Build and deploy agents

Agents are how you build, test and deploy your own agents with aixplain. Build one with Omni from a plain-language description, with Koder in aixplain Desktop or with the Agents SDK in your own code, then deploy it on cloud, where it runs 24/7, or on your own servers. This article explains each way to build an agent, how to test and debug it, how to deploy it and run it on a schedule or a trigger, and what it can't do yet.

How agents work

An agent is a model with instructions, tools, skills and limits on what it can do. It plans its own steps, calls models and tools and reports what it used and what it cost. Every agent can call the models, tools and integrations in the aixplain Marketplace with one API key. On each run, the agent stops when the task is done or a budget is reached, and every run returns its output with its steps, credits used and run time.

Key capabilities

• Any model and tool: web search, connected apps, MCP servers or your own Python, all with one key.
• Teams of agents: split a goal across subagents and combine their work.
• Control: budgets cap cost and time, and inspectors check inputs, steps and outputs as the run happens.
• Tracing: every run's steps, cost and status, in code and in the dashboard.
• Deployment: the same agent runs on cloud or on your own infrastructure, with its own ID and an API that your teams and customers reach with a secure key.

Choose how to build

Build an agent with Omni

Omni turns your description into an agent: a model, instructions, the tools and skills it needs and limits on what it can do. It shows the agent as a card in the chat, and you open the card to test it and change its setup.

Omni works with the aixplain SDK on your computer. The first time, it sets the SDK up for you and finds Python 3.9 or newer, even when your default python3 is older. If there is no suitable Python, it tells you what to install.

1. Open aixplain and select Omni.
2. Describe the job: what the agent should do, which tools or apps it needs and what it should return.
3. Answer Omni's questions as it builds the agent.
4. Approve the steps Omni asks about. Changes to the folders that hold agents always ask first.
5. When the agent appears as a card in the chat, open it to test it.

Example requests

• "Build an agent that reads new support tickets, sorts them by urgency and drafts a first reply."
• "Make an agent that searches the web for news about our competitors' pricing and sends me a weekly summary."
• "Turn what we just did into an agent I can run every Monday morning."

Build an agent with Koder

Select Koder, open the project that holds your agent code and describe the agent you want. Koder writes the agent with the Agents SDK, tests it and deploys it, and you review every change in the Review panel before you keep it.

Use Koder when the agent belongs in your codebase, under version control, next to the app that calls it.

Build an agent with the Agents SDK

The Agents SDK is a Python library for building, running and governing agents. You describe an agent in Python, call .save(), and it is deployed with an ID you can call from Python, the REST API or any other language. The source is on GitHub.

Requirements

• Python: version 3.9 or later.
• An aixplain account: see Your account, plans and billing.
• An API key: created in your workspace, as below.

Install the package

pip install aixplain

Get your API key

An API key authenticates every call you make from the SDK and the REST API. Each key belongs to one workspace and uses that workspace's assets and credits.

1. Open Settings → API keys in the workspace the key should use.
2. Select Create API key.
3. Enter a name that says where the key runs, for example Production web app.
4. Optionally set an expiration date. Leave it empty for a key that doesn't expire.
5. Select Create, then copy the key.

Build and run your first agent

This agent searches the web and answers with what it finds. Paste your API key in place of YOUR_API_KEY and run the script.

from aixplain import Aixplain

aix = Aixplain(api_key="YOUR_API_KEY")

agent = aix.Agent(
    name="Research agent",
    description="Answers questions with cited web findings.",
    instructions="Use web search when needed and keep answers concise.",
    tools=[aix.Tool.get("tavily/tavily-web-search/tavily")],
).save()

result = agent.run("What are the top 3 trending AI papers this week?")
print(result.data.output)

.save() deploys the agent to your workspace and returns it with an ID. The agent uses the default LLM, and aix.Tool.get() loads the web search tool by its asset path.

Check what the agent did

Every result records the models and tools the agent called, what the run cost and how long it took.

print(agent.id)
print([step["unit"]["name"] for step in result.data.steps])
print(result.status, result.used_credits, round(result.run_time, 1))

used_credits is the cost of the run in credits.

Run a deployed agent

A saved agent stays in your workspace until you delete it. Get it by its ID and run it again from anywhere:

import os
from aixplain import Aixplain

aix = Aixplain(api_key=os.environ["AIXPLAIN_API_KEY"])

AGENT_ID = "YOUR_AGENT_ID"  # from agent.id after .save()

agent = aix.Agent.get(AGENT_ID)
result = agent.run("Ticket: The export button returns a 500 error since this morning.")
print(result.status)
print(result.data.output)

From another language, call the agent over HTTP with your key in the x-api-key header. Runs are asynchronous: the call returns a URL that you poll until the run is complete. See REST API.

See how an agent is built

Agents you save show up on the Agents page in aixplain Desktop. Open one to see how it is built:

• Model: the model that does the work.
• Tools and skills: what the agent can use and the know-how it carries.
• Member agents: the agents it hands parts of the job to, if it leads a team.
• Input and output: what it takes and what it returns.
• Step limit: the most steps it can take in one run.
• Instructions: what it is told to do and how.

The page works for large workspaces too, with a thousand agents or more.

Test and debug an agent

When Omni shows an agent as a card in the chat, open the card to bring the agent up beside the chat. Send it real requests and read what it does. To change it, tell Omni what to change, or change its setup beside the chat, then test it again. This works for aixplain agents and for agents on your computer.

Omni includes a debugger for aixplain agents and agents on your computer. When a run doesn't go as expected, ask Omni to debug the agent. In code, read result.data.steps to see which tools ran.

Deploy an agent

Every deployed agent comes with rate limits, a budget, monitoring and tracing. Agents are versioned, with separate staging and production, and you can roll back to an earlier version. You can start on cloud and move to your own servers later, with no rebuild. Watch usage, cost and run traces in the aixplain app.

Run an agent on a schedule or a trigger

An agent can run on its own, on a schedule or when an event fires, such as a new email in a connected account.

• In the app: ask Omni or Koder to schedule an aixplain agent or set an event trigger for it. Scheduled runs show their history, and you can pause one or run it now. Omni home lists scheduled runs that failed, so you can pick them up.
• In code: create a trigger with the Agents SDK. See Triggers in the docs.

Pricing and usage

Each run draws credits from your workspace for the models and tools it calls, plus an orchestration fee on calls made inside an agent run. One credit is one US dollar. For plans and rates, see Your account, plans and billing and Pricing.

Limitations

• Deploying to your own servers needs the Enterprise plan.
• Omni in the desktop app and Omni at app.aixplain.com don't share sessions or settings yet.
• Building and testing on aixplain models needs a network connection.
• Connected apps are aixplain team assets, and verifying or using them may use credits.

Troubleshooting

save() fails with err.name_already_exists

An agent with that name already exists in your workspace. Rename the agent, or delete the old one first with agent.delete().

I get APIError: Forbidden resource

The API key is missing, mistyped or revoked. Copy the key again from Settings → API keys, or create a new one.

The agent didn't use the web

The agent decided the tool wasn't needed. Check result.data.steps, and say in instructions when it should search.

Runs are refused with err.not_enough_balance

Your workspace is out of credits. See Top up credits.

Learn more in the docs

• Quickstart: the full walkthrough, including agents that return JSON.
• Agents: add tools, pin the model, add subagents and set run parameters.
• Inspectors and Budgets: check every step and cap cost and time.
• Deployment: call agents from any language and set up on-prem.
• API keys: scoped keys and limits for each environment.

Get help

• Report a bug: open an issue on GitHub with your version, operating system and the steps to reproduce it.
• See what changed: read the release notes.