Multi-Agent Collaboration

Creating and orchestrating multiple agents.

Supervisor-Collaborator Multi-Agent

This example demonstrates how to create and orchestrate multiple agents that collaborate to accomplish a task.

We have a marketing workflow with three agents: 1. A Trend Analyzer collaborator agent that researches trending keywords given a topic. 2. A Content Writer collaborator agent that writes a blog using the trending keywords. 3. A Marketing Director supervisor agent that orchestrates the above two agents and handles sending an email to the user.

The user interacts with the Marketing Director agent (as the single point of contact).

multi_agents.py

import json
from oci.addons.adk import Agent, AgentClient, tool

@tool
def get_trending_keywords(topic):
    """ Get the trending keywords for a given topic. """
    # Here is a mock implementation
    return json.dumps({"topic": topic, "keywords": ["agent", "stargate", "openai"]})

@tool
def send_email(recipient, subject, body):
    """ Send an email to a recipient. """
    # Here is a mock implementation
    print("Sending email to ", recipient, "with subject", subject, "and body", body)
    return "Sent!"

def main():

    # A shared client for all agents
    client = AgentClient(
        auth_type="api_key",
        profile="DEFAULT",
        region="us-chicago-1"
    )

    # trend analyzer collaborator agent
    trend_analyzer = Agent(
        name="Trend Analyzer",
        instructions="You use the tools provided to analyze the trending keywords of given topics.",
        agent_endpoint_id="ocid1.genaiagentendpoint...",
        client=client,
        tools=[
            get_trending_keywords,
        ]
    )

    # content writer collaborator agent
    content_writer = Agent(
        name="Content Writer",
        instructions="You write a mini blog post (4 sentences) using the trending keywords.",
        agent_endpoint_id="ocid1.genaiagentendpoint...",
        client=client,
    )

    # marketing director supervisor agent
    marketing_director = Agent(
        name="Marketing Director",
        instructions="You ask the trend analyzer for trending keywords and "
         + " You then ask the content writer to write a blog post using the trending keywords. "
         + " You then send email to 'jane.doe@example.com' with the blog post."
         + " Then summarize the actions you took and reply to the user.",
        agent_endpoint_id="ocid1.genaiagentendpoint...",
        client=client,
        tools=[
            trend_analyzer.as_tool(
                tool_name="analyze_trending_keywords",
                tool_description="Analyze the trending keywords of given topics",
            ),
            content_writer.as_tool(
                tool_name="write_blog_post",
                tool_description="Write a blog post using the trending keywords.",
            ),
            send_email,
        ]
    )

    # Set up the agents once
    trend_analyzer.setup()
    content_writer.setup()
    marketing_director.setup()

    # Use the supervisor agent to process the end user request
    input = "Produce a blog post about current trends in the AI industry."
    response = marketing_director.run(input, max_steps=5)
    response.pretty_print()


if __name__ == "__main__":
    main()

The as_tool() method is a convenience method that allows you to pass the collaborator agent as a tool to the supervisor agent.

Passing the agent object directly to the tools

Alternatively, you may pass the agent object directly to the tools parameter of the Agent constructor of the supervisor agent.

marketing_director = Agent(
    name="Marketing Director",
    instructions="...",
    agent_endpoint_id="ocid1.genaiagentendpoint...",
    client=client,
    tools=[
        trend_analyzer, # pass the agent object directly
        content_writer, # pass the agent object directly
        send_email,
    ]
)

This is equivalent to invoking the collaborator agent's as_tool() method, without specifying your custom tool name and tool description. The ADK uses the collaborator agent's name as the tool name and the collaborator agent's description as the tool description.

---

Note: We recommend using the as_tool() method to pass the collaborator agent as a tool to the supervisor agent. This approach gives you more explicit control over the tool name and tool description which are important for LLM to understand the tools.

---

How it works

We are using the agent as a tool pattern to implement the hierarchical multi-agent workflow.

1. The supervisor agent can invoke the collaborator agent's run method as tool.
2. The supervisor agent receives run response from the collaborator agent.
3. The supervisor decides what to do next based on the collaborator agent's response.

What as_tool() method does is to convert the collaborator agent's run() method into a function tool that can be used by the supervisor agent.

Orchestration using LLM

By making a collaborator agent as a tool, we essentially use the supervisor agent's LLM's tool use capabilities to orchestrate the multi-agent workflow.

In this example, we're giving the supervisor lots of flexibility and agency, at the cost of giving up our ability to precisely control the flow of the workflow. To precisely control the flow of the multi-agent workflow, see the Deterministic Workflow example.