Skip to main content

Agents

An Agent is a Large Language Model (LLM) enhanced with instructions, external tools, and memory to retain context across interactions. Based on the provided context, the agent autonomously and iteratively selects and uses relevant tools to execute the desired task.

How agents work​

When invoked, the agent processes its input in the context of the provided instructions. If history or session_id are included, the agent incorporates prior conversation turns. It then either generates a final response or interacts with tools as many times as needed to complete the task.

To prevent infinite loops, the aiXplain agentic framework enforces a max_iterations limit (default: 10). If an output_format is specified, the agent invokes an embedded Response Agent to structure the final output accordingly. The max_tokens setting (default: 2048) defines the maximum number of tokens the agent can generate in a single response.

Setting the api_key allows you to override the default environment key and dynamically charge a different API key.

aiXplain agents are optimized for OpenAI (GPT-4o Mini default) and Meta models. However, you can override the default llm_id with your preferred model from a collection of 170+ LLMs in the aiXplain marketplace.

note

version, supplier, and tasks are placeholder parameters for upcoming agent features.

Basic agent​

  • name: A unique identifier for the agent, up to 24 characters. Allowed characters: letters, numbers, spaces, hyphens (-), and parentheses ((, )), matching the pattern ^[a-zA-Z0-9 \-\(\)]*$.
  • description: A brief summary of the agent’s role.
  • instructions: The agent’s system prompt. Defines the agent’s behavior, tone, role, boundaries, and success criteria. It is typically invisible to the end user and controls how the agent reasons, responds, and decides when to invoke tools.

name and description are metadata and do not affect agent behavior. They can become visible to the end user if the agent is set to public (on-demand feature). All other parameters remain hidden from users. They are part of the agent’s signature when added to a Team Agent.

from aixplain.factories import AgentFactory

agent = AgentFactory.create(
    name="My agent",
    description="An AI assistant that provides informative responses.",
    instructions="Answer the user's questions accurately."
)

create() initializes a draft 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​

An 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 = agent.run("What's an AI agent?")
response.data.output

Show output

Learn how to run agents with dynamic queries →

Tools​

Agents use tools to interact with external APIs, webhooks, structured workflows, and data sources to complete tasks. They dynamically decide at runtime which tool to call and how to call it by relying on the tool's signature, which includes its name, description, and parameters. After processing the results, the agent uses that information to determine the next step in execution.

Create a tool​

This code snippet demonstrates how to create a tool using a specified asset ID from the aiXplain marketplace.

The agentic framework supports various types of tools that can be integrated into agents to extend their functionality. For a complete list of available tools, visit the Tools page.

from aixplain.factories import AgentFactory

# Create a model tool using a specific model from the aiXplain marketplace
search_tool = AgentFactory.create_model_tool(
    model="6736411cf127849667606689"  # The asset ID of Tavily Search API
)

Add tool to agent​

# Add the tool to an existing agent
agent.tools.append(search_tool)
agent.save() # To deploy changes

Contextual memory​

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 agent.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 = agent.run("What is the latest news on this topic?",
                     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 = agent.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, an 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 and any formatting criteria defined in the agent’s instructions.

from aixplain.modules.agent import OutputFormat

response = agent.run("Write a short newsletter on last week's news.",
                     session_id=session,
                     output_format=OutputFormat.MARKDOWN)
response.data.output

Tracing, debugging, and monitoring​

Tracing captures each step of an agent’s run, including user messages, intermediate agent responses, tool results, and final outputs. This is essential for troubleshooting, analyzing agent behavior, and preserving conversation transcripts for further review.

Intermediate steps​

response.data.intermediate_steps

Execution stats​

Execution stats provide a detailed summary of an agent’s run, including execution status, API calls made, cost in aiXplain credits, and total runtime. A breakdown is also available per tool and agent, detailing resource usage and performance.

response.data.execution_stats

Learn more about agent tracing →

Deploying​

Agents are initially stored as drafts, which remain available for 24 hours before being deprecated unless deployed. Deploying an agent assigns a permanent API endpoint for integration.

agent.deploy()
note

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 agent can be updated at any time—changes to its name, description, instructions, or tools are applied without requiring redeployment. For example, to expand its capabilities, new tools can be dynamically added to agent.tools. Be sure to call agent.save() to persist any modifications.

# Update agent attributes
agent.name = "New Agent Name"
agent.description = "Updated agent description"
agent.instructions = "Revised agent instructions"

# Add a new tool
agent.tools.append("<TOOL>")

agent.save() # To deploy changes

Integration​

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 an agent via API using curl​

You can invoke an 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 an agent removes it from the owner's dashboard and permanently deletes its endpoint. This action cannot be undone.

agent.delete()
note

An agent cannot be deleted if it is referenced by any team agent. Attempting to delete it will raise an agent_is_in_use exception. To proceed, first remove the agent from all team agents using it.

Next​

You now have an autonomous agent deployed. To expand your agent’s capabilities, learn about the available tools you can add →