Team agents
Team Agents are advanced AI systems that coordinate multiple Agents to perform complex, multi-step tasks. They are ideal for scenarios involving planning, decision-making, and quality control—tasks that cannot be completed by a single agent alone.
A Team Agent is composed of smaller agents and a central controller that routes tasks, monitors execution, and validates results. This architecture enables modular design and supervision.
How team agents work
When invoked, a Team Agent receives user input and forwards it to a specialized embedded agent, the Mentalist Agent, which breaks the request into smaller executable steps. The Orchestrator Agent then assigns these steps to the appropriate member agents based on their roles and capabilities.
As each member agent completes its assigned step, the result is checked by the Inspector Agent, which applies guardrails on both the prompt and response. If a result violates any constraints, the Inspector flags it and triggers the Mentalist to revise and re-execute that specific step. This correction cycle can repeat up to three times.
If a specific response format is required, the system invokes a Response Agent to structure the output accordingly (e.g., JSON, MARKDOWN).
Each member may call tools or query data sources as part of its task execution. This architecture allows agents to work together, autonomously and intelligently, to complete complex workflows.
To prevent infinite loops, the framework enforces a max_iterations limit (default: 10). You can also configure which specialized agents are active using the use_mentalist and use_inspector flags (default: True). The team can be powered by any supported LLM. By default, the embedded specialized agents use OpenAI's GPT-4o Mini. Use the llm_id parameter to assign a different LLM from the aiXplain marketplace.
Setting the api_key allows you to override the default environment key and dynamically charge a different API key.
version, supplier, and tasks are placeholder parameters for upcoming features.
Basic team agent
name: A unique identifier for the team agent.description: A short summary of the team’s purpose.agents: A list of agent objects that will be coordinated by the team.
All individual agents included in a team must be created using AgentFactory.create() and must include clear instructions.
The following example demonstrates a team agent that combines two specialized agents—one for text analysis and another for multimedia processing.
- The Text Analysis Agent analyzes sentiment from a given text input using the Sentiment Analysis model by Google.
- The Multimedia Agent processes audio input and extracts text from speech. It uses the Speech Recognition model by Azure.
from aixplain.factories import AgentFactory, TeamAgentFactory
# Create the member agents
text_analysis_agent = AgentFactory.create(
name="Text Analysis Agent",
description="Analyzes text for sentiment.",
instructions="Analyze the sentiment of the input and return one of: positive, negative, or neutral.",
tools=[AgentFactory.create_model_tool("615f4c626eb56373643b09d3")]
)
multimedia_agent = AgentFactory.create(
name="Multimedia Agent",
description="Extracts text from audio input.",
instructions="Convert the input audio into text and return the transcription.",
tools=[AgentFactory.create_model_tool("60ddefab8d38c51c5885ee38")]
)
# Create the team agent
team = TeamAgentFactory.create(
name="Audio Sentiment Team",
description="Converts speech to text and analyzes its sentiment.",
agents=[text_analysis_agent, multimedia_agent],
llm_id="677c16166eb563bb611623c1" # Llama 3.3
)
create() initializes a draft team agent with a temporary endpoint valid for 24 hours. The agent will appear in the owner's dashboard labeled as Draft. To create a permanent endpoint, use the deploy method. You can view the agent in the dashboard at: https://platform.aixplain.com/discover/agent/<agent.id>
Agent response
A team agent's run() method accepts both static string queries and dynamic queries. The agent's response includes several key components within response.data:
output: The final response generated by the agent.session_id: Used to continue an ongoing conversation by maintaining context.intermediate_steps: A record of all steps taken by the agent, including interactions and intermediate responses between the LLM and tools.execution_stats: Metrics on the executed run, including the number of API calls to LLMs and tools, the number of tokens used, cost (measured in aiXplain credits, where 1 credit equals 1 USD), and response time.
response = team.run("Give me the sentiment from this audio ", content=['Audio File.mp3'])
response.data.output
Contextual memory
Team agents support two ways to manage conversation context: by passing a session_id or a history.
Each run creates a new session_id unless one is explicitly provided. This allows tracking multiple concurrent sessions per agent. Use session_id in team.run() to automatically store and retrieve memory across turns. If not provided, context is not preserved, and a new session is created per call.
session = response.data.session_id
response = team.run("What is the content of the audio file?",
session_id=session)
response.data.output
Use history to manually pass prior messages. It must follow the OpenAI format:
history = [
{ "role": "user", "content": "My name is Alex." },
{ "role": "assistant", "content": "Hi Alex! How can I help you?" }
]
response = team.run(input="What’s my name?", history=history)
response.data.output
# Expected: "Your name is Alex."
If both session_id and history are provided, history takes precedence and resets the session context.
Session data is stored for 15 days. Listing all sessions per agent is coming soon.
Output format
By default, a team agent's final response is returned as plain text. The agentic framework also supports structured output formats such as JSON and MARKDOWN, enabling responses tailored to specific use cases.
When a structured format is specified using the OutputFormat setting, a specialized Response Agent is automatically invoked at the end of execution. This agent applies and verifies the formatting based on the selected output format.
from aixplain.modules.agent import OutputFormat
response = team.run("Write a short newsletter on last week's news.",
session_id=session,
output_format=OutputFormat.MARKDOWN)
response.data.output
Tracing, monitoring and debugging
- Validate individual agent performance and outputs.
- Assess agent interactions for seamless execution.
Use data.intermediate_steps to analyze task execution and intermediate outputs:
response.data.intermediate_steps
Learn more about agent tracing →
Deploying
Team agents are initially stored as drafts, which remain available for 24 hours before being deprecated unless deployed. Deploying a team agent assigns a permanent API endpoint for integration. Note, all member agents need to be deployed first.
team.deploy()
Team agents are built and deployed on aiXplain’s multi-tenant cloud, hosted on AWS by default. For alternative deployment options, contact care@aixplain.com.
Updating
Once deployed, an team agent can be updated at any time—changes to its name, description, or agents are applied without requiring redeployment. For example, to expand its capabilities, new tools can be dynamically added to team.agents. Be sure to call team.save() to persist any modifications.
new_agent = AgentFactory.create(
name="Search Agent",
description="Conduct search based on given topic."
)
new_agent
team.agents.append(new_agent)
team.save()
Integration
Team agents can be seamlessly integrated into your application using REST APIs or SDKs. The integration process involves invoking an agent with a POST request, retrieving execution results with a GET request, and handling responses dynamically.
You can interact with agents via API calls using curl, Python (requests), or JavaScript (fetch). This allows for flexible deployment in various environments, including backend services, web applications, and automation workflows.
View integration codes at: https://platform.aixplain.com/discover/agent/<agent.id>?tab=integration
Running a team agent via API using curl
You can invoke a team agent using a POST request to the aiXplain API. Below is an example curl request:
curl -X POST "https://platform-api.aixplain.com/sdk/agents/${agent.id}/run" \
-H "x-api-key: f282********0500" \
-H "Content-Type: application/json" \
-d '{
"query": "<QUERY_TEXT_DATA>",
"sessionId": "<SESSION_ID_TEXT_DATA>"
}'
You can retrieve the result of an agent execution using a GET request to the aiXplain API. Below is an example curl request:
curl -X GET "https://platform-api.aixplain.com/sdk/agents/${requestId}/result" \
-H "x-api-key: f282********0500" \
-H "Content-Type: application/json" # Fetches the result of an agent execution using the request ID
Deleting
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()