Team agents

Team agents are multi-agent systems composed of individual agents that each own a specific task in a coordinated workflow. Instead of relying on a single generalist, team agents break complex prompts into subgoals and route them to the most capable agents, based on task responsibilities and dependencies.

They enable:

• Specialized reasoning by assigning specific roles to each agent
• Task orchestration using dependency-aware routing and execution
• Modular design where each agent can be developed and tested independently
• Scalability for advanced workflows like lead qualification, customer support, content generation, and RAG

---

Creating a team agent

A team agent is defined by composing individual agents with one or more AgentTask definitions. Each agent specifies its role, goal, and execution logic, and the team agent manages the execution order using declared task dependencies.

from aixplain.factories import AgentFactory
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",
    instructions="Find EdTech leads for AI personalization products.",
    tasks=[find_leads],
    tools=[
        AgentFactory.create_model_tool(model="6736411cf127849667606689"), # Tavily Search API
        AgentFactory.create_model_tool(model="66f423426eb563fa213a3531") # Scrape Website Tool
    ]
)

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

---

Composing the team agent

Use TeamAgentFactory.create() to build a team agent from individual agents. Dependencies between tasks define the execution graph.

from aixplain.factories import TeamAgentFactory

team = TeamAgentFactory.create(
    name="AI for Personalized Learning Lead Generation",
    description="AI for Personalized Learning Lead Generation",
    agents=[lead_finder, lead_analyzer],
)

team.deploy()

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

• name: The name of the team agent
• description: Optional description of the team agent
• agents: List of individual agents (IDs or objects) to compose the team
• llm_id: The ID of the LLM that powers team-wide coordination. (Default: GPT-4o Mini)
• use_mentalist: Whether to use the built-in Mentalist agent to plan tasks. (Default: True)
• use_inspector: Whether to enable step- or output-level validation with Inspector. (Default: True)
• num_inspectors: How many inspector agents to spawn during execution. (Default: 1)
• inspector_targets: What to inspect: ["steps"], ["output"], or both. (Default: ["steps"])
• use_mentalist_and_inspector: Legacy flag to enable both Mentalist and Inspector simultaneously. (Default: False)
• api_key: Optional override for the default team API key.
• supplier and version: Reserved for future features.

How team agent inputs shape behavior

Component	Purpose	Influence on behavior
TeamAgent.run()	Defines user goal	Acts as the high-level goal for the Mentalist and Orchestrator. Guides planning and tool selection.
Agent.AgentTask	Defines the unit of execution	Controls routing, evaluation, and response expectations. Define task order and which agents must wait for results from others. The expected_output is used as a reference by the Inspector (if enabled) to assess correctness.
Agent.instructions	Forms the developer message in the agent's prompt.	Directly influences how the agent interprets and executes its task.

---

How team agents run

Team agents coordinate multiple specialized agents to support planning, orchestration, and trust during execution. These system agents are embedded in the team agent runtime to manage sub-agent behavior, validate outputs, and ensure consistent, high-quality responses.

Together, they form the backbone of team agent execution—enabling accurate task flow, safe evaluation, and modular, inspectable behavior at scale.

---

Mentalist (planner)

Role
Creates a graph-based execution plan based on the user’s objective and the available workers and their tools.

Responsibilities

• Breaks down the user request into a set of discrete tasks
• Structures those tasks into a dependency graph (e.g., step 1 → step 2 + step 3)
• Assigns each task to a suitable agent based on their capabilities
• Ensures tasks are relevant and minimal. If the task is unsolvable or inappropriate, flags it as NOT_SOLVABLE

Output
A task plan indicating task order, descriptions, and assigned agents.

Impact of enabling or disabling the Mentalist

Setting	Behavior
use_mentalist=True	The Mentalist agent creates a graph-based plan before execution. Tasks can run in parallel when possible, reducing latency and improving efficiency for multi-step objectives.
use_mentalist=False	The Orchestrator decides tasks sequentially, one step at a time, based on the current context. This is simpler but may lead to slower and less strategic execution.

---

Orchestrator (supervisor)

Role
Executes the Mentalist's plan step by step, deciding which agent to activate next and passing the necessary input.

Responsibilities

• Selects the next agent to act, or ends execution if the task is complete
• Analyzes past agent outputs (intermediate steps) to determine the next move
• Provides the selected worker with a fully contextualized input, including all relevant context so far
• Responds with the keyword "FINISH" when the user’s objective is achieved or if execution cannot continue

---

Agent

Role
Carries out the individual task assigned by the Orchestrator using its instructions and tools.

Responsibilities

• Receives contextualized task input from the Orchestrator
• Decides how to respond, potentially invoking one or more tools
• Must return a response using a strict JSON blob format
• Sends result back to the Orchestrator

---

Inspector(s) (step validator)

Role
Evaluates whether a worker’s step output is correct, complete, and well-executed

Responsibilities

• Reviews an agent's task input and output
• Confirms whether the response meets expectations (CORRECT) or returns feedback
• Feedback includes missing elements, mistakes, or reasons for failure, without fixing the response
• Evaluates the final response to the user, after all agent steps are completed.

Special rules:

• Accepts different styles as long as content is correct
• Doesn’t penalize tool limitations (e.g., if tool can’t show intermediate steps)
• Doesn’t suggest fixes—only diagnoses

Impact of enabling or disabling the Inspector

Setting	Behavior
use_inspector=True	Each step is evaluated automatically for correctness and completeness. If issues are found, feedback is returned to improve the next steps. Adds reliability but increases latency.
use_inspector=False	Agent steps are not evaluated. Execution is faster, but there's no feedback loop, so mistakes may go unnoticed. Best for trusted agents or low-stakes use cases.

---

Response generator

Role Formats the final output after all agents have completed their tasks, ensuring it matches the expected format (e.g., plain text, JSON, or markdown).

Responsibilities

• Receives the original user query and all intermediate steps from prior agents
• Synthesizes a complete, coherent response based on the overall context
• Applies the requested output_format (e.g., TEXT, MARKDOWN, JSON)
• Does not invoke tools or rerun tasks—acts only as a summarizer
• Returns the final output to the user or system caller

---

Deleting a team agent

Deleting a team agent removes it from the owner's dashboard and permanently deletes its endpoint. It does not delete its member agents. This action cannot be undone.

team.delete()

---