← All templates
PythonCoreFree sampleApplied AI EngineerForward Deployed EngineerApplied AI Architect

Tool-using Claude agent

An order-support agent with a bounded tool loop, pydantic tool schemas, an approval-gated idempotent refund, and cost accounting.

Download .zip

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

  1. Step budget. At most AGENT_MAX_STEPS model calls per question, then it stops with step_budget.
  2. Loop detection. The same tool with the same input more than AGENT_MAX_IDENTICAL_CALLS times gets a warning result; once more and the agent stops with loop_detected.
  3. Errors are data. Bad input, unknown tools, business-rule failures and handler crashes all come back as tool_result with is_error: true. Crashes are logged with a traceback; the model only sees a safe message.
  4. Writes are gated and idempotent. issue_refund checks policy before it writes, and a repeated call with the same order and amount returns the first refund.
  5. Every exit is typed. Callers branch on result.outcome, never on the answer text.

Extending it

  1. Add a tool: write an input model in schemas.py (subclass ToolInput), a handler in build_registry, and registry.register(Tool(...)). Write the description for the model: say when to use it and what it returns.
  2. Use a real backend: replace OrderStore with a client that has the same get and refund methods. Keep the idempotency key on the server side of that call.
  3. Change models: set AGENT_MODEL. Add its prices to PRICES in llm.py or cost shows as $0.
  4. Serve it over HTTP: call run_agent from a FastAPI route; build LLM and 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_required refunds (ticket, Slack, admin UI).
  • Logs shipped somewhere searchable; alert on loop_detected, step_budget and cost per question.
  • An eval set of real questions run on every prompt or model change.
  • Prices in llm.py checked against the pricing page.
  • Secrets from your secret manager, never from a committed file.

Run it

shell
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?"

Test it

shell
pytest -q

Offline: no API key or network needed.

Taught in