The **Agent API** is a stable, unified way to invoke Everruns agents from your own code.

Before it, there were several ways in, each with its own shape. API endpoint channels had their own keys and could only poll. Protocol channels such as AG-UI and A2A each speak their own protocol. The management API could run any agent, but only with a personal access token, and that token reaches every agent, harness, key, and budget you can manage.

![The Agent API: your backend calls one agent's base URL with an agent key, mints a 15-minute runtime token for your web app, and the browser calls the same URL from an allowed origin. Each caller sees only the sessions it started. The management API is not reachable with an agent credential.](/_astro/overview.Bv-wBmad.svg)

## The contract

Each agent gets its own base URL from an **Agent API** channel, for example `https://app.everruns.com/api/v1/channels/appchan_…`. The URL stays the same as you change the agent's configuration. Callers authenticate with agent keys created on that channel; a key's secret starts with `evr_ak_` and is shown once.

The same routes and request and response shapes are served by Everruns Cloud, a self-hosted server, and a serve app you run yourself. Each SDK (Python, TypeScript, Rust) has an `AgentClient` for them.

Routes, relative to the agent URL:

- `GET /` returns the agent card: name, description, accepted input and credentials.
- `POST /sessions` starts a conversation, `GET /sessions` lists the caller's own.
- `POST /sessions/{id}/messages` sends a message. It starts a turn, or steers the one already running.
- `GET /sessions/{id}/sse` follows events live and resumes after a dropped connection. `GET /sessions/{id}/events` pages through them.
- `POST /sessions/{id}/question-answers` and `POST /sessions/{id}/tool-approvals` answer an agent that is waiting on the caller.
- `POST /sessions/{id}/cancel` stops the running turn.

An agent key never reaches the management API. It cannot list your agents, read another agent, or create keys. Within the agent, a key sees only the sessions it started; any other session answers `404`, the same as one that does not exist.

Keys belong to the organization, not to the member who created them. Name each key after the application that holds it. Rotating a key issues a new secret and keeps the old one working for an overlap you choose (24 hours by default, up to 168), so you can deploy the new secret before the old one stops. Revoking stops both.

## Calling it

`AgentClient` reads `EVERRUNS_AGENT_URL` and `EVERRUNS_AGENT_KEY` from the environment:

```python
from everruns_sdk import AgentClient

async with AgentClient() as agent:
    reply = await agent.run("Where is order 42?")
    print(reply)
```

`run` starts a session, sends the message, follows the event stream until the turn ends, and returns the agent's reply. Pass a session id to continue a conversation. When you need more control, the same client has the session calls directly: `create_session`, `send_message`, `stream_events`, `list_events`, `cancel`, and the answers to questions and tool approvals. `AgentClient` ships in SDK 0.3, and Python users want `everruns-sdk` 0.3.1 or later.

There is nothing SDK-specific on the wire. The same calls are plain HTTP:

```bash
curl -X POST "$EVERRUNS_AGENT_URL/sessions" \
  -H "Authorization: Bearer $EVERRUNS_AGENT_KEY"

curl -X POST "$EVERRUNS_AGENT_URL/sessions/$SESSION_ID/messages" \
  -H "Authorization: Bearer $EVERRUNS_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":{"role":"user","content":[{"type":"text","text":"Where is order 42?"}]}}'

curl -N "$EVERRUNS_AGENT_URL/sessions/$SESSION_ID/sse?after_sequence=0" \
  -H "Authorization: Bearer $EVERRUNS_AGENT_KEY"
```

## What a caller sees

An agent's event stream holds a lot: tool names, arguments, results, internal errors. Most callers should see none of that. The channel's **visibility** decides:

- `messages`: user input, the final assistant text, turn boundaries, and any question or approval waiting on the caller.
- `activity` (the default): adds "a tool started" and "a tool finished", with the channel's own activity text, never tool names or arguments.
- `full`: the raw events, for callers who own both ends.

Errors follow the same idea. By default a failed turn reports only a public error code; `detailed` errors are opt-in.

Tool approvals stay with you unless you say otherwise. By default someone with access to the agent in Everruns decides, and the caller only sees that a call is waiting. Set the channel's approvals to `caller` and the key holder sees the tool and its arguments and decides. Questions from the agent (`ask_user`) are answered by the caller, except one that asks for a credential, which a person completes in Everruns.

## Acting for your own users

A key acts as your application. Most applications have users of their own, and their conversations should not mix. Create the key with the **end user** permission and name the user on each request. In the SDKs:

```python
alice = agent.for_end_user("customer-42")
await alice.run("Where is my order?")
```

This sends an `End-User` header. Sessions then belong to that user: the key acting as itself, or for another user, does not see them. When the agent uses per-user connections, a turn started for `customer-42` uses that user's connections, never the application's.

If your users already sign in with your own identity provider, they can call the agent directly with those tokens. List the provider in the channel's `auth_methods` (OpenID Connect, or OAuth 2.0 token introspection). Everruns only validates those tokens; it never issues them. Each token subject becomes its own end user. Members of your organization can also call with their own personal access token when you turn on **Organization members**.

## From a browser

An agent key must never ship in a browser or mobile app. Instead, your backend exchanges it for a **runtime token** for one user:

```python
token = await agent.for_end_user("customer-42").runtime_token()
# hand token["access_token"] to the page; it lasts 15 minutes and works on this agent only
```

The token cannot be exchanged for another, and end users always get the public error codes. List your page's origin, such as `https://app.example.com`, under **Browser origins** on the channel, and the browser can call the agent URL directly.

## Production limits

Two channel settings and one request header for production traffic:

- **Daily spending limit per caller.** One key, or one end user, can spend at most this much on the agent per UTC day. Past it, starting a session or sending a message answers `429` until the next day. Reading still works, and a turn already running finishes.
- **Rate limit per minute**, per caller and client IP.
- **Safe retries.** Send an `Idempotency-Key` header when you start a session or send a message (the SDKs take an `idempotency_key` argument). A retry of the same request within 24 hours returns the first response instead of starting a second session or sending the message twice.

## The same API on your own machine

The Agent API is not tied to Everruns Cloud. A [serve](https://everruns.com/docs/framework/serve-tutorial/) app, an agent you build with the Everruns Framework and run yourself, serves the same routes and shapes at `/v1/channels/{agent}`, and can require API keys, OpenID Connect, or OAuth 2.0 introspection in front of them.

So one client works against both. Point `EVERRUNS_AGENT_URL` at `http://localhost:3000/v1/channels/support` while you develop, and at the hosted agent URL when you deploy. The client code does not change.

## Replacing API endpoint channels

The older `api_endpoint` channel type is gone. Existing `api_endpoint` channels were converted to Agent API channels automatically, with the same keys and their sessions carried over. Clients need to move to the routes under `/v1/channels/{channel_id}`: the old `/v1/apps/{app}/api/{chan}` routes now return `410`.

## Getting started

Add an Agent API channel to an agent, publish it, create a key, and call it.

- [Call your agent from code](https://everruns.com/docs/how-to/call-your-agent-from-code/): keys, the SDKs, end users, browsers, and spend limits, step by step.
- [Agent API reference](https://everruns.com/docs/features/agent-api/): every route, credential and channel setting.
- [Tutorial: serve an agent and call it from code](https://everruns.com/docs/framework/serve-tutorial/): the same `AgentClient` against an agent you run yourself.

---

## Machine-readable entry points

- [/llms.txt](https://everruns.com/llms.txt): index of this site written for language models.
- [/llms-full.txt](https://everruns.com/llms-full.txt): every page on this site as one document.
- [/auth.md](https://everruns.com/auth.md): how an agent obtains Everruns API credentials.
- [/.well-known/ai-catalog.json](https://everruns.com/.well-known/ai-catalog.json): ARD capability manifest.
- [/.well-known/mcp/server-card.json](https://everruns.com/.well-known/mcp/server-card.json): MCP server card for Everruns Managed Demo.
- [/.well-known/agent-skills/index.json](https://everruns.com/.well-known/agent-skills/index.json): agent skills for working with Everruns.

Any page on this site serves Markdown to `Accept: text/markdown`.
