Quickstart

Quickstart

quickstart:
  time: 5 min
  prerequisites:
    - running agents service (docker-compose or k8s)
    - valid JWT or API key from the identity service
  result: streaming SSE response from a live agent

This guide walks through the minimal path: create an agent, open a session, and send a prompt. You will see SSE chunks arrive in your terminal.

Prerequisites

You need a running agents service and a bearer token. The token is issued by the identity service. For local development, the make dev-token target in paper-board/identity issues a short-lived JWT against the local dev stack.

Set the base URL and token in your shell:

export BASE_URL=http://localhost:8080
export TOKEN=<your-jwt-or-api-key>

Step 1 — Create an agent

curl -s -X POST "$BASE_URL/v1/agents" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name":         "my-first-agent",
    "slug":         "my-first-agent",
    "model":        "claude-opus-4-7",
    "systemPrompt": "You are a helpful assistant."
  }' | jq .

Expected response (201 Created):

{
  "id":           "018f1a2b-0000-7000-8000-000000000001",
  "orgId":        "018f1a2b-0000-7000-8000-000000000000",
  "name":         "my-first-agent",
  "slug":         "my-first-agent",
  "model":        "claude-opus-4-7",
  "systemPrompt": "You are a helpful assistant.",
  "createdAt":    "2026-05-24T10:00:00Z",
  "updatedAt":    "2026-05-24T10:00:00Z"
}

Save the agent id:

export AGENT_ID=018f1a2b-0000-7000-8000-000000000001

Step 2 — Open a session

A session scopes a conversation to one agent. Sessions are cheap; create one per user interaction.

export SESSION_ID=$(curl -s -X POST "$BASE_URL/v1/sessions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"agentId\": \"$AGENT_ID\"}" | jq -r .id)
echo "session: $SESSION_ID"

Step 3 — Send a prompt and watch the stream

curl -s -N -X POST "$BASE_URL/v1/sessions/$SESSION_ID/prompt" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "messages": [
      {"role": "user", "content": "Explain Go interfaces in one sentence."}
    ]
  }'

You will see a stream of SSE lines:

data: {"type":"text","content":"Go "}
data: {"type":"text","content":"interfaces "}
data: {"type":"text","content":"define behavior..."}
data: {"type":"done","tokensIn":12,"tokensOut":9}

The stream ends when a done event arrives. If the agent invokes a tool, you will also see tool_use and tool_result events before the final text.

Request flow

sequenceDiagram
  autonumber
  participant Client
  participant agents as agents HTTP API
  participant LLM as Anthropic API
  participant compute as compute gRPC

  Client->>agents: POST /v1/agents  →  201
  Client->>agents: POST /v1/sessions  →  201
  Client->>agents: POST /v1/sessions/{id}/prompt (SSE)
  agents->>LLM: Stream(model, system, messages)
  LLM-->>agents: text chunks
  agents-->>Client: data: {"type":"text", ...}
  LLM-->>agents: tool_use block
  agents->>compute: ExecCommand gRPC
  compute-->>agents: stdout / exit_code
  agents->>LLM: tool_result → continue
  LLM-->>agents: final text + done
  agents-->>Client: data: {"type":"done", ...}

What to do next

• Read the API reference for all endpoints, error codes, and SSE event types.
• Read Operations for environment variables, Helm values, and migrator commands.