Skip to main content
The OTAS Agent Manifest is the integration contract every OTAS-connected agent must follow. It defines three operational phases — session creation, in-domain request handling, and out-of-domain event logging — that together give OTAS full observability over everything your agent does. If your agent deviates from this contract, events will be missing or unauthenticated, and analytics in Brain will be incomplete.

​
Operational phases

Before walking through the full workflow, it helps to understand the three phases at a high level:
  1. Session creation — At the start of every new process, your agent calls the UASAM session endpoint to obtain a short-lived JWT. This JWT becomes its identity for the duration of the run.
  2. In-domain requests — For any call made within your project domain, your agent attaches the session JWT as the X-OTAS-AGENT-SESSION-TOKEN header. The server-side OTAS middleware captures the event automatically.
  3. Out-of-domain requests — For any external API call (outside your project domain), your agent makes the call normally, then immediately POSTs a structured event log to Brain using both the agent key and the session token.

​
Full integration workflow

1

Obtain your credentials

Your agent needs three fixed values before it can integrate with OTAS. These are set at deployment time and must not be changed or exposed during operation.
CredentialDescription
PROJECT_IDUUID of your OTAS project
AGENT_KEYAgent key in the format agent_<prefix>_<secret> — valid for 30 days
PROJECT_DOMAINBase URL of the project your agent operates within (e.g., https://usc.edu)
2

Create a session at process start

Call the UASAM session creation endpoint at the beginning of every new task or process. Never skip this step and never reuse a token from a previous run.
curl -X POST http://localhost:8000/api/agent/v1/session/create/ \
  -H "X-OTAS-AGENT-KEY: agent_abc123_yoursecrethere" \
  -H "Content-Type: application/json" \
  -d '{ "meta": {} }'
The meta field accepts any JSON object. Use it to record task context such as the task name, user-facing operation, or input summary.A successful response returns a JWT you must store for the rest of the session:
{
  "status": 1,
  "status_description": "agent_session_created",
  "response": {
    "Header_value": "X-OTAS-AGENT-SESSION-TOKEN",
    "jwt_token": "<YOUR_SESSION_JWT>"
  }
}
Store the value of jwt_token. This is your X-OTAS-AGENT-SESSION-TOKEN for this session.
3

Attach the session token to every in-domain request

For any API call made within your project domain, include the session JWT as a request header. The OTAS server-side middleware on your backend reads this header and logs the event automatically — you do not need to call Brain yourself.
curl -X GET https://your-project-domain.example.com/api/v1/some-resource \
  -H "X-OTAS-AGENT-SESSION-TOKEN: <YOUR_SESSION_JWT>"
This header must be present on every single request made within the project domain. Missing it means the event will not be captured by OTAS.
4

Log out-of-domain requests manually

When your agent calls an API outside the project domain, it must manually POST the event to Brain immediately after the external call completes. Use both the agent key and session token as headers.
curl -X POST http://localhost:8002/api/v1/backend/log/agent/ \
  -H "X-OTAS-AGENT-KEY: agent_abc123_yoursecrethere" \
  -H "X-OTAS-AGENT-SESSION-TOKEN: <YOUR_SESSION_JWT>" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "your-project-uuid",
    "path": "/api/v1/the-external-path",
    "method": "POST",
    "status_code": 200,
    "latency_ms": 123.45,
    "request_size_bytes": 512,
    "response_size_bytes": 1024,
    "request_headers": "{\"Content-Type\": \"application/json\"}",
    "request_body": "{\"your\": \"request body\"}",
    "query_params": "",
    "post_data": "",
    "response_headers": "{\"Content-Type\": \"application/json\"}",
    "response_body": "{\"your\": \"response body\"}",
    "request_content_type": "application/json",
    "response_content_type": "application/json",
    "custom_properties": {},
    "error": "",
    "metadata": {}
  }'
Fill in all fields accurately based on the actual request and response. The latency_ms value must reflect the real measured round-trip time — it is used directly in p50/p95/p99 analytics.

​
Behavioral rules

These rules are mandatory for all OTAS-integrated agents. Violating any of them will result in missing or rejected events.
RuleRequirement
Session creationAlways create a new session at the start of every new process
In-domain requestsAlways include X-OTAS-AGENT-SESSION-TOKEN on every request within the project domain
Out-of-domain requestsAlways log via the Brain logging endpoint immediately after the external call
Agent key usageUse the agent key only in session creation and out-of-domain logging headers
Session token reuseNever reuse a session token across separate processes

​
Quick reference

ItemValue
Agent key headerX-OTAS-AGENT-KEY
Session token headerX-OTAS-AGENT-SESSION-TOKEN
Session creation URLhttp://localhost:8000/api/agent/v1/session/create/
Out-of-domain log URLhttp://localhost:8002/api/v1/backend/log/agent/
Agent key formatagent_<prefix>_<secret>
Agent key validity30 days

Build docs developers (and LLMs) love

Get started for freeTalk to us