Start a new agent session and receive a session JWT. The JWT scopes all Brain event logs to this run and is passed as X-OTAS-AGENT-SESSION-TOKEN.
Call this endpoint at the start of every agent task or run. The session JWT you receive scopes all events, traces, and logs produced during that task back to a single identifiable session. Pass the returned token in the X-OTAS-AGENT-SESSION-TOKEN header on every subsequent OTAS call made within that run.
Authentication for this endpoint uses the agent’s API key (X-OTAS-AGENT-KEY), not a user token. The key must be active and unexpired.
Optional JSON object with task context. Use it to attach structured metadata to the session for filtering and debugging, e.g. { "task": "summarize", "input_length": 512 }. Defaults to {}.
Signed HS256 JWT. Valid for 30 days from issuance. The JWT payload contains:
agent_session_id — UUID of the newly created session
agent_id — UUID of the authenticating agent
iat — issued-at timestamp
exp — expiry timestamp (30 days after iat)
Create a new session for every distinct task or process. Never reuse a session JWT across separate, independent runs — doing so conflates their events under a single session, making attribution and debugging unreliable.
Do not share a session JWT between parallel agent instances. Each concurrent run must start its own session so that events are attributed correctly.