Agentic Architecture
########################

RECAP uses an orchestrator-tool based multiagent orchestrator. The Orchestrator Agent
recieves user requests and delegates specialized tasks to pther agents exposed as tools
to orchestrator. 

This design allows new agents to be developed, tested and easily added into the larger
workflow. 

.. image:: _static/agents.png
   :width: 1403px
   :height: 931px
   :scale: 50 %

Orchestrator
************

This agent is responsible for coordinating responses to user queries. It utilizes tool calls 
to delegeate tasks to subagents and synthesize the results into a helpful response.

The orchestrator is initialized with a system prompt, Langchain Model and optionally
a set of tool agents. See example below:

.. code-block:: python

    from recap.agents import Orchestrator, SummaryAgent
    from langchain_ollama import ChatOllama

    # Initialize Langchain Model for orchestrator to use
    model = ChatOllama(
        model="gemma4:e4b",
        temperature=0,
        num_ctx=(2048 * 4),
        base_url=os.getenv("OLLAMA_BASE_URL"),
    )  # Test with smaller gemma3:1b or gemma3:4b

    # Orchestrator no tools
    orchestrator_agent = Orchestrator(model=model)

    # Orchestrator with summary agent as tool
    orchestrator_agent = Orchestrator(
        model=model,
        tools=[summary_agent.as_tool()],
    )

You are then able to invoke the orchestrator with conversation history

.. code-block:: bash

    messages.append(("user", user_query))
    response = orchestrator_agent.invoke({"messages": ("user", "Can you tell me about papers from 2018")})
    last_message = response["messages"][-1]
    print(last_message.content)


This module design allows new tools and agents to be developed to extend orchestrator agent capabilities.
Additionally, sub agents can use other agents as tools, enabling nested multi-agent workflows.

Tool Agents
***********

The repository also includes other agents that can be utilized as tools:

- **ChromaRetrievalAgent** - Retrieves paper reviews from the Chroma database.
  It supports both semantic search over review text and metadata filtering
  (for example by year, decision, or paper ID). For large result sets, the
  agent stores the complete results as an artifact and returns a reference
  along with a representative sample.

- **SummaryAgent** - Produces concise summaries of one or more review
  documents using the TextRank summarization algorithm. It is useful for
  condensing retrieval results before presenting them to a user or passing
  them to another agent.

- **AnalyticsAgent** - Performs analytical operations over retrieval results.
  It generates an execution plan from a natural language request and executes
  operations such as grouping, aggregation (for example mean, sum, min, and
  max), sorting, value counts, and top-*k* selection.

- **VisualizationAgent** - Generates Chart.js specifications from structured
  data. It is typically used after the analytics agent to transform aggregated
  results into bar or pie chart configurations that can be rendered by a

Each agent can be converted into a LangChain ``StructuredTool`` using
``BaseAgent.as_tool()``. The returned tool can then be supplied to another
BaseAgent, allowing for complex extensible multiagent workflows

See :doc:`tutorials/building_new_tool_agent` for more information about creating new agents.