cui.guru

anthropics/claude-quickstarts · 20.8k stars · Intermediate · 10 min · 2026-11-12

Build a tool-using agent loop with Claude Quickstarts

A compact Python reference agent (core logic under 300 lines) that shows how an LLM, a list of tools and a loop add up to an agent.

TL;DR

The agents/ quickstart in anthropics/claude-quickstarts is a minimal, educational agent: Claude calls tools in a loop until it stops asking for them. The README says the core logic is under 300 lines and that it is a reference implementation, not an SDK.

Why this repo matters

The repo is a collection of projects that help you start building applications with the Claude API (customer support, computer use, browser use, autonomous coding and more). The agents/ folder is the smallest of them: it strips an agent down to agent.py, a tools/ folder and a utils/ folder, so you can read the whole thing in one sitting and port the pattern to your own stack.

Best practices

  • Keep the loop simple: call the model, run any tool_use blocks, send the results back, and stop when a reply has no tool calls (agent.py).
  • Describe every tool with a name, a description and a JSON input_schema; subclass Tool and implement execute (tools/base.py).
  • Return tool failures as results flagged is_error instead of crashing the loop, so the model can recover (utils/tool_util.py).
  • Track tokens and truncate old messages once the context window limit is exceeded, and mark the latest message for prompt caching (utils/history_util.py).
  • Reach external tools through MCP servers (stdio or SSE) rather than hard-coding them; they are wrapped as ordinary tools (utils/connections.py).
  • Treat it as a starting point: the README says it deliberately lacks production features.

How-to

Where do I start?

1. Which Python and which packages do I need?

Python 3.10+, a Claude API key in ANTHROPIC_API_KEY, and the two libraries from the README:

git clone https://github.com/anthropics/claude-quickstarts
cd claude-quickstarts
pip install "anthropic>=2.0.0,<3" "mcp>=2.0"
export ANTHROPIC_API_KEY=...

Try it

Write a small Tool of your own (for example one that returns the current date), pass it to an Agent with verbose=True, and ask a question that needs it. Watch the printed tool call, tool result and final output.

Pitfalls

  • With no credential set, the first request fails with "Could not resolve authentication".
  • If an MCP server fails to start, the error is printed and the agent continues without its tools; check the "Loaded N MCP tools" line.
  • MCP results are text only: the MCPTool returns "No text content in tool response" otherwise.
  • This is a reference, not production code; the README says so explicitly.

Next steps

Read the agents README, then explore the sibling quickstarts such as autonomous-coding and browser-use-demo in the repo.