> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xenovia.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create an agent

> Create an agent for an app you build, give it a key, and send it a first request.

Every kind of agent comes under Xenovia the same way: create it, connect it, see its first session. This page is for an app you build. For tools your team already uses, see [Coding agents](https://docs.xenovia.io/agents/coding-agents.md) and [AI platforms](https://docs.xenovia.io/agents/ai-platforms.md).

For example, create a `support-agent` whose purpose is "Answer customer questions about orders", route it to your OpenAI provider, and point your app's OpenAI client at it. Its first request shows up in **Sessions**, checked against that purpose.

## Before you start

Add a provider with a model and its credential on **Providers** first: the agent sends every request to its provider's model. See [Providers](https://docs.xenovia.io/providers/overview.md).

## Create it

**1. Open the wizard**

On **Agents**, click **Create agent**. Under **Your own agent**, choose **Set up manually**. (When Nova is on, **Set up with Nova** lets you describe the agent and has [Nova](https://docs.xenovia.io/nova.md) fill in the setup.) The same wizard opens from **Create an agent** in the Welcome dialog.

**2. Purpose**

**What is this agent for?** Give it a **Name** and, optionally, a **Description**. Write its **Purpose** in plain language: every model request is checked against this text before any guardrail runs, and the check starts in Monitor. Add **Capabilities (optional)**: the things it does, each with a name and description.

**3. Model route**

**Where do its model requests go?** Choose its **Provider**. Requests go to the provider's model. Optionally add **Fallbacks**: providers tried in order when the primary is down (see [Fallbacks](https://docs.xenovia.io/providers/fallbacks.md)).

**4. Protection**

**What protects it?** Add **Policies and guardrails**. Policies are rules from the template catalog and switch on when you activate the agent. Guardrails are model-judged checks that run after the purpose check. Everything here starts in Monitor: it records what it would do without changing any outcome.

**5. Create**

Click **Create agent**. Nothing is saved until you do. The agent is created as a draft.

![Create an agent wizard on the Purpose step, filled in for a support-assistant agent](https://mintcdn.com/xenovia/RO5UF1Tk8L9B7yPt/images/screens/create-an-agent-purpose.png?fit=max\&auto=format\&n=RO5UF1Tk8L9B7yPt\&q=85\&s=8ccc13a640d683dcc229afcf0669e8a0)

The Create an agent wizard, Purpose step

## Connect it

While the agent is a draft, its **Overview** shows **Setup** in three steps. For an active agent, the **Setup** button opens the same steps.

**1. Change the base URL to the Xenovia URL**

Copy the agent's base URL, `https://runtime.xenovia.io/{agent_id}/v1`, into your client. The agent ID is the part between the host and `/v1`.

**2. Add authentication**

Choose **Create API key**, give it a **Key name**, and copy the key (`xe_...`). It is shown once. The header is `Authorization: Bearer $XENOVIA_API_KEY`.

**3. Send a test request**

```bash theme={null}
curl https://runtime.xenovia.io/{agent_id}/v1/chat/completions \
  -H "Authorization: Bearer $XENOVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"Hello from Xenovia"}]}'
```

The body names no model: the runtime uses the provider's.

[Connect your app](https://docs.xenovia.io/agents/connect-your-app.md) has the same change for each SDK and framework.

## Activate it

Click **Activate**. Activation needs an API key and a provider with a model; until both are in place, the console lists what is missing (such as **No API key** or **No provider attached**), with a button to fix each.

> [!WARNING]
>
> While the agent is a draft, the runtime answers its keys with `403` and the message `agent is not active: activate it in the Xenovia dashboard before sending requests`. The OpenAI SDK raises this as `PermissionDeniedError`.

When the request goes through, the response carries `X-Xenovia-Session-Id`, `X-Xenovia-Trace-Id` and `X-Xenovia-Decision: allowed`, and a session for it appears in **Sessions**, showing your agent and the model set on its provider, not the `model` you sent.

## The agent's page

| Tab | What it holds |
| - | - |
| **Overview** | Setup while it's a draft; then its purpose, routing and activity |
| **Capabilities** | What the agent does, checked by the [purpose check](https://docs.xenovia.io/control/neon.md#purpose-and-capabilities) |
| **Configuration** | **Model routing** (provider and [fallbacks](https://docs.xenovia.io/providers/fallbacks.md)), and the danger zone: **Deactivate agent** or **Delete agent** |
| **Policies** | The [policies](https://docs.xenovia.io/control/policies.md) that cover it |
| **Neon** | [Neon](https://docs.xenovia.io/control/neon.md)'s protections and your guardrails |
| **Hosted tools** | The [hosted tools](https://docs.xenovia.io/control/hosted-tools.md) its provider may run |
| **API keys** | Its keys. **Revoke** stops a key immediately |
| **Sub-agents** | Its [sub-agents](https://docs.xenovia.io/agents/sub-agents.md) |

## What next?

> [card] [Connect your app](https://docs.xenovia.io/agents/connect-your-app.md)
>
> The change for your SDK or framework.

> [card] [Add a policy](https://docs.xenovia.io/control/policies.md)
>
> Block one thing it should never do.

> [card] [Read its sessions](https://docs.xenovia.io/observability/sessions.md)
>
> See each request and decision.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.