# 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](https://www.aixplain.com/support/articles/get-started-with-aixplain-desktop)** or with **[the Agents SDK](https://docs.aixplain.com)** 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.

> aixplain Desktop is free to download for macOS, Windows and Linux, and the Agents SDK is included on every plan, starting with Core. Running and testing agents on aixplain models uses your team's credits. Deploying to your own servers needs the **[Enterprise](https://www.aixplain.com/enterprise)** plan. The app is in early releases (version 0.x), so features can change from one release to the next.

## 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

| Way | Use it when |
| --- | --- |
| **Omni** | You want an agent working fast, from a plain-language description, with no code |
| **Koder in aixplain Desktop** | The agent belongs in your codebase, under version control, and you review every change |
| **The Agents SDK** | Your app calls the agent, or you need every option set exactly in Python |

## Build an agent with Omni

**[Omni](https://www.aixplain.com/support/articles/get-started-with-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](https://www.aixplain.com/support/articles/get-started-with-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](https://github.com/aixplain/aiXplain)**.

### Requirements

- **Python:** version 3.9 or later.
- **An aixplain account:** see **[Your account, plans and billing](https://www.aixplain.com/support/articles/account-plans-and-billing)**.
- **An API key:** created in your workspace, as below.

### Install the package

```sh
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](https://app.aixplain.com/team/settings?tab=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.

> **Important:** The full key is shown only once. If you lose it, delete it and create a new one. In production, read the key from an environment variable such as `AIXPLAIN_API_KEY` instead of writing it into your code.

### 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.

```python
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.

```python
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:

```python
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](https://docs.aixplain.com/getting-started/integration/)**.

## 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.

> **Important:** Changes to the folders that hold agents, modes and commands always ask for your approval, in every access mode. Omni can't remove an aixplain agent's inspector or make it weaker. Anything that sends, creates, changes or deletes something in your connected apps is shown to you and approved one call at a time.

> **Note:** Before you go live, test the agent on realistic and adversarial inputs, confirm which tools ran, add inspectors and cap each run with a budget.

## Deploy an agent

| Where | What you get |
| --- | --- |
| **On cloud** | The default. The agent runs 24/7 on aixplain's managed infrastructure, billed per run |
| **Your own servers** | The agent runs on-prem, in your VPC or air-gapped, on the Enterprise plan |

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](https://app.aixplain.com/dashboard)**.

> **Note:** Deployed agents live on cloud or on your organization's servers, not on your desktop. When you call one, its full traces stay where it is hosted.

## 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](https://docs.aixplain.com/assets/agents/triggers/)** in the docs.

> **Important:** Unattended runs keep every deny rule. Scheduled runs refuse to push code, delete folders, spend money or read secrets, and record why.

## 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](https://www.aixplain.com/support/articles/account-plans-and-billing)** and **[Pricing](https://www.aixplain.com/pricing)**.

## Limitations

- Deploying to your own servers needs the Enterprise plan.
- Omni in the desktop app and Omni at **[app.aixplain.com](https://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](https://app.aixplain.com/team/settings?tab=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](https://www.aixplain.com/support/articles/account-plans-and-billing#top-up-credits)**.

## Learn more in the docs

- **[Quickstart](https://docs.aixplain.com/getting-started/quick-start/):** the full walkthrough, including agents that return JSON.
- **[Agents](https://docs.aixplain.com/assets/agents/):** add tools, pin the model, add subagents and set run parameters.
- **[Inspectors](https://docs.aixplain.com/assets/agents/inspectors/)** and **[Budgets](https://docs.aixplain.com/assets/agents/budgets/):** check every step and cap cost and time.
- **[Deployment](https://docs.aixplain.com/deployment/):** call agents from any language and set up on-prem.
- **[API keys](https://docs.aixplain.com/platform-overview/teams-and-governance/api-keys/):** scoped keys and limits for each environment.

## Get help

- **Report a bug:** open an issue on **[GitHub](https://github.com/aixplain/koder/issues/new/choose)** with your version, operating system and the steps to reproduce it.
- **See what changed:** read the **[release notes](https://www.aixplain.com/release-notes)**.