BotCircuits 代理

5. Install dependencies into the venv

uv sync

Configure your provider, model, and API key:

The wizard walks you through provider (`anthropic` / `openai` / `gemini`), model, and API key with arrow-key navigation (↑/↓ to move, Enter to select, Esc to keep the current value). Each pick is saved as you go:

- `provider` and `model` → `~/.botcircuits/settings.json`
- API key → `~/.botcircuits/.env` (`ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `GEMINI_API_KEY`, file mode `0600`)

Re-running `botcircuits setup` shows your existing values as defaults, and an existing API key gives you a **Keep / Replace / Clear** choice instead of re-prompting for the secret.

| Form | What it does |
|---|---|
| `botcircuits setup` | Full wizard (currently the LLM section) |
| `botcircuits setup llm` | Just the LLM provider/model/API-key section |
| `botcircuits setup --user` | Write to `~/.botcircuits/` (default) |
| `botcircuits setup --project` | Write to `./.botcircuits/settings.json` (shared via VCS) |
| `botcircuits setup --local` | Write to `./.botcircuits/settings.local.json` (gitignored personal override) |

Prefer to configure by hand? Copy the env template instead:

WhatsApp (all three required to enable)

WHATSAPP_PHONE_NUMBER_ID=123456789 WHATSAPP_ACCESS_TOKEN=EAA… WHATSAPP_VERIFY_TOKEN=any-shared-secret # echoed back during Meta's GET verify

Setup

Clone and install

```bash

1. Install uv (skip if you already have it)

curl -LsSf https://astral.sh/uv/install.sh | sh

or: brew install uv

Building a workflow

The raw file you author is not what the engine runs. The workflow build step takes the natural-language conditions on each agentAction and prepares conditions and variables the engine can evaluate deterministically:

• Conditions — each NL condition (e.g. "the requested tone is warm") is compiled into a typed choices[] entry with an operator (is, >=, contains, …) and a value, so the engine can pick the matching branch without re-calling the LLM at runtime.
• Variables — an aggregated flow.variables list is emitted, naming every slot referenced by the compiled conditions along with its inferred dataType and a short description. The runtime uses this list to coerce the LLM's free-text args into the right shape before evaluating branches.

/workflow add|edit runs the builder for you. If you hand-edit a workflow file, re-build it from the CLI:

botcircuits workflow build --name=greet_user

The agent runtime only loads workflows from .botcircuits/workflows/.build/, so a workflow that hasn't been built isn't callable — workflow build is what produces the runnable copy.

---

Platform setup notes

WhatsApp. In the Meta WhatsApp Business app, set the webhook URL to https://<your-host>/messaging/whatsapp and the verify token to whatever you put in WHATSAPP_VERIFY_TOKEN. Subscribe to the messages field on the WhatsApp Business Account.

Slack (Socket Mode). Create a Slack app, enable Socket Mode, and generate an app-level token with connections:write (→ SLACK_APP_TOKEN). Add bot scopes chat:write, channels:history, groups:history, app_mentions:read, im:history, im:write, users:read and install the workspace (→ SLACK_BOT_TOKEN). Subscribe to bot events message.im, message.channels, message.groups, app_mention. Missing message.channels / message.groups is the most common setup mistake — the bot will reply in DMs but appear dead in channels.

Generic webhook.

curl -X POST http://localhost:8000/messaging/webhook \
  -H "authorization: Bearer $WEBHOOK_TOKEN" \
  -H "content-type: application/json" \
  -d '{"chat_id": "user-42", "text": "What is the weather like?"}'

If WEBHOOK_OUTBOUND_URL is set, the gateway posts the agent's reply back to that URL with the same bearer token.

Deployment

##### Docker-Compose ( TODO ) ##### Kubernetes ( TODO )

Quick Start

3. Pick a Python (3.11+) and create the project venv

uv python install 3.11 uv venv --python 3.11 # creates ./.venv

4. Activate the venv

source .venv/bin/activate # bash / zsh

.env — API key for the provider you want to use (required)

ANTHROPIC_API_KEY=... OPENAI_API_KEY=... GEMINI_API_KEY=...

Optional — only used as a fallback when settings.json / CLI flags don't set them

LLM_PROVIDER=anthropic # anthropic | openai | gemini ANTHROPIC_MODEL=claude-opus-4-7 OPENAI_MODEL=gpt-4.1 GEMINI_MODEL=gemini-2.5-flash ```

Effective precedence (highest wins): CLI flag → settings.json (layered) → env var → built-in default.

List configured servers

botcircuits mcp list

Workflow

A workflow is a step-by-step conversation script the agent can run on your behalf. Each workflow is one JSON file that lives under .botcircuits/workflows/, and once the agent loads it the workflow becomes a tool the model can call by name.

Force-running a workflow

When you don't want to leave it up to the model to decide whether to invoke a workflow, kick one off directly:

/workflow run --name workflow_demo
/workflow run --name workflow_demo --initial-args '{"end_id":"step_3"}'

This calls the workflow tool right away with the args you supplied, seeds the conversation with the resulting first step, and hands control back to the model to perform it. --initial-args must be a JSON object; omit it to start with {}. The target workflow must already be registered — workflow tools are auto-discovered from .botcircuits/workflows/.build/ and the command refreshes that registry before looking up the name, so a freshly authored workflow works without a restart.

Where workflows live

By default, workflows live in .botcircuits/workflows/*.json under the current directory. Override with BOTCIRCUITS_WORKFLOWS_DIR=/abs/path (or set it in .env). A missing directory just means "no workflows" — drop a folder in to opt in.

Each file is one workflow record:

{
  "name": "greet_user",
  "description": "Greet the caller, then say goodbye.",
  "flow": {
    "start": "s0",
    "steps": {
      "s0": { "type": "start", "next": "a1" },
      "a1": {
        "type": "agentAction",
        "next": "a2",
        "conditions": [
          { "condition": "the requested tone is warm", "next": "a2" }
        ],
        "settings": {
          "action": "Capture the desired tone and greet the user accordingly."
        }
      },
      "a2": {
        "type": "agentAction",
        "settings": { "action": "Say goodbye." }
      }
    }
  }
}

name doubles as the tool name the model calls; it must match ^[a-zA-Z0-9_-]+$. Only start and agentAction step types are supported — to branch, attach a conditions list at the step root (sibling of type and next, not nested inside settings). conditions is control flow, so it sits next to the other control-flow fields rather than with the step-type-specific payload in settings.