Runtime and scopes

The main idea behind agent runtime calls is simple: each request carries an agent identity plus any extra scope hints needed to narrow retrieval.

Request shape

Use the OpenAI-compatible chat endpoint and pass the agent identity by route or header.

POST /v1/chat/completions
Authorization: Bearer acm_...
Content-Type: application/json
X-Achiral-Agent: release-readiness-agent
X-Achiral-Project: payments
X-Achiral-Scan-Session: optional-session-id

How the runtime uses scope

The runtime resolves access before retrieval.

In practice, that means it checks:

1. the token;
2. the organization;
3. the agent identity; and
4. any extra narrowing hints such as project or scan-session values.

Scope hints

Scope hints narrow retrieval. They do not grant extra access.

Scope	Use it for
Agent	The agent identity for the responsibility
Client or account	The durable boundary attached to the agent
Project	A narrower retrieval hint inside that boundary
Scan session	A run-specific narrowing hint

Good write-back behavior

When you decide what should persist across runs, store the outcomes that help later work, such as:

• decisions;
• approvals;
• stable preferences;
• implementation choices; and
• handoff summaries.

Avoid treating every transient runtime detail as durable memory.

Production guidance

Start with one narrow agent and review whether the retrieved context is helping. If the scope is too broad, split the workflow or pass a narrower project hint.

For operational controls, stay on this page and tighten scope before broadening rollout.