Agent Integration

FastClaw Agent Integration

FastClaw is an agent runtime. It stores agent configuration, runs the agent loop with its tools and sandbox, keeps sessions and memory, and meters usage. Your application owns everything about its users: sign-in, which user may use which agent, chat records, billing. Your backend calls FastClaw; FastClaw never calls your app back and never knows your users.

Follow this guide over guesses from other FastClaw code (the dashboard's /api/* endpoints are internal and change without notice). Integrations use /v1/* only.

1. Configure the connection first

The integration needs two values. Never hardcode them; read them on the server side from configuration (environment variables or the app's secret store):

If either is missing, stop and ask the user for it — tell them where to find it (table above) and which key type the integration needs (section 2). Add both to the project's environment template (.env.example or similar) without real values.

Then verify the connection:

bashCopy code
curl -s "$FASTCLAW_BASE_URL/v1/agents" -H "Authorization: Bearer $FASTCLAW_API_KEY"

A 200 lists the agents the key may use; 401 unauthorized means a wrong or revoked key.

Never expose the key to browsers or mobile apps. Clients talk to your backend; your backend talks to FastClaw.

2. Pick the scenario

A user key reaches every agent of its FastClaw account. For scenario B, use a FastClaw account dedicated to this integration (and one per environment, e.g. myapp-prod / myapp-dev) so the key can't touch agents used elsewhere.

Whichever scenario: your app must check "may this user use this agent?" before every call. FastClaw only isolates accounts and API keys from each other.

3. Scenario A — chat with fixed agents

1. The user creates the agent(s) in the FastClaw console and issues an Agent API key granted to them.

2. Find the agents the key may use:

   bashCopy code
   curl -s "$FASTCLAW_BASE_URL/v1/agents" -H "Authorization: Bearer $FASTCLAW_API_KEY"
   

   jsonCopy code
   { "agents": [ { "id": "agt_2834a7a1e660d509b83d", "display_name": "Image Editor", "description": "…", "model": "…", "metadata": {}, "created_at": "…", "updated_at": "…" } ], "has_more": false }
   

3. Keep the agent ids in configuration (e.g. FASTCLAW_AGENT_ID, or a map from your feature to an agent id when there are several). With a single granted agent, chat requests may omit agent_id; name it anyway once the app may use more than one.

4. Chat (section 5).

4. Scenario B — manage agents

Agents created with the API belong to the key's FastClaw account. FastClaw does not record which of your users an agent is for — keep that mapping in your database (and mirror it into metadata if you want to filter by it).

Create — POST /v1/agents

bashCopy code
curl -s "$FASTCLAW_BASE_URL/v1/agents" \
  -H "Authorization: Bearer $FASTCLAW_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "Weekly Report Assistant",
    "description": "Summarizes the team every Friday",
    "instructions": "You write concise weekly reports.",
    "model": "anthropic/claude-sonnet-5-5",
    "metadata": { "app_user": "user-123" }
  }'

jsonCopy code
{ "agent": { "id": "agt_2834a7a1e660d509b83d", "display_name": "Weekly Report Assistant", "name": "agt_2834a7a1e660d509b83d", "description": "Summarizes the team every Friday", "model": "anthropic/claude-sonnet-5-5", "metadata": { "app_user": "user-123" }, "created_at": "2026-10-04T08:00:00Z", "updated_at": "2026-10-04T08:00:00Z" } }

• Only name is required. instructions becomes the agent's SOUL.md (persona). model is <provider>/<model>; omit it for the account default.
• metadata: your own string key/values — at most 16 keys, keys ≤ 64 characters, values ≤ 512. Stored and filterable, never used for authorization.
• Show display_name to people. name equals id (kept for old clients).

List — GET /v1/agents

Newest first. Query: limit (1–100; omit for all), cursor (the previous page's next_cursor), metadata[key]=value filters (ANDed; also metadata.key=value).

bashCopy code
curl -s "$FASTCLAW_BASE_URL/v1/agents?limit=20&metadata%5Bapp_user%5D=user-123" \
  -H "Authorization: Bearer $FASTCLAW_API_KEY"

Read — GET /v1/agents/{id}

Update — PATCH /v1/agents/{id}

Any of name, description, instructions, model, metadata; omitted fields are unchanged. model: "" clears the override. metadata merges; a key set to null or "" is removed.

Identity files — PUT /v1/agents/{id}/system-files/{name}

Body {"content": "..."}. name is one of SOUL.md, IDENTITY.md, AGENTS.md, BOOTSTRAP.md, TOOLS.md, HEARTBEAT.md, KNOWLEDGE.md (max 256 KB). Shared by every end-user of the agent.

Delete — DELETE /v1/agents/{id}

A second delete returns 404 agent_not_found; treat it as "already deleted". Also remove your own mapping.

Agent keys may also read and update (PATCH, identity files) the agents granted to them; only user keys create and delete.

5. Chat (both scenarios) — POST /v1/chat/completions

OpenAI-compatible, with FastClaw extensions.

bashCopy code
curl -sN "$FASTCLAW_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $FASTCLAW_API_KEY" -H "Content-Type: application/json" \
  -H "X-Fastclaw-Session-Key: myapp:conv_42" \
  -d '{
    "agent_id": "agt_2834a7a1e660d509b83d",
    "user": "user-123",
    "stream": true,
    "messages": [{ "role": "user", "content": "Summarize today'\''s discussion" }]
  }'

• agent_id (or header X-Fastclaw-Agent-ID; the body wins) picks the agent and is strict: an agent the key may not use is 404 agent_not_found — never a different agent. Omitted, FastClaw uses the key's only agent (or the account's only agent).
• X-Fastclaw-Session-Key selects the conversation history. Always send it, deterministic per conversation and prefixed with your app: myapp:<conversation>[:<topic>]. Omitted, every call starts a new session.
• user (or header X-Fastclaw-End-User; the body wins) is your user's stable id (not an email or display name). It keeps that user's session history and personal memory (USER.md / MEMORY.md) private to them. Omit it when all callers should share the agent's memory (e.g. a user's own agent, or a group chat).
• params: per-turn structured context shown to the agent, not persisted. In group chats send the current speaker as "params": {"speaker": {"id": "user-456", "name": "Bob"}}.
• Files: images (image URLs or data URLs, shown to vision models) and attachments ([{"url", "name"}], any file type) land in the agent's workspace for this turn. A message's content may also be an array of parts in the OpenAI or Anthropic shape — {"type": "text", "text"}, {"type": "image_url", "image_url": {"url"}}, {"type": "image", "source": {"type": "base64", "media_type", "data"}} — and its images are treated like images.
• project_id (optional) files the conversation under one of the agent's projects so it shares that project's workspace.
• Only the last user message is sent to the agent — FastClaw keeps the history itself, keyed by the session key. Don't resend old turns.

Streaming returns OpenAI SSE chunks (data: {"choices":[{"delta":{"content":"..."}}]} … data: [DONE]); non-streaming returns an OpenAI chat.completion (choices[0].message.content). The request's model field doesn't change the agent's model — the agent's configuration decides it.

usage (non-streaming: top level; streaming: on the final chunk) sums every model call the agent made for this turn, tool loops included: prompt_tokens / completion_tokens / total_tokens as in OpenAI (prompt_tokens includes cached input, also in prompt_tokens_details.cached_tokens), plus input_tokens (uncached), cache_read_tokens, cache_creation_tokens and model_calls. Use it to attribute cost to your users per turn.

API conversations are never trusted with the FastClaw host: the agent's tools (shell, scripts) run in FastClaw's sandbox. If the FastClaw operator hasn't configured one, the agent can still answer but can't run commands.

Files the agent produces

Files the agent creates or changes during a turn — e.g. an edited image — come back with the reply in files (non-streaming: top level; streaming: on the final chunk, the one with finish_reason). Files the reply links as /workspace/<path> come first; your own uploads are not echoed back.

jsonCopy code
{
  "choices": [{ "message": { "role": "assistant", "content": "Done: ![edited](/workspace/edited.png)" } }],
  "files": [
    {
      "name": "edited.png",
      "path": "edited.png",
      "size": 77490,
      "content_type": "image/png",
      "url": "https://claw.example.com/v1/agents/agt_…/sessions/myapp%3Aconv_42/files/edited.png"
    }
  ]
}

• Download url with the same Authorization header — and the same X-Fastclaw-End-User when the conversation had one: end-users can only read their own conversations' files. It is GET /v1/agents/{agent_id}/sessions/{session_key}/files/{path} (?project_id= for project conversations).
• Send "return_files": "inline" to also get each file's bytes as a data_url (files up to 10 MB, 25 MB per reply) — simplest for one image.
• Don't rely on the agent to put files anywhere else: FastClaw instructs it not to upload your users' files to third-party services.

6. Usage and quotas

• GET /v1/usage — per-day token usage. Query: days (1–90, default 30), agent_id, end_user (your user id), scope=app (the whole account, all end-users). Each daily row has agentId and endUser; roll up by them to bill your users.
• PUT|GET|DELETE /v1/quota — monthly token / request limits for an end-user (user_id from POST /v1/users with {"external_id": "<your user id>"}).

7. Errors

Every /v1 error is {"error": {"type", "code", "message"}}. Branch on code:

8. Checklist

• FASTCLAW_BASE_URL and FASTCLAW_API_KEY read from server-side configuration, documented in the env template, verified with GET /v1/agents.
• Right key type for the scenario (agent key for fixed agents, user key on a dedicated account for managed agents).
• The app checks the user's access to an agent before every call.
• Deterministic X-Fastclaw-Session-Key per conversation; user set when a user's history must stay private.
• Streaming parsed as SSE; errors handled by error.code.
• Produced files taken from files (download url or return_files: "inline").
• No FastClaw key or URL in client-side code.