Team Agents

Team agents orchestrate multiple specialised agents to solve complex tasks through coordinated execution and built-in quality control. They inherit all capabilities of individual agents and add multi-agent coordination on top.

Setup

pip install aixplain

from aixplain import Aixplain

aix = Aixplain(api_key="YOUR_API_KEY")

Quick start

web_search_tool = aix.Tool.get("tavily/tavily-search-api")

researcher = aix.Agent(
    name="Researcher",
    description="Searches for information and gathers data.",
    tools=[web_search_tool],
)

writer = aix.Agent(
    name="Writer",
    description="Writes clear, well-structured reports.",
    output_format="markdown",
)

team = aix.Agent(
    name="Research and Writing Team",
    description="Researches topics and produces written reports.",
    agents=[researcher, writer],
)
team.save(save_subcomponents=True)

response = team.run(query="Research quantum computing and write a summary.")
print(response.data.output)

Show output

note

A team agent is an Agent — there is no separate TeamAgent class. Passing agents=[...] is what turns an agent into a team. Subagent names must be unique in your workspace; reusing one raises err.name_already_exists.

How it works

A team agent is composed of subagents (workers) and a set of built-in micro-agents (coordination layer):

Micro-agent	Role
Planner	Breaks the goal into a structured task plan
Orchestrator	Routes tasks to the right subagent
Inspector	Runtime guardrail that validates quality at input, step, and output checkpoints. See Inspectors.

The Planner and Orchestrator see each subagent's name and description and delegate work to a subagent by name. A subagent's own tools are encapsulated — they are not exposed to the coordination layer. Tools attached to the team itself are visible to the Planner with their full parameter schemas, since the Planner can call them directly.

Execution flow

1. INPUT          → User query enters the team

2. PLANNING
   ├─> Autonomous: Planner builds a task graph on the fly
   └─> Structured: Orchestrator follows predefined task dependencies

3. EXECUTION LOOP ⟲
   ├─> Orchestrator selects the next task with completed dependencies
   ├─> Subagent executes the task using its tools
   ├─> Inspector evaluates result quality
   │   └─> CONTINUE | RERUN | ABORT | EDIT
   └─> Repeat until a terminal task (one with no successors) completes

4. RETURN         → The team returns the final answer from the terminal task

Execution modes

Autonomous coordination (default)

The Planner dynamically plans and assigns work at runtime. No tasks need to be defined upfront:

note

# replaces: CrewAI Crew + role definitions + process configuration
# agents= replaces the crew metaphor; delegation happens at runtime

team = aix.Agent(
    name="Research Team",
    description="Research topics, analyse findings, and write reports.",
    agents=[researcher, writer],
)
team.save(save_subcomponents=True)

response = team.run(query="Research quantum computing trends.")
print(response.data.output)

Show output

Best for exploratory workflows and complex problems where the approach should adapt to intermediate results.

Structured workflow with tasks

Define explicit task dependencies for deterministic, auditable execution. The Orchestrator runs a task only once every task it depends on has completed:

# 1. Define tasks
find_leads = aix.Agent.Task(
    name="find_leads",
    instructions="Generate a list of leads in the EdTech industry.",
    expected_output="List of companies with contact info.",
)

analyze_leads = aix.Agent.Task(
    name="analyze_leads",
    instructions="Prioritise leads based on alignment with an AI platform.",
    expected_output="Qualified and prioritised lead list.",
    dependencies=[find_leads],  # runs after find_leads
)

# 2. Assign tasks to subagents
lead_finder = aix.Agent(
    name="Lead Finder",
    description="Finds EdTech leads using web search.",
    tasks=[find_leads],
    tools=[web_search_tool],
)

lead_analyzer = aix.Agent(
    name="Lead Analyzer",
    description="Qualifies and prioritises leads.",
    tasks=[analyze_leads],
)

# 3. Create and run the team
team = aix.Agent(
    name="Lead Generation Team",
    description="Generate and qualify EdTech leads.",
    agents=[lead_finder, lead_analyzer],
)
team.save(save_subcomponents=True)

response = team.run(query="Identify and qualify EdTech leads for an AI learning platform.")
print(response.data.output)

Show output

The dependency drives execution order: find_leads runs first, and its output feeds analyze_leads, whose result becomes the team's final answer.

Best for repeatable processes and regulated workflows where execution order must be guaranteed.

Task constraints:

• Dependencies must form a DAG — no circular references.
• A task runs only when all its dependencies have completed.
• If any subagent has a task assigned, every subagent must have at least one.

Modes compared

	Autonomous	Structured
Planning	Planner creates task graph at runtime	Fixed dependencies defined upfront
Execution order	Adaptive	Guaranteed
Best for	Exploratory, complex problems	Repeatable, auditable workflows

Configuration

team = aix.Agent(
    name="Research Team",                           # required
    agents=[researcher, writer, analyst],           # required — list of Agent objects
    description="Conducts research and writes reports.",
    instructions="Always cite sources. Prioritise recent data. Use clear, professional language.",
    llm="model-path",                               # LLM used by the Planner and Orchestrator
    output_format="markdown",                       # text | markdown | json
    expected_output='{"summary": "string"}',        # required when output_format="json"
)

instructions steer the Planner's task breakdown and the team's overall behaviour. Keep each subagent's description distinct so the Orchestrator can route work correctly.

Task configuration

task = aix.Agent.Task(
    name="data_collection",                         # required — unique identifier
    instructions="Collect sales data from last quarter using available tools.",  # required
    expected_output="CSV with sales transactions and metadata.",                 # required
    dependencies=[auth_task, validation_task],      # optional — tasks that must finish first
)

Runtime parameters

Team agents accept the same runtime parameters as individual agents. The one knob worth tuning per team is max_iterations: it defaults to 5, the same as a single agent, but a multi-agent plan takes more reasoning steps, so raise it for teams.

response = team.run(
    query="Research and summarise AI safety developments.",
    session_id="team-session-123",
    max_tokens=2000,
    max_iterations=30,      # default is 5 — raise it for multi-step team plans
    progress_format="status",
    progress_verbosity=1,
    timeout=600,
)
print(response.data.output)

Show output

For the full runtime-parameter table (session_id, history, variables, progress_*, timeout, and more), see the Agents page — every parameter there applies to teams unchanged.

Tracing team execution

Each entry in response.data.steps records which subagent ran (agent) and which model or tool it invoked (unit), along with its input, output, thought, and status:

response = team.run(query="Research and analyse AI trends.")

print("Status: ", response.status)
print("Runtime:", response.run_time, "s")
print("Credits:", response.used_credits)

for i, step in enumerate(response.data.steps or []):
    agent = step.get("agent")
    agent = agent.get("name") if isinstance(agent, dict) else agent
    unit  = step.get("unit")
    unit  = unit.get("name") if isinstance(unit, dict) else unit

    print(f"\n--- Step {i+1}: {agent} → {unit} ---")
    if step.get("thought"):
        print("Thought:", str(step["thought"])[:200])
    if step.get("input"):
        print("Input:  ", str(step["input"])[:200])
    if step.get("output"):
        print("Output: ", str(step["output"])[:200])
    print("Status: ", step.get("status"), "· Credits:", step.get("used_credits"))

Show output

note

task and action appear on steps only when running on the V3 engine with tasks configured; on the default engine they return None. The agent, unit, input, output, thought, status, and used_credits fields are always present. See Agents → Inspecting steps for the full field reference.

Save and update

Always pass save_subcomponents=True when saving a team — this persists the subagents alongside the team:

team.output_format = "markdown"
team.save(save_subcomponents=True)

Troubleshooting

agent reached the maximum number of iterations max_iterations defaults to 5. Multi-agent plans run more steps than a single agent, so raise it for teams:

team.max_iterations = 50
team.save()

Failed to save … err.name_already_exists A subagent's name collides with an existing agent in your workspace. Give each subagent a unique name before saving.

Team not coordinating well Review the team description and instructions — these guide the Planner's task breakdown. Ensure each subagent's description clearly differentiates its capabilities so the Orchestrator can route tasks correctly. Inspect response.data.steps to see how work was assigned.

A subagent is never used In autonomous mode, verify the subagent's description is distinct enough for the Planner to identify when it's needed. In structured mode, confirm the subagent has a task assigned.

Tasks execute in the wrong order Check that all dependencies are correctly declared. A task runs only when every dependency in its list has completed — a missing dependency declaration is the most common cause.

model response was cut off because the maximum token limit was reached Raise the LLM's persistent token cap:

llm = aix.Model.get("openai/gpt-5.4")
llm.inputs.max_tokens = 100_000
team.llm = llm
team.save()

Team response is cropped The team's own max_tokens (default 2048) caps the final output independently of the LLM cap:

team.max_tokens = 20_000
team.save()