> ## Documentation Index
> Fetch the complete documentation index at: https://docs.akua.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Agents API
> Public API resources for creating sessions, submitting turns, streaming events, and resolving approvals
The Agents API is designed as a set of flat, workspace-scoped resources. Use the generated API reference for endpoint parameters, request bodies, response schemas, and try-it examples. This page explains how the resources fit together.
## API reference
Create and manage durable agent configurations.
Start, list, retain, archive, and detect conflicts for task sessions.
Submit work, inspect results, cancel turns, and emit events.
Read and stream agent progress, widgets, and artifacts.
Browse curated starting points for common agent workflows.
Read and update communication defaults and learning-mode settings.
List and resolve human approval gates.
Review and accept agent-prepared repository changes.
Workspace-scoped requests resolve the workspace from your credential — implied by a workspace API token, or selected with the optional `Akua-Context` header for broad credentials.
## SDK shape
The generated SDK groups methods by OpenAPI operation ID, not by URL nesting. A TypeScript client should read naturally:
```ts TypeScript theme={null}
const agent = await client.agents.create({
name: 'Production deploy triage',
capabilities: ['CHAT', 'CODING', 'AMBIENT']
});
const templates = await client.agentTemplates.list();
const failedInstallTriage = templates.data.find(
(template) => template.id === 'agtpl_failedinstalltriage01'
);
const session = await client.agentSessions.create({
agent_id: agent.id
});
const turn = await client.agentTurns.create(
{
session_id: session.id,
message:
'Investigate the failed production install and draft a repository change request if needed.'
},
{ idempotencyKey: 'turn-2026-05-13-prod-failure' }
);
for await (const event of client.agentEvents.stream({ turn: turn.id })) {
if (event.type === 'widget.created') {
renderAgentWidget(event.data.widget_type, event.data);
continue;
}
console.log(event.type, event.data);
}
```
## Why flat paths
The API does not use `/v1/agent/...` or deeply nested paths. Flat resources make common workspace queries easier:
* List all running turns in a workspace.
* Show every pending approval request.
* Stream events for a session or turn.
* Render dashboard chat widgets from normalized events.
* Reuse a session when an ambient trigger continues existing work.
* Inspect repository change requests across agents to avoid duplicate work.
OpenAPI tags and documentation pages provide the product grouping users expect, while the URLs stay stable and resource-oriented.
## Protocol compatibility
Akua supports Agent Client Protocol as a compatibility adapter, not as a separate product data model. The ACP bridge maps session creation, prompts, streaming updates, and permission prompts to the same `agent_sessions`, `agent_turns`, `agent_events`, and `approval_requests` resources.
Use the REST API when you need workspace-scoped management, SDK resources, list filters, audit history, quotas, billing controls, retention, or ambient agent configuration. Use ACP when an editor or agent client wants a standard interactive protocol for talking to an Akua-hosted agent.
ACP compatibility should not force Akua to copy protocol details before they stabilize. ACP currently centers on sessions, prompt turns, updates, tool calls, plans, permissions, and capability negotiation. Multi-agent and forked-session work is still evolving, so Akua keeps canonical lineage in its own resources and maps to ACP where a client supports it.
The bridge is intentionally stateless. It does not create ACP-only canonical rows, ACP IDs, or a separate approval table. Unknown ACP features are ignored when they are advisory, or represented as `agent_events` artifacts when the information should remain visible in the dashboard and event stream.
Zed's external-agent model is a useful comparison. Zed uses ACP to connect external agents to the editor UI, but external agents still keep their own authentication, billing relationship, configuration files, and feature limits. Akua follows the same separation: ACP is an adapter for interactive agent clients, while Akua resources own workspace scope, approvals, repository change requests, quotas, retention, and audit history.
ACP permission prompts and Codex-style approvals are runtime gates. Akua maps them into `approval_requests` so they can be listed, audited, expired, and resolved from the dashboard or API. Repository change requests stay separate: they are durable change artifacts with diffs, validation, and review state. Accepting one can itself require an approval request when policy demands it.
## Integration examples
Use the REST API or generated SDK for durable product integration. Use Code Mode/MCP when an agent needs to discover and call the Akua API as a tool. Use ACP when an editor or agent client already speaks the protocol and wants a standard interactive stream.
```ts TypeScript SDK theme={null}
const approvals = await client.approvalRequests.list({
state: 'PENDING',
agent: agent.id
});
await client.approvalRequests.resolve(
approvals.data[0].id,
{ decision: 'APPROVE' },
{
idempotencyKey: 'approve-prod-fix-001',
ifMatch: approvals.data[0].etag
}
);
```
```js Code Mode theme={null}
async () => {
const res = await platform.request({
method: 'GET',
path: '/v1/repository_change_requests',
query: { state: 'READY' },
headers: { 'Akua-Context': 'ws_123' }
});
return res.body.data.map((change) => ({
id: change.id,
parent_repository_id: change.parent_repository_id,
state: change.state
}));
}
```
```json ACP theme={null}
{
"method": "session/prompt",
"params": {
"message": "Investigate the failed install and ask before accepting any change."
}
}
```
## Schema notes
Some fields are intentionally split so clients can distinguish preferences from policy-controlled results:
| Field | Resource | Meaning |
| ------------------------- | ------------------------ | -------------------------------------------------------------------------------------------------- |
| `communication_profile` | Session | Resolved active profile for beginner, intermediate, advanced, expert, or adaptive language. |
| `runtime_hint` | Turn | Client preference such as `AUTO`, `CODE_MODE`, or `RETAINED_RUNTIME`. |
| `runtime_decision` | Turn | Whether the runtime request was allowed, denied, or requires approval. |
| `resolved_execution_mode` | Turn | What Akua actually used after applying agent policy and workspace limits. |
| `origin` | Session and turn | Where the work came from: dashboard, API, MCP, ACP, ambient, or system. |
| `usage_summary` | Agent, session, and turn | Provider cost, runtime compute, storage, MCP/API calls, and ambient trigger counts when populated. |
| `agent_turn_id` | Snippet and snippet run | Optional attribution for session-scoped generated snippets and prepared actions. |
Widget events should be typed. A `widget.created` event carries `widget_type`, `schema_version`, `resource_refs`, optional `reactive_bindings`, and `actions`. Initial widget types include `approval_card`, `choice_card`, `status_card`, `navigation_hint`, and `repository_change_request_review`.
Actions are prepared platform actions, not arbitrary client code. Reactive bindings let dashboard widgets stay current while API and ACP clients can ignore them or render their own equivalents.
Widgets may represent a whole interaction, not just one resource. For example, an agent can emit a card that combines a repository change request, an install status, a documentation link, and prepared reply buttons. Akua can also synthesize default widgets from canonical resources; resource state remains the source of truth.
V1 does not need a separate widget-action endpoint. Clients execute the underlying action through the canonical resource API, such as resolving an approval request, creating a turn, submitting structured input, running an attributed snippet action, or navigating to a dashboard path. Attributed snippet runs roll up to the source turn's `usage_summary.api_call_count`.
## Idempotency and state
Mutation requests that create work use `Idempotency-Key` so clients can safely retry interrupted requests. Mutable resources include `etag` and use `If-Match` when an update depends on the current state.
Clients should not set lifecycle state directly. Use resource actions such as cancel a turn, resolve an approval request, or archive a session.
## Related topics
Authenticate API clients and set workspace scope.
Jump into the generated endpoint reference.
Let external agents call the API through Code Mode.
Understand grants, approvals, and audit events.