Team agents

Team agents are multi-agent systems built on aiXplain that coordinate several specialized agents to solve complex tasks. They allow you to assign different agents to different subtasks, plan execution dynamically, monitor agent responses, and validate outputs.

Team agents embed micro agents that handle planning, orchestration, validation, and response generation.

How they work

A team agent orchestrates a group of micro agents and user-defined agents:

Mentalist (planner): Breaks down the user query into actionable tasks and agents.
Orchestrator: Decides and manages the flow of which agent handles which task next.
User-define agent(s): Perform specialized tasks using tools, memory, and reasoning.
inspector(s): Review reasoning steps and/or final output for accuracy, compliance, and quality.
Feedback Combiner: Consolidates inspection feedback for further orchestration decisions.
Response Generator: Synthesizes the final user answer based on intermediate steps, outputs, and inspections.

Lifecycle

create() → run() → deploy() → save() → delete()

note

Use TeamAgentFactory.list() to list all your accessible team agents, based on your API key, and TeamAgentFactory.get(<team_id>) to retrieve a specific team agent.

Creating a team agent

You create a team agent by defining the member agents and optionally linking tasks with clear dependencies.

In this example, the team agent is built to automate lead generation and qualification in the EdTech industry. It coordinates two agents:

Lead Finder, responsible for discovering potential leads using search and web scraping tools.
Lead Analyzer, responsible for evaluating and prioritizing the collected leads.

The team agent ensures that tasks are executed in the correct order — first finding leads, then analyzing them — to deliver a qualified and actionable list.

from aixplain.factories import AgentFactory, TeamAgentFactory
from aixplain.modules.agent.agent_task import AgentTask

# Step 1: Define tasks
find_leads = AgentTask(
    name="find leads",
    description="Generate a list of leads in the EdTech industry.",
    expected_output="List of companies with contact info."
)

analyze_leads = AgentTask(
    name="analyze leads",
    description="Prioritize leads based on alignment with the AI platform.",
    expected_output="A qualified and prioritized list.",
    dependencies=[find_leads]
)

# Step 2: Create task agents
lead_finder = AgentFactory.create(
    name="Lead Finder",
    description="Find EdTech leads.",
    instructions="Find EdTech leads.",
    tasks=[find_leads],
    tools=[
        AgentFactory.create_model_tool(model="6736411cf127849667606689"),  # Tavily Search
        AgentFactory.create_model_tool(model="66f423426eb563fa213a3531")   # Scrape Website
    ]
)

lead_analyzer = AgentFactory.create(
    name="Lead Analyzer",
    description="Qualify EdTech leads.",
    instructions="Qualify EdTech leads.",
    tasks=[analyze_leads]
)

# Step 3: Create and deploy the team agent
team = TeamAgentFactory.create(
    name="AI for Personalized Learning Lead Generation",
    description="Generate and qualify EdTech leads for AI-based personalized learning.",
    agents=[lead_finder, lead_analyzer]
)

team.deploy()

Parameters:

name (str): Team agent name.
description (str, optional): Short description, does not impact behaviour.
agents (List[Agent]): List of user-defined agents that will collaborate.
llm_id (str, optional): LLM ID used for micro agents.
use_mentalist (bool, optional): Enable the mentalist for planning.
use_inspector (bool, optional): Enable inspectors for reviewing execution.
num_inspectors (int, optional): Number of inspectors (default: 1, currently only one is supported).
inspector_targets (list, optional): Stages to inspect: ["steps"], ["output"], or both (default: ["steps"]).
supplier, version: Internal fields for asset management (not active).

note

Assets' name and description help agents reason about tool usage and are displayed on asset cards in Discover.

Mentalist

The mentalist is responsible for planning the execution order of tasks and assigning them to the appropriate micro agents.

When use_mentalist = True, the team agent can dynamically decide the optimal execution path based on task definitions, dependencies, and context.
When use_mentalist = False, team agent executes tasks in a predefined static order, which may limit the ability to adapt to unexpected outputs or dynamic conditions during runtime.

Inspector(s)

In aiXplain's team agent architecture, inspectors are special micro agents that review and assess how tasks are executed by other agents.

Inspectors can target two parts of the agent execution:

steps: Inspect intermediate steps during task execution (e.g., tool usage, agent reasoning).
output: Inspect the final answer before it is returned to the user.

How inspectors work:

You enable inspectors with use_inspector=True when creating the team agent.
The inspector_targets parameter controls whether you inspect steps, output, or both.
You can configure how many inspectors you want (num_inspectors), but currently only one inspector is practically used.
Inspectors produce "thoughts" — written feedback or assessments — which are saved inside the intermediate_steps field of the agent response.
Inspectors help identify issues early, improve reliability, and catch invalid reasoning or faulty tool responses.

note

Coming soon: aiXplain will introduce custom inspectors that allow you to assign guardrails, unit tests, compliance checkers, PII redaction, and content filters to agents, offering deeper control over validation and quality assurance.

Feedback combiner

The feedback combiner is another micro agent. Its role is to aggregate the feedback provided by inspectors into a single, unified comment.

If multiple inspectors (or multiple steps) provide feedback, the combiner consolidates them.
The combiner passes the unified feedback downstream to help the final response agent adjust or finalize the answer.

Response generator

The response generator is the final micro agent responsible for producing the final output after inspections and feedback are complete. Its job:

Read the original outputs and any feedback from the inspectors and feedback combiner.
Decide how to refine or regenerate the final output based on quality checks.
Ensure that the response aligns with the user request, formatting preferences (TEXT, MARKDOWN, JSON), and any corrections suggested by inspectors.

Using `AgentTask`

AgentTasks define the specific work that each agent inside a Team Agent is expected to perform. They guide the mentalist in planning the workflow and the orchestrator in sequencing execution across agents.

Each AgentTask includes:

name (str): Name of the task.
description (str): What the agent is expected to do.
expected_output (str): The expected result for this task.
dependencies (list, optional): Other tasks that must be completed before starting this task.

How it works:

You assign AgentTask objects to individual agents when creating them.
The Mentalist reads all defined tasks and their dependencies to dynamically plan the task execution order.
The Orchestrator routes tasks to the right agents based on these assignments and plans.

Visual flow of a team agent execution

[User Query]
      ↓
[Planner (Mentalist)]
  - Plans steps and assigns tasks to agents
      ↓
[Orchestrator]
  - Manages task execution order
  - Selects the right agent to solve each step
      ↓
[Agent Execution]
  - Each agent performs its assigned task
  - Agents can call tools, use memory, reason through tasks
      ↓
[Inspector(s)] (optional but recommended)
  - After each agent’s task, inspectors review:
      - STEP-level reasoning (intermediate results)
      - OUTPUT-level quality (final answers)
  - Can involve 1 or multiple inspectors
      ↓
[Feedback Combiner]
  - Aggregates feedback from inspectors
  - Determines if a step needs revision or is approved
      ↓
[Response Generator]
  - Gathers:
      - Agent outputs
      - Inspector feedback
      - Execution trace
  - Synthesizes the **final user-facing response**
      ↓
[Final API Response]
  - Delivered to user
  - Includes:
      - Final output
      - Session ID
      - Intermediate steps
      - Execution statistics

Running a team agent

A team agent accepts not only text as input but also files, links, and variables to enrich its processing context.

To run a team agent with a simple text query:

team_response = team.run(
    query="Identify and qualify EdTech leads for AI-based personalized learning."
)

# Use session_id to retain conversation context and enable follow-up questions
session_id = team_response.data["session_id"]

team_response = team.run(
    query="New query",
    sessiodn_id = session_id,
    output_format=OutputFormat.MARKDOWN # Return final output in different formats

)

Learn how to run team agents with dynamic input →

The run call returns a ModelResponse object that includes:

The final output generated by the agent team
Session and execution information
A detailed step-by-step trace showing how the agents collaborated

You can access these key parts of the response:

team_response.data["output"] # Final result
team_response.data["intermediate_steps"] # Execution trace
team_response.data["executionStats"]  # Session and performance metrics

See tracing and monitoring guide →

Deploying a team agent

By default, newly created agents are drafts. They expire in 24 hours unless deployed. Deploy your team agent to aiXplain's cloud to make it available via an API permanently. After deployment, the team agent will appear in your team's dashboard, and its integration code is available at: https://platform.aixplain.com/discover/agent/<team.id>

team.deploy()

Integrating a team agent via API

Team agents can be invoked through REST APIs, allowing integration with web apps, backends, and automation pipelines.

Run via `curl`:

curl -X POST "https://platform-api.aixplain.com/sdk/agents/${team.id}/run" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Summarize this week in AI.",
    "sessionId": "<SESSION_ID_TEXT_DATA>"
  }'

Get result by request ID:

curl -X GET "https://platform-api.aixplain.com/sdk/agents/${requestId}/result" \
  -H "x-api-key: YOUR_API_KEY"

Saving a team agent

Update changes to the backend after editing.

# Edit description
team.description = "New description"

# Add agents
team.agents.append(agent_object)

team.save()

Deleting a team agent

Permanently delete a team agent. Deletion is irreversible and removes API access.

team.delete()

How they work​

Lifecycle​

Creating a team agent​

Mentalist​

Inspector(s)​

Feedback combiner​

Response generator​

Using AgentTask​

Visual flow of a team agent execution​

Running a team agent​

Deploying a team agent​

Integrating a team agent via API​

Run via curl:​

Get result by request ID:​

Saving a team agent​

Deleting a team agent​

How they work

Lifecycle

Creating a team agent

Mentalist

Inspector(s)

Feedback combiner

Response generator

Using `AgentTask`

Visual flow of a team agent execution

Running a team agent

Deploying a team agent

Integrating a team agent via API

Run via `curl`:

Get result by request ID:

Saving a team agent

Deleting a team agent