Agents

Agents are autonomous, tool-using entities powered by large language models (LLMs). They follow a ReAct-style loop (Reasoning + Acting) where they reason through a user’s query, optionally call tools to gather or analyze data, and then generate a final answer.

An agent can:

• Understand and respond to user input
• Call external tools (e.g., search, summarization, retrieval)
• Maintain memory between turns
• Format responses as plain text, JSON, or Markdown
• Be deployed and accessed through APIs or SDK

---

Creating an agent

You create an agent by defining its behavior, attaching tools, and selecting a model:

from aixplain.factories import AgentFactory

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

Each agent includes:

• name and description: Metadata for organizing and discovering agents
• instructions: The system prompt defining behavior and constraints
• tools: Optional list of callable external functions (retrievers, APIs, etc.)
• llm_id: The identifier for the LLM to use (default: GPT-4o Mini)
• api_key: Optional override for the default team API key.
• tasks: Only relevant when working with Team Agents.
• supplier and version: Reserved for future features.

By default, newly created agents are drafts. They expire in 24 hours unless deployed.

---

Running an agent

To run an agent, use the run() method with a user query and optional parameters:

response = agent.run(
    query="What are the latest AI updates?"
)
response.data.output

Learn how to run agents with dynamic input →

run() parameters

Parameter	Description
query	The user's input.
data / content	Structured or unstructured input (e.g. documents, tables, images).
session_id	Enables contextual memory across calls.
history	Overrides the session state with manual message history.
name	Identifier for the call instance (used for tracking/debugging). (Default: "model_process")
parameters	Optional agent-level configuration (e.g. temperature, model switches). (Default: {})
output_format	Format of the final response (TEXT, MARKDOWN, JSON). (Default: TEXT)
timeout	Total runtime limit in seconds before force stop. (Default: 300)
wait_time	Time interval (in seconds) between polling checks. (Default: 0.5)
max_tokens	Maximum number of tokens the agent is allowed to generate. (Default: 2048)
max_iterations	Maximum number of reasoning + tool usage loops. (Default: 10)

Internal reasoning (ReAct loop)

Agents operate in cycles of:

1. Thought: "I should use a search tool."
2. Action: { "action": "search_tool", "action_input": { ... } }
3. Observation: Tool result inserted by SDK
4. Repeat or finalize

Final response is always:

{
  "action": "Final Answer",
  "action_input": "Here’s what I found..."
}

---

Output format

Agents can return answers in structured formats using the output_format argument.

from aixplain.modules.agent import OutputFormat

response = agent.run(
    query="Review this product: Canon EOS 4000D",
    output_format=OutputFormat.MARKDOWN
)
response.data.output

Available formats

Format	Description
TEXT	Plain natural language output
MARKDOWN	Formatted markdown for web display
JSON	Structured key-value output for downstream processing

A specialized Response Agent is used internally to ensure formatting validity.

---

Contextual memory

Agents can remember previous interactions through two mechanisms:

1. session_id

Stores multi-turn memory on aiXplain’s servers for up to 15 days.

response = agent.run(query="What's a better option?", session_id=response.data.session_id)
response.data.output

You must run the agent to create a 'session_id'.

2. history

Manual override of memory for stateless use cases:

history = [
  { "role": "user", "content": "My name is Alex." },
  { "role": "assistant", "content": "Hi Alex! How can I help?" }
]

response = agent.run(query="What’s my name?", history=history)
response.data.output

If both session_id and history are provided, history takes precedence.

---

Deploying an agent

To make an agent permanent and accessible via API, call:

agent.deploy()

After deployment:

• The agent gets a persistent API endpoint
• You can update its tools, instructions, or metadata via .save()

agent.name = "Updated Agent"
agent.tools.append(new_tool)
agent.save()  # Persists changes to the deployed version

Once deployed, the agent will appear in your team's dashboard, and its integration code (including API usage examples in Python, curl, and JavaScript) is available at: https://platform.aixplain.com/discover/agent/<agent.id>

---

Integrating agents 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"

---

Agent response structure

Calling agent.run() returns an AgentResponse object:

AgentResponse(
    status='SUCCESS',
    completed=True,
    data=AgentResponseData(
        input={ ... },
        output="Summarized news content...",
        session_id="abc123",
        intermediate_steps=[ ... ],
        execution_stats={ ... }
    ),
    used_credits=0.0003,
    run_time=4.1
)

Key fields

Field	Description
output	Final agent answer
session_id	Conversation ID
intermediate_steps	Trace of actions, tool calls, and observations
execution_stats	Runtime, cost, and tool-level breakdowns
used_credits	Estimate of inference cost
run_time	Total duration in seconds

Use intermediate_steps and execution_stats to trace, debug, and monitor behavior.

See tracing and debugging guide →

---

Deleting

Deleting an agent remove it from the owner's dashboard and permanently deletes its endpoint. Agents cannot be deleted if they are part of a Team Agent. This action cannot be undone.

agent.delete()

---

Summary

aiXplain agents simplify intelligent task execution by wrapping LLMs with memory, tool use, and structured output capabilities. You can build, run, monitor, and integrate agents using a consistent interface across Python SDK and REST APIs.