> ## 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.

# Agent API tasks

> Create an agent, start a session, submit a turn, resolve an approval, and create a repository change request

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/akua-1dce587a/AEEz0U2s7Do2sYaM/images/heros/agents-tasks-light.svg?fit=max&auto=format&n=AEEz0U2s7Do2sYaM&q=85&s=d4e9a06fbdec2ffcac36521c1fc378d1" alt="Agent task lifecycle from queued work through running, waiting for approval, and completed evidence." width="1536" height="864" data-path="images/heros/agents-tasks-light.svg" />

  <img className="hidden dark:block" src="https://mintcdn.com/akua-1dce587a/AEEz0U2s7Do2sYaM/images/heros/agents-tasks-dark.svg?fit=max&auto=format&n=AEEz0U2s7Do2sYaM&q=85&s=8bab341d1533650c9702e9e1e18bc66f" alt="Agent task lifecycle from queued work through running, waiting for approval, and completed evidence." width="1536" height="864" data-path="images/heros/agents-tasks-dark.svg" />
</Frame>

Use these tasks when you integrate directly with the Agents API. All examples assume you have an API token and a workspace ID.

```bash theme={null}
export AKUA_API_TOKEN="..."
export AKUA_WORKSPACE_ID="ws_..."
export AKUA_API_URL="https://api.akua.dev/v1"
```

## Create an agent

Create an agent for a reusable automation identity. Keep grants narrow and add ambient triggers only when the agent should start from platform signals.

```bash theme={null}
curl "$AKUA_API_URL/agents" \
  -H "Authorization: Bearer $AKUA_API_TOKEN" \
  -H "Akua-Context: $AKUA_WORKSPACE_ID" \
  -H "Idempotency-Key: agent-prod-triage-001" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production deploy triage",
    "description": "Investigates failed installs and prepares reviewable fixes.",
    "capabilities": ["CHAT", "CODING", "AMBIENT"],
    "grants": [
      { "resource": "install", "actions": ["read"] },
      { "resource": "cluster", "actions": ["read"] },
      { "resource": "repository_change_request", "actions": ["read", "create", "continue"] }
    ]
  }'
```

## Start a session

Create a session when you want a durable conversation or task thread. A session can be reused across multiple turns.

```bash theme={null}
curl "$AKUA_API_URL/agent_sessions" \
  -H "Authorization: Bearer $AKUA_API_TOKEN" \
  -H "Akua-Context: $AKUA_WORKSPACE_ID" \
  -H "Idempotency-Key: session-prod-triage-001" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agt_...",
    "origin": "API",
    "title": "Investigate production install failure"
  }'
```

## Submit a turn

Submit a turn to ask the agent to do work. Use a runtime hint when you know whether the task needs a retained runtime; policy still decides what runs.

```bash theme={null}
curl "$AKUA_API_URL/agent_turns" \
  -H "Authorization: Bearer $AKUA_API_TOKEN" \
  -H "Akua-Context: $AKUA_WORKSPACE_ID" \
  -H "Idempotency-Key: turn-prod-triage-001" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "ags_...",
    "message": "Investigate why install inst_... failed after the latest update. Create a repository change request only if you find a likely source or config fix.",
    "runtime_hint": "AUTO"
  }'
```

Stream events while the turn runs:

```bash theme={null}
curl "$AKUA_API_URL/agent_events:stream?turn=atn_..." \
  -H "Authorization: Bearer $AKUA_API_TOKEN" \
  -H "Akua-Context: $AKUA_WORKSPACE_ID" \
  -H "Accept: text/event-stream"
```

## Resolve an approval

Approval requests are runtime gates. Resolve them with both `Idempotency-Key` and `If-Match` so retries are safe and stale approvals are rejected.

```bash theme={null}
curl "$AKUA_API_URL/approval_requests?state=PENDING&session=ags_..." \
  -H "Authorization: Bearer $AKUA_API_TOKEN" \
  -H "Akua-Context: $AKUA_WORKSPACE_ID"
```

```bash theme={null}
curl "$AKUA_API_URL/approval_requests/apr_...:resolve" \
  -H "Authorization: Bearer $AKUA_API_TOKEN" \
  -H "Akua-Context: $AKUA_WORKSPACE_ID" \
  -H "Idempotency-Key: approve-runtime-action-001" \
  -H "If-Match: 3" \
  -H "Content-Type: application/json" \
  -d '{ "decision": "APPROVE" }'
```

## Create a repository change request

Create a repository change request when an agent or integration needs a reviewable fork-backed change. The response returns the change request resource. Use `:create_token` to mint a scoped token for the fork.

```bash theme={null}
curl "$AKUA_API_URL/repository_change_requests" \
  -H "Authorization: Bearer $AKUA_API_TOKEN" \
  -H "Akua-Context: $AKUA_WORKSPACE_ID" \
  -H "Idempotency-Key: rcr-prod-fix-001" \
  -H "Content-Type: application/json" \
  -d '{
    "parent_repository_id": "repo_...",
    "change_type": "inputs_change",
    "title": "Restore missing database URL",
    "description": "Prepared after failed-install triage found the runtime env var was removed."
  }'
```

```bash theme={null}
curl "$AKUA_API_URL/repository_change_requests/rcr_...:create_token" \
  -H "Authorization: Bearer $AKUA_API_TOKEN" \
  -H "Akua-Context: $AKUA_WORKSPACE_ID" \
  -H "Idempotency-Key: rcr-prod-fix-token-001" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "write",
    "expires_in_seconds": 1800
  }'
```

After the fork contains commits, accept, reject, or withdraw the change request through its lifecycle actions.

## Related topics

<CardGroup cols={2}>
  <Card title="Agents API" icon="code" href="/agents/api">
    Review the resource model and SDK shape.
  </Card>

  <Card title="Permissions and security" icon="shield-check" href="/agents/permissions-and-security">
    Understand grants, approvals, credential proxying, and review boundaries.
  </Card>
</CardGroup>