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.团队智能体本身就是一种智能体（Agent）——不存在单独的 TeamAgent 类。通过传入 agents=[...] 即可将智能体转变为团队。子智能体的名称在工作区中必须唯一；重用名称会引发 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.规划器（Planner）和编排器（Orchestrator）可以看到每个子智能体的名称和描述，并按名称将工作委派给子智能体。子智能体自身的工具是封装好的，不会暴露给协调层。附加到团队本身的工具对规划器是可见的，且包含完整的参数架构，因为规划器可以直接调用它们。

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.依赖关系驱动执行顺序：find_leads 先运行，其输出作为 analyze_leads 的输入，analyze_leads 的结果成为团队的最终答案。

Best for repeatable processes and regulated workflows where execution order must be guaranteed.最适合可重复的流程和受监管的工作流，即必须保证执行顺序的场景。

Task constraints:任务约束：

• Dependencies must form a DAG — no circular references.依赖关系必须构成有向无环图（DAG）——不得有循环引用。
• A task runs only when all its dependencies have completed.任务仅在所有依赖项完成后才会运行。
• If any subagent has a task assigned, every subagent must have at least one.如果任何子智能体被分配了任务，则每个子智能体都必须至少分配一个任务。

Planner

By default the Planner micro-agent builds the execution plan using the team llm. Pass a planner model to hand plan generation to a dedicated LLM instead: the planner reads the query, produces an execution plan of tasks, and the team executes that plan on its main llm.默认情况下，规划器微型智能体使用团队 LLM 构建执行计划。传入 planner 模型可将计划生成交给专门的 LLM 处理：规划器读取查询，生成任务执行计划，然后由团队使用其主 LLM 执行该计划。

The planner works in both execution modes. In autonomous mode it plans the task graph from the query alone. When tasks are defined, the planner optimises how those tasks are sequenced and delegated. The planner can be a different model than the llm that executes the work.规划器在两种执行模式下均可工作。在自主模式下，它仅根据查询规划任务图。当定义了任务时，规划器会优化这些任务的排序和委派。规划器可以使用与执行工作的 LLM 不同的模型。

planner_llm = aix.Model.get("openai/gpt-4.1-nano")

team = aix.Agent(
    name="Research Team",
    description="Research topics, analyse findings, and write reports.",
    llm="openai/gpt-5.4",       # executes the plan
    planner=planner_llm,        # generates the execution plan
    agents=[researcher, writer],
)
team.save(save_subcomponents=True)

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

Show output

The plan is generated by planner_llm, while execution runs on the team llm. Inspect response.data.steps to confirm the plan-generation step is attributed to the planner model rather than the main LLM.计划由 planner_llm 生成，而执行则在团队 LLM 上运行。检查 response.data.steps 以确认计划生成步骤归属于规划器模型，而非主 LLM。

Modes compared

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

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
    planner="model-path",                           # optional dedicated model for plan generation
    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 the iteration limit, set on the team's budget (budget.max_iterations): it defaults to None (no cap), the same as a single agent, but a multi-agent plan takes many reasoning steps, so set it explicitly for teams.团队智能体接受与单个智能体相同的运行时参数。每个团队值得调整的一个关键参数是迭代限制，设置在团队的预算中（budget.max_iterations）：其默认值为 None（无上限），与单个智能体相同，但多智能体计划涉及许多推理步骤，因此请为团队显式设置该值。

# Iteration limits live on the budget. Set it before run() to apply to that run.
team.budget.max_iterations = 30   # uncapped by default; set it for multi-step team plans

session = aix.Session(agent=team, name="AI safety research")
session.save()

response = team.run(
    query="Research and summarise AI safety developments.",
    session=session,
    progress_format="status",
    progress_verbosity=1,
    timeout=600,
)
print(response.data.output)

Show output

A Session binds to the team agent exactly as it does to a single agent, so session.agent_id is the team's id and the transcript covers the whole team's turns.会话（Session）绑定到团队智能体的方式与绑定到单个智能体完全相同，因此 session.agent_id 是团队的 ID，而转录内容涵盖了整个团队的轮次。

For the full runtime-parameter table (session, history, variables, progress_*, timeout, and more), see the Agents page. Every parameter there applies to teams unchanged.关于完整的运行时参数表（session、history、variables、progress_*、timeout 等），请参阅“智能体”页面。其中的每个参数都适用于团队，且无需更改。

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.data.steps 中的每个条目都记录了运行的子智能体（agent）和调用的模型或工具（unit），以及其输入、输出、思考过程和状态：

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.task 和 action 仅在配置了任务并运行在 V3 引擎上时才会出现在步骤中；在默认引擎上它们返回 None。agent、unit、input、output、thought、status 和 used_credits 字段始终存在。有关完整的字段参考，请参阅“智能体”→“检查步骤”。

Save and update

Always pass save_subcomponents=True when saving a team — this persists the subagents alongside the team:保存团队时请务必传入 save_subcomponents=True —— 这会将子智能体与团队一并持久化：

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

Troubleshooting

agent reached the maximum number of iterations - The iteration limit defaults to 5. Multi-agent plans run more steps than a single agent, so raise it through the budget for teams:智能体达到了最大迭代次数 —— 迭代限制默认为 5。多智能体计划运行的步骤比单个智能体多，因此请通过团队预算增加该值：

team.budget.max_iterations = 50
team.save()

Failed to save … err.name_already_exist - A subagent's name collides with an existing agent in your workspace. Give each subagent a unique name before saving.保存失败 … err.name_already_exist —— 子智能体的名称与工作区中现有的智能体冲突。保存前请为每个子智能体赋予唯一名称。

Team not coordinating well - Review the team description and instructions, which 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.团队协调不佳 —— 检查团队描述和指令，它们指导了规划器的任务拆解。确保每个子智能体的描述能清晰区分其能力，以便编排器正确路由任务。检查 response.data.steps 以查看工作是如何分配的。

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 的持久令牌上限：

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:团队响应被裁剪 —— 团队自身的 max_tokens（默认 2048）独立于 LLM 上限限制了最终输出：

team.max_tokens = 20_000
team.save()