Orchestrator example

[git-hari-j]

@KennyVaneetvelde Hello. First of all thanks for the awesome agentic-framework.

I am looking to use atomic-agents to create an orchestration example. Let me explain the scenario
I have a main py file that accepts user requests via the terminal. It runs it through the orchestrator agent to determine which agent to call, say search agent. The search agent should in turn call SearxNGSearchTool. Output of the tool should be fed back to the main agent after passing through search agent > orchestrator agent > main agent

Flow (my expectatation)
User input (in main py file) > Call orchestrator agent > based on user input it is determined to call the search agent > call search agent with user input > search agent invokes searchXNG tool and runs the search > Response from searxng is fed back to search agent > response frm search agent output schema fed back to orchestrator agent > response frm orchestrator agent output schema fed back to main py file

Can you validate if this is the sequence of steps? I am unable to understand the link between the agent and tool. How do i call the tool from the agent and send back response up the ladder. Any clarifications are welcome

[KennyVaneetvelde]

Hey, that's a great question! Your understanding of the flow is spot on. That sequence is exactly the kind of powerful, multi-step reasoning you can build with atomic-agents.

You've hit on the core design principle of the framework: Agents decide, your code executes.

The "missing link" you're looking for isn't inside the agent itself. An agent's primary job is to receive input and use the model to output a structured response that follows a specific Pydantic schema. It's your application logic that takes this structured output and then calls the appropriate tool. The tool's output is then fed back to an agent (either the same one or a different one) to be processed into a final answer.

The orchestration-agent example is the most direct answer to your question. The orchestrator_agent is designed to choose between different tools.

First, the agent's job is to decide the tool. The agent's output_schema is a Union of the input schemas for all the tools it can choose from. This is the key to how it makes a decision.

Here's the OrchestratorOutputSchema from atomic-examples/orchestration-agent/orchestration_agent/orchestrator.py:

class OrchestratorOutputSchema(BaseIOSchema):
    """Combined output schema for the Orchestrator Agent. Contains the tool to use and its parameters."""

    tool: str = Field(..., description="The tool to use: 'search' or 'calculator'")
    tool_parameters: Union[SearxNGSearchToolInputSchema, CalculatorToolInputSchema] = Field(
        ..., description="The parameters for the selected tool"
    )

When you run this agent, it doesn't execute the tool. It just populates this OrchestratorOutputSchema object, telling you which tool to use (tool) and the exact parameters for it (tool_parameters).

As an aside, we don't strictly need the tool field. We could just inspect the type of the tool_parameters field to decide which tool to run. However, having the explicit tool field can make the code easier to read and understand, which is why it's included in the demo.

Then, your application executes the tool. Your main application code receives this OrchestratorOutputSchema object and uses it to call the correct tool's .run() method. This is the "link" between the agent and the tool. You can see this in atomic-examples/orchestration-agent/orchestration_agent/orchestrator.py:

def execute_tool(
    searxng_tool: SearxNGSearchTool, calculator_tool: CalculatorTool, orchestrator_output: OrchestratorOutputSchema
) -> Union[SearxNGSearchToolOutputSchema, CalculatorToolOutputSchema]:
    if orchestrator_output.tool == "search":
        return searxng_tool.run(orchestrator_output.tool_parameters)
    elif orchestrator_output.tool == "calculator":
        return calculator_tool.run(orchestrator_output.tool_parameters)
    else:
        raise ValueError(f"Unknown tool: {orchestrator_output.tool}")

Finally, the tool output is fed back to the agent to get a polished, natural language response. Notice how the main loop in orchestrator.py does this:

• It runs the agent once to get the OrchestratorOutputSchema.
• It executes the selected tool.
• It then adds the tool's output to the agent's memory as a system message.
• It temporarily swaps the agent's output schema to a FinalAnswerSchema.
• It runs the agent a second time. Now, the agent has the full context (original query + tool output) and is tasked with generating a user-friendly final_answer.

Here's the code from atomic-examples/orchestration-agent/orchestration_agent/orchestrator.py that does this:

# ... after running the tool and getting the `response`
orchestrator_agent.output_schema = FinalAnswerSchema
orchestrator_agent.memory.add_message("system", response)
final_answer = orchestrator_agent.run(input_schema)
console.print(f"\n[bold blue]Final Answer:[/bold blue] {final_answer.final_answer}")

The deep-research example showcases the multi-agent flow you described. There isn't one single orchestrator, but a sequence of specialized agents and tools chained together in main.py.

The flow looks like this:

1. choice_agent.run(): First, an agent decides if a search is even necessary.
2. query_agent.run(): If so, another agent generates optimized search queries.
3. searxng_search_tool.run(): The tool is executed directly with the generated queries.
4. webpage_scraper_tool.run(): Another tool is run on the search results.
5. Update Context: The scraped content is loaded into a ScrapedContentContextProvider. This is a key step – the results are made available to the next agent via the system prompt.
6. question_answering_agent.run(): Finally, the main QA agent takes the original question and, using the information now in its context, generates the final answer.

This pattern perfectly matches your expectation of agents calling other agents (or rather, the output of one agent being the input for the next) and then ultimately calling tools. The "ladder" is the main application loop that passes the data from one step to the next.

Your intuition is correct! The framework is designed for you to implement this orchestration logic in your main application code, giving you full control over the flow. The orchestration-agent is a great starting point for a tool-selection pattern, while deep-research is an excellent example of a sequential, multi-agent pipeline.

[git-hari-j]

Thank you @KennyVaneetvelde . An additional question, how do we address a Human-In-Loop scenario in case of research.