Agents: AI systems OTAS monitors

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

Field	Description
`id`	UUID, auto-generated. Passed as `X-OTAS-AGENT-ID` where required.
`name`	Human-readable label for this agent.
`description`	Optional description of what the agent does.
`provider`	The AI provider powering this agent, e.g., `"Anthropic"`, `"OpenAI"`, `"Google"`.
`project`	The project this agent belongs to. An agent can only belong to one project.
`created_by`	The user who created the agent. Must be a project Admin.
`is_active`	Whether 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>

Field	Description
`id`	UUID identifier for the key record.
`prefix`	Short identifier used to look up the key without exposing the secret.
`expires_at`	Keys expire 30 days after creation.
`revoked_at`	Set when a key is explicitly revoked.
`active`	`false` 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

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.

Pass the key in API calls

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

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.

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.

Field	Description
`id`	UUID, auto-generated. Used as the session reference in event logging.
`agent`	The agent this session belongs to.
`agent_key`	The key used to authenticate the session creation request.
`meta`	Arbitrary 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.

Get Started

Core Concepts

Agent Integration

Analytics & Dashboard

Deployment

Agents: AI systems OTAS monitors

Agent fields

Creating an agent

Agent keys

Key lifecycle

Agent sessions

Creating a session

End-to-end flow

1. Create agent

2. Store the key

3. Create a session

4. Log events

​Agent fields

​Creating an agent

​Agent keys

​Key lifecycle

​Agent sessions

​Creating a session

​End-to-end flow

1. Create agent

2. Store the key

3. Create a session

4. Log events

Agent fields

Creating an agent

Agent keys

Key lifecycle

Agent sessions

Creating a session

End-to-end flow