docs/api/agents.md

Agents API Reference

This page documents the API for DeepCritical agents.

KnowledgeGapAgent

Module: src.agents.knowledge_gap

Purpose: Evaluates research state and identifies knowledge gaps.

Methods

evaluate

async def evaluate(
    self,
    query: str,
    background_context: str,
    conversation_history: Conversation,
    iteration: int,
    time_elapsed_minutes: float,
    max_time_minutes: float
) -> KnowledgeGapOutput

Evaluates research completeness and identifies outstanding knowledge gaps.

Parameters:

• query: Research query string
• background_context: Background context for the query
• conversation_history: Conversation history with previous iterations
• iteration: Current iteration number
• time_elapsed_minutes: Elapsed time in minutes
• max_time_minutes: Maximum time limit in minutes

Returns: KnowledgeGapOutput with:

• research_complete: Boolean indicating if research is complete
• outstanding_gaps: List of remaining knowledge gaps

ToolSelectorAgent

Module: src.agents.tool_selector

Purpose: Selects appropriate tools for addressing knowledge gaps.

Methods

select_tools

async def select_tools(
    self,
    query: str,
    knowledge_gaps: list[str],
    available_tools: list[str]
) -> AgentSelectionPlan

Selects tools for addressing knowledge gaps.

Parameters:

• query: Research query string
• knowledge_gaps: List of knowledge gaps to address
• available_tools: List of available tool names

Returns: AgentSelectionPlan with list of AgentTask objects.

WriterAgent

Module: src.agents.writer

Purpose: Generates final reports from research findings.

Methods

write_report

async def write_report(
    self,
    query: str,
    findings: str,
    output_length: str = "medium",
    output_instructions: str | None = None
) -> str

Generates a markdown report from research findings.

Parameters:

• query: Research query string
• findings: Research findings to include in report
• output_length: Desired output length ("short", "medium", "long")
• output_instructions: Additional instructions for report generation

Returns: Markdown string with numbered citations.

LongWriterAgent

Module: src.agents.long_writer

Purpose: Long-form report generation with section-by-section writing.

Methods

write_next_section

async def write_next_section(
    self,
    query: str,
    draft: ReportDraft,
    section_title: str,
    section_content: str
) -> LongWriterOutput

Writes the next section of a long-form report.

Parameters:

• query: Research query string
• draft: Current report draft
• section_title: Title of the section to write
• section_content: Content/guidance for the section

Returns: LongWriterOutput with updated draft.

write_report

async def write_report(
    self,
    query: str,
    report_title: str,
    report_draft: ReportDraft
) -> str

Generates final report from draft.

Parameters:

• query: Research query string
• report_title: Title of the report
• report_draft: Complete report draft

Returns: Final markdown report string.

ProofreaderAgent

Module: src.agents.proofreader

Purpose: Proofreads and polishes report drafts.

Methods

proofread

async def proofread(
    self,
    query: str,
    report_title: str,
    report_draft: ReportDraft
) -> str

Proofreads and polishes a report draft.

Parameters:

• query: Research query string
• report_title: Title of the report
• report_draft: Report draft to proofread

Returns: Polished markdown string.

ThinkingAgent

Module: src.agents.thinking

Purpose: Generates observations from conversation history.

Methods

generate_observations

async def generate_observations(
    self,
    query: str,
    background_context: str,
    conversation_history: Conversation
) -> str

Generates observations from conversation history.

Parameters:

• query: Research query string
• background_context: Background context
• conversation_history: Conversation history

Returns: Observation string.

InputParserAgent

Module: src.agents.input_parser

Purpose: Parses and improves user queries, detects research mode.

Methods

parse_query

async def parse_query(
    self,
    query: str
) -> ParsedQuery

Parses and improves a user query.

Parameters:

• query: Original query string

Returns: ParsedQuery with:

• original_query: Original query string
• improved_query: Refined query string
• research_mode: "iterative" or "deep"
• key_entities: List of key entities
• research_questions: List of research questions

Factory Functions

All agents have factory functions in src.agent_factory.agents:

def create_knowledge_gap_agent(model: Any | None = None) -> KnowledgeGapAgent
def create_tool_selector_agent(model: Any | None = None) -> ToolSelectorAgent
def create_writer_agent(model: Any | None = None) -> WriterAgent
def create_long_writer_agent(model: Any | None = None) -> LongWriterAgent
def create_proofreader_agent(model: Any | None = None) -> ProofreaderAgent
def create_thinking_agent(model: Any | None = None) -> ThinkingAgent
def create_input_parser_agent(model: Any | None = None) -> InputParserAgent

Parameters:

• model: Optional Pydantic AI model. If None, uses get_model() from settings.

Returns: Agent instance.

See Also

• Architecture - Agents - Architecture overview
• Models API - Data models used by agents