Agent API tasks

Agent task lifecycle from queued work through running, waiting for approval, and completed evidence.

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

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.

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.

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.

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:

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.

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

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.

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."
  }'

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.

Agents API

Review the resource model and SDK shape.

Permissions and security

Understand grants, approvals, credential proxying, and review boundaries.

Overview

Workflows

Controls

Reference

Create an agent

Start a session

Submit a turn

Resolve an approval

Create a repository change request

Agents API

Permissions and security

​Create an agent

​Start a session

​Submit a turn

​Resolve an approval

​Create a repository change request

​Related topics

Agents API

Permissions and security

Create an agent

Start a session

Submit a turn

Resolve an approval

Create a repository change request

Related topics