Skip to main content
Pro Feature - Oracle Research Agent is available exclusively on Pro plans.

​
Overview

Oracle Research Agent is Nia’s autonomous research assistant that conducts deep investigations across codebases, documentation, and the web. It serves as a specialized “second brain” for external knowledge needs and technical research.

​
Key Capabilities

Oracle is powered by the Nia API and includes:
  • Web search - Find information across the internet
  • Code search - Search through repository code
  • Documentation search - Query documentation sources
  • Doc filesystem tools - Navigate documentation with doc_tree, doc_ls, doc_read, doc_grep
  • Package source code analysis - Explore PyPI, NPM, Crates.io, Go modules
  • Context preservation - Organize findings for handoff to main agents

​
Research Strategy

Oracle follows a progressive 3-step research pattern:
1

DISCOVER

  • Use nia_web_search for quick lookups and discovery
  • Use nia_deep_research_agent for complex analysis, comparisons, and pros/cons evaluation
2

INDEX

  • Automatically index discovered resources
  • Monitor status during indexing process
3

SEARCH

  • Use search_codebase, search_documentation, regex_search
  • Use read_source_content for specific file analysis

​
Execution Methods

​
1. Direct Streaming (Real-time)

Use the /v2/oracle endpoint with SSE streaming for immediate results: 
curl --request POST \
  --url https://apigcp.trynia.ai/v2/oracle \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "query": "How does authentication work in the FastAPI codebase?",
    "repositories": ["fastapi/fastapi"],
    "data_sources": ["FastAPI Documentation"],
    "output_format": "markdown report with code examples",
    "model": "claude-opus-4-5-20251101"
  }'
Create asynchronous jobs via Hatchet workflow for better reliability: Benefits:
  • Queues jobs for reliable execution
  • Supports concurrency limits per user
  • Enables reconnection to running jobs
  • Provides job status tracking and history
Workflow:
  1. Create job: POST /v2/oracle/jobs
  2. Subscribe to updates: GET /v2/oracle/jobs/{job_id}/stream (SSE)
  3. Check status: GET /v2/oracle/jobs/{job_id}

​
Real-time Event Types

Both execution methods provide real-time streaming events:
Event TypeDescription
iteration_startNew research iteration beginning
tool_startTool execution starting (includes action, args, reason)
tool_completeTool finished with success/failure status
generating_reportFinal report synthesis starting
completeResearch finished with full result
heartbeatConnection keep-alive (every 0.5s during idle)
errorError occurred during research
workflow_eventHatchet workflow state changes (job-based only)

​
Example Workflows

User Query: “Find popular JWT libraries for Python”Oracle Workflow:
  1. nia_web_search("popular JWT libraries Python")
  2. Review results for top candidates
  3. Auto-index top 2-3 repositories
  4. search_codebase for implementation patterns
  5. Present findings with sources

​
Additional Features

  • Chat with results: Follow up on research with /v2/oracle/sessions/{session_id}/chat
  • View history: List past sessions with /v2/oracle/history
  • Session details: Get full session info with /v2/oracle/sessions/{session_id}
  • Message history: Retrieve chat messages with /v2/oracle/sessions/{session_id}/messages

​
Response Format

Completed research includes:
  • Final report (markdown or specified format)
  • Citations with source IDs and summaries
  • Tool call history
  • Iteration count and duration
  • Session ID for follow-ups