Everruns
← Blog

Introducing the Agent API: A Stable, Unified Way to Invoke Agents

Looking up at glass office towers against a blue sky

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.

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:

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:

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:

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:

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