Skip to main content

Agents

Agents are autonomous, tool-using AI systems powered by large language models (LLMs). They reason, act, call tools, and produce structured outputs such as text or Markdown.

How they work​

Agents follow a ReAct-style loop:

  • Thought → Action → Observation → (repeat) → Final Answer.
  • They use LLMs for reasoning and external tools for specific capabilities.
  • Agents can maintain memory between conversations through session_id or manual history.

Lifecycle​

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

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

Creating an agent​

Create an agent by defining behavior, selecting a model, and optionally attaching tools.

from aixplain.factories import AgentFactory

agent = AgentFactory.create(
    name="Google Search Agent",
    description="A search agent",
    instructions="Use Google Search to answer queries.",
    tools=[
        AgentFactory.create_model_tool("65c51c556eb563350f6e1bb1")
    ],
    llm_id="669a63646eb56306647e1091"
)

Parameters:

  • name (str): Agent name.
  • description (str): Short description, does not impact behaviour.
  • instructions (str): System prompt defining agent behavior.
  • tools (list, optional): List of tools or models the agent can call.
  • llm_id (str, optional): LLM used for reasoning (default: GPT-4o mini).
  • api_key (str, optional): Override for default team API key.
  • tasks (list, optional): Specialized task definitions for team agents.
  • 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.

Selecting LLMs for agents​

Different LLMs balance complexity, latency, and cost in different ways. aiXplain agents are compatible with any LLM. They are optimized for best performance with OpenAI models and Llama-based models.

Best practice: Start with a high-performing model to meet your target accuracy. Then, experiment with smaller or faster models to optimize for cost and speed without sacrificing reliability.

How to write effective instructions​

Instruction defines the agent's behavior, tone, and task focus. This parameter acts as the agent's "brain" by setting the system prompt that guides how it reasons, uses tools, and formulates responses.

  • Define the agent’s role clearly: ("You are a helpful research assistant specializing in scientific papers.")
  • Specify goals or task types: ("Summarize articles, extract key findings, and suggest next steps.")
  • Set the tone and style: ("Respond formally and cite sources when possible.")
  • Mention tool usage if needed: ("Use the 'search_tool' when external information is required.")

Running an agent​

An agent accepts text input and, depending on its design, may also accept files, links, or variables to enrich its reasoning process.

To run an agent with a simple text query:

agent_response = agent.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 = response.data["session_id"]

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

)

Learn how to run agents with dynamic input →

The run call returns an AgentResponse object that includes:

  • The final output generated by the agent
  • Session and execution information
  • A detailed step-by-step trace showing how the agent used tools

You can access these key parts of the response:

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

See tracing and monitoring guide →

Deploying an agent​

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

agent.deploy()

Integrating an agent via API​

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/${agent.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 an agent​

Persist any configuration changes to the backend, even after deployment.

# Update agent name
agent.name = "Updated Agent" 

# Append more instructions
agent.instructions = agent.instructions + "You are a multilingual assistant." 

# Add a new tool
agent.tools.append(new_tool) 

# Remove a tool
agent.tools.remove(agent.tools[0])

agent.save() # Updates the agent with the changes; maintains its original id

Deleting an agent​

Permanently delete an agent.

agent.delete()
note

Agents part of a Team Agent cannot be deleted individually, until the team agent is deleted.

Adding tools to agents​

Assets (models, utilities, pipelines, indices,...) can be attached as tools to extend agent capabilities.

tool = AgentFactory.create_model_tool("66f83c216eb563266175e201") # Weather API
agent.tools.append(tool)
agent.save()

Each tool should have a clear, agent-friendly description to help the agent reason about when to call it. You can override a marketplace tool’s description:

tool.description = "Use this tool to find real-time weather updates."

Best practices when adding tools:

  • Validate each tool before integrating it.
  • Limit tool count up to 10 tools per agent. If more are needed, split into specialized agents.

Common tool types for agents​

TypeDescriptionExamples
ModelsAI models like LLMs, speech recognition, etc.Parse data with LLM, generate images
UtilitiesAPIs or custom code integrationsScrape websites, fetch weather
DataIndexes or knowledge basesEnable RAG (retrieve-and-generate) from your documents
PipelinesRule-based model workflowsMulti-step processes like translate-then-summarize
Agents (Team Agents)Other agents as callable componentsResearch, negotiation, verification agents
note

For systems without an API, agents can use computer-use models that simulate UI interactions like a human would. Coming soon

Learn more about tools →