thesyart/claude-agent-examples

Purpose and Entry Points

This is a Python teaching repository that incrementally builds a Claude-based AI agent, not a production application. Each standalone script preserves prior behavior and adds one architectural capability. Start with build-agent-example/code/step01_single_call.py; the complete teaching runtime is build-agent-example/code/step12_hooks.py. Dependencies and Anthropic credentials/model configuration are supplied through requirements.txt and .env.example.

Cumulative Agent Runtime

The core control loop evolves from one model request into a conversational, tool-executing agent. Conversation state is introduced as replayed message history, then role constraints via a system prompt, then repeated model/tool-result turns:

• build-agent-example/code/step03_history.py

• build-agent-example/code/step05_tool_use.py

• build-agent-example/code/step12_hooks.py

The Anthropic model API is the primary external service. Scripts are intended for local Python execution and terminal interaction.

Prompt, Skills, and Tools Boundary

System prompts define agent behavior; tools are explicit callable capabilities exposed to the model; skills are Markdown knowledge/SOP packages loaded only when selected. This keeps skill content out of the default prompt and separates model decisions from local capability execution.

• build-agent-example/code/step06_skills.py

• skills/ddg-web-search-1.0.0/SKILL.md

• skills/github/SKILL.md

The appendix demonstrates the relationship: MCP receives/provides capabilities, skills supply procedure, and tools perform actions.

• build-agent-example/code/sp_mcp-skill-tool.py

Persistent Memory and Context Compaction

From step 7 onward, the agent persists raw conversation, situational notes, durable memory, and a user profile. Durable memory is injected into prompts; a compaction prompt summarizes older context to control prompt size. The runtime creates missing storage defaults rather than overwriting existing data.

• build-agent-example/code/step07_memory_system.py

• templates/USER.md

• templates/agent/compact_prompt.md

The README describes runtime-created memory/ files, although that directory is not present in the supplied tree.

Planning and Delegated Work

Task execution gains an update_todos planning interface, then isolated subagents with distinct identities and concurrent dispatch, followed by a persistent agent-team model with shared team state and inbox-style communication.

• build-agent-example/code/step08_plan_todolist.py

• build-agent-example/code/step09_subagent.py

• build-agent-example/code/step10_agent_team.py

Subagent role definitions are external prompt assets, creating a boundary between orchestration logic and persona/task specialization.

• templates/subagents/general.md

• templates/subagents/researcher.md

MCP Integration

MCP extends the local tool surface through external servers over stdio transport. Server launch/configuration is separated from agent orchestration: the client stage loads server definitions, while the included time server is a local reference provider.

• build-agent-example/code/step11_mcp.py

• mcp_servers.json

• build-agent-example/mcp_server_time.py

The default MCP configuration assumes the local virtual environment’s Python executable.

Lifecycle Governance and Supporting Material

The final runtime adds before/after hooks around agent operations for interception, modification, and auditing—an execution-policy boundary applied after all core capabilities are assembled.

• build-agent-example/code/step12_hooks.py

• build-agent-example/doc/step12_hooks.md

• tests/test_step12_hooks.py

Documentation, slides, and transcripts support the curriculum but are outside the executable runtime: build-agent-example/doc/, ppt/, and bilibili-transcripts/.