> ## Documentation Index
> Fetch the complete documentation index at: https://docs.simplefunctions.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Build Agents

> Recommended patterns for agents using SimpleFunctions CLI and APIs — loop, safety classes, headless harness, MCP.

The SimpleFunctions CLI is designed to be driven by an LLM. The recommended loop, the tool classifications, and the JSON contract all assume an agent — not a human — is the primary caller.

## Recommended loop

<Steps>
  <Step title="Discover tools">
    `sf describe --all --json` returns every command with its safety class and JSON shape.
  </Step>

  <Step title="Pull world state">
    `sf world --json` for fresh global context, or `sf world --delta --json --since 1h` for a long-running agent.
  </Step>

  <Step title="Query or inspect">
    `sf query` for natural-language search, `sf inspect <ticker>` for a structured market dossier.
  </Step>

  <Step title="Pull account context">
    `sf me --json --detail` if authenticated.
  </Step>

  <Step title="Decide">
    Monitor, create an intent, place an order, or wait.
  </Step>
</Steps>

```bash theme={null}
sf describe --all --json
sf world --json
sf query "Fed rate cut" --json --limit 3
sf inspect KXRATECUT-26DEC31 --json
sf portfolio history --json --ticks 10 --trades 10 --since 2026-04-23
```

## Long-running agents

Use deltas instead of full snapshots so the context window stays small:

```bash theme={null}
sf world --delta --json --since 1h
```

Use bounded account reads:

```bash theme={null}
sf me --json --detail --limit 10
sf feed --json --hours 6
sf portfolio history --json --ticks 0 --trades 50 --status open
```

## Safety classes

Agents should treat commands as:

| Class            | Meaning                                                                             |
| ---------------- | ----------------------------------------------------------------------------------- |
| `safe_read`      | Public read-only. No auth required. Always safe to call.                            |
| `account_read`   | Authenticated read-only. Returns user-scoped data. Safe to call.                    |
| `server_write`   | Mutates SimpleFunctions server state (creates intents, theses, alerts). Reversible. |
| `local_runtime`  | Starts/stops a local process (e.g. `sf agent`). Side-effects on the local box only. |
| `exchange_write` | Can place or cancel orders on Kalshi or Polymarket. Real money.                     |

<Warning>
  Always check `sf describe --all --json` for the safety class before calling a command. `exchange_write` commands fail-closed without a TTY unless `SF_AUTO_CONFIRM=1` is set, but the gate is still your last line of defense — review the order before confirming.
</Warning>

## Headless mode

```bash theme={null}
sf agent --headless
```

Emits NDJSON tool calls on stdout and waits for tool responses on stdin. Useful when you want to drive `sf`'s tool surface from your own LLM harness — for example, embed it in a scheduled task, CI job, or another agent runtime.

See [Common workflows](/integrations/common-workflows) for a worked example.

## MCP

Same tools, different transport. See [MCP server](/cli/mcp-server) for the wire-up.

## Next steps

<CardGroup cols={2}>
  <Card title="JSON contract" href="/cli/json-contract">
    CLI envelope shape and exit codes.
  </Card>

  <Card title="Tool manifest" href="/cli/tool-manifest">
    Discover every command programmatically.
  </Card>

  <Card title="CLI command reference" href="/cli/command-reference">
    Comprehensive command surface.
  </Card>

  <Card title="Risk gates" href="/concepts/risk-gates">
    Pre-trade safety rails for exchange\_write commands.
  </Card>
</CardGroup>