Tool-using Claude agent
An order-support agent that answers questions about orders and can issue refunds. It is small on purpose (about 450 lines), but it has the parts a production agent needs: a bounded loop, typed tools, errors the model can recover from, an approval gate on the write, idempotency, cost accounting and structured logs. Copy it, swap the example tools for yours, keep the rest.
File map
| File | What it does |
|---|---|
app/main.py |
CLI entry point. Builds the real dependencies, sets up JSON logging, prints the answer and the cost. |
app/agent.py |
The loop. Calls Claude, runs requested tools, stops on end_turn, max_tokens, refusal, the step budget or a detected loop. |
app/tools.py |
Tool registry (pydantic model → JSON schema), the order store, lookup_order and issue_refund. |
app/schemas.py |
Pydantic models: tool inputs, orders, refunds, the result and usage totals. |
app/prompts.py |
The system prompt, kept stable so prompt caching works. |
app/llm.py |
Client wrapper: request defaults, per-call logging, token and dollar accounting. |
app/config.py |
pydantic-settings: every knob, read from env or .env. |
tests/ |
Offline tests. fakes.py scripts Claude's replies; test_sdk_contract.py runs the real SDK over a mocked transport. |
Setup and run
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env # add ANTHROPIC_API_KEY
python -m app.main "Where is order 1042?"
python -m app.main "Order 1043 arrived damaged, please refund it" --approve-refunds
python -m app.main "Refund order 1044" --json
Without --approve-refunds (or AGENT_ALLOW_REFUNDS=true), refunds come back as
approval_required and nothing is written. Refunds over AGENT_REFUND_LIMIT_USD are always held.
Test
pytest -q
No API key or network needed.
How the loop stays safe
- Step budget. At most
AGENT_MAX_STEPSmodel calls per question, then it stops withstep_budget. - Loop detection. The same tool with the same input more than
AGENT_MAX_IDENTICAL_CALLStimes gets a warning result; once more and the agent stops withloop_detected. - Errors are data. Bad input, unknown tools, business-rule failures and handler crashes all come back as
tool_resultwithis_error: true. Crashes are logged with a traceback; the model only sees a safe message. - Writes are gated and idempotent.
issue_refundchecks policy before it writes, and a repeated call with the same order and amount returns the first refund. - Every exit is typed. Callers branch on
result.outcome, never on the answer text.
Extending it
- Add a tool: write an input model in
schemas.py(subclassToolInput), a handler inbuild_registry, andregistry.register(Tool(...)). Write the description for the model: say when to use it and what it returns. - Use a real backend: replace
OrderStorewith a client that has the samegetandrefundmethods. Keep the idempotency key on the server side of that call. - Change models: set
AGENT_MODEL. Add its prices toPRICESinllm.pyor cost shows as $0. - Serve it over HTTP: call
run_agentfrom a FastAPI route; buildLLMand the registry per request (or per tenant).
Production checklist
- Real order and refund APIs behind
OrderStore, with their own timeouts and auth. - Idempotency enforced by the payments system, not only in this process.
- Approval queue for
approval_requiredrefunds (ticket, Slack, admin UI). - Logs shipped somewhere searchable; alert on
loop_detected,step_budgetand cost per question. - An eval set of real questions run on every prompt or model change.
- Prices in
llm.pychecked against the pricing page. - Secrets from your secret manager, never from a committed file.