Skip to main content
An Agent is the entity within your project that OTAS monitors. Each agent maps to a distinct AI system or component in your architecture—for example, a customer-support LLM, a document processing pipeline, or a code generation service. Agents have their own API keys and sessions, which lets OTAS attribute every logged event to the right system.

​
Agent fields

FieldDescription
idUUID, auto-generated. Passed as X-OTAS-AGENT-ID where required.
nameHuman-readable label for this agent.
descriptionOptional description of what the agent does.
providerThe AI provider powering this agent, e.g., "Anthropic", "OpenAI", "Google".
projectThe project this agent belongs to. An agent can only belong to one project.
created_byThe user who created the agent. Must be a project Admin.
is_activeWhether the agent is currently active.

​
Creating an agent

Only project Admins can create agents. A single API call creates both the Agent record and an initial AgentKey, so you have a working key immediately. 
POST /api/agent/v1/create/
X-OTAS-USER-TOKEN: <your-jwt>
X-OTAS-PROJECT-ID: <project-uuid>

{
  "agent_name": "Support Bot",
  "agent_description": "Handles customer support queries",
  "agent_provider": "Anthropic"
}
The response contains both the agent object and the agent_key object—including the full key value, which is shown only once.

​
Agent keys

An AgentKey is a credential issued to a specific agent. It is distinct from a Backend SDK Key: while an SDK key authenticates your server-side middleware on behalf of any agent, an agent key authenticates the agent itself. Key format: agent_<prefix>_<secret>
FieldDescription
idUUID identifier for the key record.
prefixShort identifier used to look up the key without exposing the secret.
expires_atKeys expire 30 days after creation.
revoked_atSet when a key is explicitly revoked.
activefalse if the key has expired or been revoked.
Rotating a key via POST /api/agent/v1/agents/key/create/ immediately revokes all existing active keys for that agent before issuing the new one. Update your agent’s configuration before the old key expires to avoid downtime.

​
Key lifecycle

1

Key is issued at agent creation

The initial key is returned in the agent_key.api_key field of the create response. Store it securely—it will not be shown again.
2

Pass the key in API calls

Your agent sends X-OTAS-AGENT-KEY: agent_<prefix>_<secret> to authenticate when creating sessions or logging events.
3

Rotate the key before expiry

Call POST /api/agent/v1/agents/key/create/ with { "agent_id": "<uuid>" }. This revokes the current key and issues a fresh one expiring 30 days from now.
4

Revoke if compromised

Call POST /api/agent/v1/agents/key/revoke/ with { "agent_key_id": "<uuid>" }. The key is immediately invalidated.

​
Agent sessions

An AgentSession scopes a group of events to a single task or run. Every time your agent starts a new task, it should create a session. All events logged during that task are then linked to the session, making it easy to replay or debug the entire interaction.
FieldDescription
idUUID, auto-generated. Used as the session reference in event logging.
agentThe agent this session belongs to.
agent_keyThe key used to authenticate the session creation request.
metaArbitrary JSON for run context, e.g., { "user_id": "u_123", "task": "summarize" }.

​
Creating a session

POST /api/agent/v1/session/create/
X-OTAS-AGENT-KEY: agent_<prefix>_<secret>

{ "meta": { "task_id": "t_001", "user_id": "u_42" } }
The response contains a short-lived JWT in the jwt_token field. Pass this as X-OTAS-AGENT-SESSION-TOKEN when logging events so OTAS associates them with this session.

​
End-to-end flow

1. Create agent

Call POST /api/agent/v1/create/ as a project Admin. Receive the agent UUID and initial AgentKey.

2. Store the key

Save agent_<prefix>_<secret> in your agent’s environment. The plain-text key is never stored by OTAS.

3. Create a session

Before each task, call POST /api/agent/v1/session/create/ with X-OTAS-AGENT-KEY. Receive a session JWT.

4. Log events

Send X-OTAS-AGENT-SESSION-TOKEN with each event so OTAS groups all calls under the correct session.

Build docs developers (and LLMs) love

Get started for freeTalk to us