LLM agent integration - Bron Developer

bron is built to be driven by an LLM agent (Claude Code, Codex, Cursor, custom tooling) without any wrapping layer. This page captures the contract: what an agent can rely on, what surfaces it should query first, and how to keep it from doing damage.

Discovery in one call

The agent doesn’t need to memorise the API. --schema emits the complete CLI surface as one OpenAPI 3.1 JSON document:

bron --schema                          # full CLI: every command, every flag, every type
bron <resource> <verb> --schema        # single-command fragment
bron --output yaml <r> <v> --schema    # same dump in YAML

What’s in there:

Every command path (accounts list, tx withdrawal, tx subscribe, …)
Every flag, with its type, enum values, defaults, and short description
Every request body shape, by transactionType discriminator for tx create
Every response shape, indexed by HTTP status code
The --embed tokens each list endpoint accepts, with the resulting _embedded shape

For an agent that just spawned, bron --schema | head -200 is enough orientation to start composing valid commands. Agents driving the MCP server instead have an even cheaper entry point: a single bron_help call returns the data model, any tool’s response shape, and worked jq recipes on demand.

The recommended agent flow

1. user: "approve every signing-required withdrawal under $1k"
   ↓
2. agent: bron tx --help               # → see verbs (list, get, approve, ...)
   agent: bron tx list --help          # → see filters
   ↓
3. agent: bron tx list \
            --transactionStatuses signing-required \
            --transactionTypes withdrawal \
            --output jsonl
   → JSONL: agent parses, picks the ones with params.amount < 1000
   ↓
4. agent: bron tx approve <tx>         # for each match
   → exit 0 = success, exit ≠ 0 = stop and report to user

Three loops covers most workflows: discover → query → act. --schema for static introspection, --help for human prose where helpful, --output jsonl for machine consumption.

Stable contracts

These won’t break across 0.x releases:

Surface	Contract
Exit codes	`0` success; `1` other; `3` 401/403; `4` 404; `5` 400; `6` 409; `7` 429; `8` 5xx
Error envelope on stderr	`error: <message>` line + `status:` / `code:` / `id:` lines
`--schema` document shape	Strict OpenAPI 3.1 fragment; field paths + types
Flag/verb names	`tx`, `tx list`, `tx withdrawal`, `--output`, `--columns`, etc.
Date rendering	ISO 8601 UTC in every output format
Numeric strings	Decimals stay strings (no `float64` coercion)

--help text wording, color, and table layout are NOT part of the stable surface. Don’t grep --help output in agent code; use --schema.

Idempotency

Every tx <type> and tx create call accepts --externalId <key>. Bron de-duplicates by (workspace, externalId): retrying a call with the same key returns the existing transaction, not a duplicate. For an agent, this is critical — LLMs retry on perceived failure, and without an idempotency key a retry would create a second withdrawal:

# DON'T — agent retries this on a hiccup → double-spend
bron tx withdrawal --accountId acc --params.amount=100 ...

# DO — agent retries this on a hiccup → same tx, no double-spend
bron tx withdrawal --externalId "agent-task-7f3a" --accountId acc --params.amount=100 ...

Generate --externalId from a stable identifier of the agent’s task (task ID, request ID, hash of the prompt + timestamp) — anything that would be the same on retry.

Dry-runs before real submits

bron tx dry-run validates a transaction body against the API without submitting it: returns the expected fees, blockchain ETA, validation errors:

bron tx dry-run --transactionType withdrawal --file /tmp/tx.json --output json

For an agent acting on behalf of a human, a dry-run + summary + explicit confirmation step is the standard pattern. Same body schema as the live call, so the agent can reuse the same JSON.

Output for agents

The default JSON is fine. JSONL is often easier to parse line-by-line in a streaming agent:

bron tx list --output jsonl

For really long lists, project just the fields the agent needs:

bron tx list \
  --transactionStatuses signing-required \
  --output jsonl \
  --columns transactionId,transactionType,params.amount,params.assetId,createdAt

Less to parse, less context spent.

Intent vs settlement. params.amount is what a transaction requested (the intent / quote); _embedded.events[].amount is what actually moved on-chain (the settlement). For any financial total — volume, net flow, P&L — aggregate _embedded.events[], never params.amount. Summing params.amount looks right but is wrong for swaps, bridges, intents, fiat and fee-bearing transfers. Events are omitted by default — add --includeEvents (CLI) or includeEvents: true (MCP) to fetch them. params.amount is still correct when you genuinely want the requested amount, e.g. filtering withdrawals under a threshold.

Agent-friendly help topic

bron help agents

Prints a concise, machine-readable orientation guide: the commands you’ll need most, the schema entry point, the idempotency contract, the exit-code map. Reference it from agent system prompts so a fresh agent can self-orient in one call.

Dedicated skills repo

For Claude Code, packaged skills live in bronlabs/bron-skills — SKILL.md files with allowed-tools declarations, references, and worked examples for the most common flows (bron-tx-send, bron-tx-subscribe, bron-balances-read, bron-address-book). Install for Claude Code in one shot:

git clone https://github.com/bronlabs/bron-skills ~/src/bron-skills
~/src/bron-skills/install/install-claude.sh

Cross-agent project memory (AGENTS.md standard) ships in the same repo for Codex, Cursor, Aider, GitHub Copilot, Junie. Drop the file into any project that uses bron and the agent picks it up automatically.

Safety guardrails to write into your agent prompt

Suggested constraints for a Bron-driving agent — copy into your system prompt and tune:

Always pass --externalId on any tx <type> or tx create call. Generate it from a stable task identifier.
Never pipe credentials anywhere except the local profile config. Don’t log JWK contents.
Confirm before approve / decline / cancel / sign — these are state-changing, often irreversible. Show the human the affected transactions and wait for explicit OK.
Use tx dry-run before any first-time withdrawal pattern, to surface fees and validation errors.
Bound query windows — --createdAtFrom / --createdAtTo on list queries to avoid pulling thousands of records into context.
Treat exit codes as truth — bron tx approve $tx || stop_and_report instead of grepping success messages.

​Discovery in one call

​The recommended agent flow

​Stable contracts

​Idempotency

​Dry-runs before real submits

​Output for agents

​Agent-friendly help topic

​Dedicated skills repo

​Safety guardrails to write into your agent prompt