Skip to main content

Multi-Agent Teams

Multi-agent teams let you deploy several specialized agents behind one chat app.

Use this when one assistant should route questions to different specialists, such as billing, support, data analysis, product documentation, or file-based knowledge tasks.

When to Use Multi-Agent Teams​

Use a multi-agent team when:

  • Different questions should be handled by different instructions.
  • Each agent has a clear topic area.
  • One agent needs a data source that other agents do not need.
  • You want the response to show which agent handled the request.

For a single assistant with one prompt and one set of knowledge files, use the Custodian Class or Create Your First Assistant instead.

Core Objects​

ObjectPurpose
AgentDefines one specialized assistant with a name, prompt, topics, and optional data source files.
AgentTeamGroups multiple agents and defines the routing mode.
TeamAppThe deployed team app returned by team.deploy(). Use it to chat with the team.

Create a Team​

This example uses the sample pattern from the SDK repository:

from custodian_labs import Agent, AgentTeam

team = AgentTeam(
    agents=[
        Agent(
            name="billing",
            model="gpt-4o",
            system_prompt="Answer billing questions.",
            topics=["billing", "invoice", "refund", "payment"],
        ),
        Agent(
            name="data",
            model="gpt-4o",
            system_prompt="Answer questions about the uploaded CSV file.",
            topics=["data", "csv", "customer", "file"],
        ).add_data_source_file("sample_pii_data.csv"),
    ],
    routing_mode="single",
)

app = team.deploy()

reply = app.chat("How many people are in the uploaded file and which cities do they live in?")
if reply is not None:
    print(reply.response)
    print(reply.selected_agent)

How Routing Works​

Each Agent includes topics. The team uses these topics, along with the user's message, to decide which agent should handle the request.

In the example above:

  • Billing questions can route to the billing agent.
  • CSV or customer-data questions can route to the data agent.
  • The data agent has its own uploaded file.

The response may include selected_agent, which helps you inspect which agent answered.

Routing Modes​

ModeBehaviorUse when
singleSelects one agent to answer the request.Most teams where one specialist should handle each message.
chainAllows multiple handoffs within the team, up to max_handoffs.More complex workflows where agents may need to pass work between each other.

If you are unsure, start with routing_mode="single".

Add a Data Source to One Agent​

Call .add_data_source_file() on the agent that should use the file:

Agent(
    name="data",
    model="gpt-4o",
    system_prompt="Answer questions about the uploaded CSV file.",
    topics=["data", "csv", "customer", "file"],
).add_data_source_file("sample_pii_data.csv")

This keeps the file scoped to that agent's role.

For general RAG behavior, see Data Sources and RAG.

Team Requirements​

When creating a team:

  • Include at least one agent.
  • Give every agent a unique name.
  • Use the same API key and base URL across all agents in the same team.
  • Choose routing_mode="single" or routing_mode="chain".

If a team is misconfigured, the SDK raises a validation error before deployment.

Chat with a Team​

After deployment, call .chat() on the returned team app:

reply = app.chat("Can you help with a refund question?")

if reply is not None:
    print(reply.response)
    print(reply.selected_agent)

Like regular apps, team apps keep a session ID on the app instance. Use app.reset_session() to start a fresh conversation.

Next Steps​