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)
How it works
A team agent is composed of subagents (workers) and a set of built-in micro-agents (coordination layer):
| Micro-agent | Role |
|---|---|
| Mentalist | Breaks the goal into a structured task plan |
| Orchestrator | Routes tasks to the right subagent |
| Inspector | Validates output quality; returns CONTINUE, RETRY, or ABORT |
| Response Generator | Synthesises the final user-facing response |
The Mentalist and Orchestrator see each subagent's name, description, and the names and descriptions of its tools — presented in XML for structured reasoning. They do not see tool internal parameters; those are only visible to the subagent that calls them.
Execution flow
1. INPUT → User query enters the team
2. PLANNING
├─> Autonomous: Mentalist creates 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 | RETRY | ABORT
└─> Repeat until plan reaches FINISH
4. SYNTHESIS → Response Generator produces the final answer
Execution modes
Autonomous coordination (default)
The Mentalist dynamically plans and assigns work at runtime. No tasks need to be defined upfront:
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)
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:
# 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)
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 | Mentalist 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 Mentalist and Orchestrator
output_format="markdown", # text | markdown | json
expected_output='{"summary": "string"}', # required when output_format="json"
)
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 key difference is the default for max_iterations:
response = team.run(
query="Research and summarise AI safety developments.",
session_id="team-session-123",
max_tokens=2000,
max_iterations=30, # teams default to 30; single agents default to 5
progress_format="status",
progress_verbosity=1,
timeout=600,
)
print(response.data.output)
Tracing team execution
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 []):
print(f"\n--- Step {i+1}: {step.get('agent')} ---")
print("Task:", step.get("task")) # assigned task name
print("Thought:", step.get("thought")) # Inspector feedback
print("Action:", step.get("action")) # CONTINUE / RETRY / ABORT
print("Reason:", step.get("reason"))
for ts in step.get("tool_steps") or []:
print(" Tool:", ts.get("tool"))
print(" Input:", ts.get("input"))
print(" Output:", str(ts.get("output"))[:200], "…")
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
Teams default to max_iterations=30. Raise it for complex multi-step workflows:
team.max_iterations = 50
team.save()
Team not coordinating well
Review the team description and instructions — these guide the Mentalist's planning. Ensure each subagent's description clearly differentiates its capabilities so the Orchestrator can route tasks correctly. Inspect response.data.steps to see how tasks were assigned.
A subagent is never used
In autonomous mode, verify the subagent's description is distinct enough for the Mentalist 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-4o")
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()