# thesyart/claude-agent-examples architecture

> Architecture diagram of the GitHub repository thesyart/claude-agent-examples, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thesyart/claude-agent-examples
- Repository: https://github.com/thesyart/claude-agent-examples

## Overview

#### 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/`.

Main entry points: [`build-agent-example/code/step11_mcp.py`](https://github.com/thesyart/claude-agent-examples/blob/main/build-agent-example/code/step11_mcp.py) (MCP client stage), [`build-agent-example/code/step06_skills.py`](https://github.com/thesyart/claude-agent-examples/blob/main/build-agent-example/code/step06_skills.py) (Skills-enabled agent), [`build-agent-example/code/step07_memory_system.py`](https://github.com/thesyart/claude-agent-examples/blob/main/build-agent-example/code/step07_memory_system.py) (Persistent memory), [`build-agent-example/code/step12_hooks.py`](https://github.com/thesyart/claude-agent-examples/blob/main/build-agent-example/code/step12_hooks.py) (Hooked agent runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Teaching Runtime"]
  node_step01["Single model call<br/>Python lesson"]
  node_step03["Conversation history<br/>Python lesson<br/>[step03_history.py]"]
  node_step05["Tool-use loop<br/>Python lesson<br/>[step05_tool_use.py]"]
  node_step12["Hooked agent runtime<br/>Python lesson<br/>[step12_hooks.py]"]
  node_local_cli(("Local terminal user<br/>runtime boundary"))
end

subgraph group_capabilities["Capabilities"]
  node_system_skills["Skills-enabled agent<br/>Python lesson<br/>[step06_skills.py]"]
  node_skills["Skill packages<br/>Markdown knowledge<br/>[SKILL.md]"]
  node_github_skill["GitHub skill<br/>Markdown knowledge<br/>[SKILL.md]"]
  node_planning["Todo planning<br/>Python lesson"]
  node_subagents["Concurrent subagents<br/>Python lesson<br/>[step09_subagent.py]"]
  node_team["Persistent agent team<br/>Python lesson"]
  node_roles["Subagent roles<br/>prompt assets<br/>[general.md]"]
  node_mcp_appendix["MCP / skill / tool guide<br/>appendix example"]
end

subgraph group_state["State &amp; Context"]
  node_memory_runtime["Persistent memory<br/>Python lesson"]
  node_user_profile["User profile template<br/>memory template<br/>[USER.md]"]
  node_compaction_prompt["Compaction prompt<br/>prompt template<br/>[compact_prompt.md]"]
end

subgraph group_integration["External Integration"]
  node_anthropic{{"Anthropic model API<br/>external API"}}
  node_mcp_client["MCP client stage<br/>Python lesson<br/>[step11_mcp.py]"]
  node_mcp_config["MCP server config<br/>server definitions<br/>[mcp_servers.json]"]
  node_time_server{{"Reference time server<br/>MCP server<br/>[mcp_server_time.py]"}}
end

node_step01 -->|"adds history"| node_step03
node_step03 -->|"adds tool loop"| node_step05
node_step05 -->|"adds skill selection"| node_system_skills
node_system_skills -->|"adds persistence"| node_memory_runtime
node_memory_runtime -->|"adds planning"| node_planning
node_planning -->|"adds delegation"| node_subagents
node_subagents -->|"adds shared team state"| node_team
node_team -->|"adds MCP tools"| node_mcp_client
node_mcp_client -->|"assembled into final runtime"| node_step12
node_local_cli -->|"interactive input"| node_step12
node_step12 -->|"model requests"| node_anthropic
node_system_skills -->|"selects and loads"| node_skills
node_system_skills -->|"selects and loads"| node_github_skill
node_memory_runtime -->|"initializes from"| node_user_profile
node_memory_runtime -->|"uses for compaction"| node_compaction_prompt
node_subagents -->|"loads roles"| node_roles
node_team -.->|"uses personas"| node_roles
node_mcp_client -->|"reads definitions"| node_mcp_config
node_mcp_config -->|"launches via stdio"| node_time_server
node_mcp_appendix -.->|"documents capability boundary"| node_mcp_client
node_step12 -->|"uses external tools"| node_mcp_client

click node_step01 "https://github.com/thesyart/claude-agent-examples/blob/main/build-agent-example/code/step01_single_call.py"
click node_step03 "https://github.com/thesyart/claude-agent-examples/blob/main/build-agent-example/code/step03_history.py"
click node_step05 "https://github.com/thesyart/claude-agent-examples/blob/main/build-agent-example/code/step05_tool_use.py"
click node_step12 "https://github.com/thesyart/claude-agent-examples/blob/main/build-agent-example/code/step12_hooks.py"
click node_system_skills "https://github.com/thesyart/claude-agent-examples/blob/main/build-agent-example/code/step06_skills.py"
click node_skills "https://github.com/thesyart/claude-agent-examples/blob/main/skills/ddg-web-search-1.0.0/SKILL.md"
click node_github_skill "https://github.com/thesyart/claude-agent-examples/blob/main/skills/github/SKILL.md"
click node_memory_runtime "https://github.com/thesyart/claude-agent-examples/blob/main/build-agent-example/code/step07_memory_system.py"
click node_user_profile "https://github.com/thesyart/claude-agent-examples/blob/main/templates/USER.md"
click node_compaction_prompt "https://github.com/thesyart/claude-agent-examples/blob/main/templates/agent/compact_prompt.md"
click node_planning "https://github.com/thesyart/claude-agent-examples/blob/main/build-agent-example/code/step08_plan_todolist.py"
click node_subagents "https://github.com/thesyart/claude-agent-examples/blob/main/build-agent-example/code/step09_subagent.py"
click node_team "https://github.com/thesyart/claude-agent-examples/blob/main/build-agent-example/code/step10_agent_team.py"
click node_roles "https://github.com/thesyart/claude-agent-examples/blob/main/templates/subagents/general.md"
click node_mcp_client "https://github.com/thesyart/claude-agent-examples/blob/main/build-agent-example/code/step11_mcp.py"
click node_mcp_config "https://github.com/thesyart/claude-agent-examples/blob/main/mcp_servers.json"
click node_time_server "https://github.com/thesyart/claude-agent-examples/blob/main/build-agent-example/mcp_server_time.py"
click node_mcp_appendix "https://github.com/thesyart/claude-agent-examples/blob/main/build-agent-example/code/sp_mcp-skill-tool.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_step01,node_step03,node_step05,node_step12,node_local_cli toneBlue
class node_system_skills,node_skills,node_github_skill,node_planning,node_subagents,node_team,node_roles,node_mcp_appendix toneAmber
class node_memory_runtime,node_user_profile,node_compaction_prompt toneMint
class node_anthropic,node_mcp_client,node_mcp_config,node_time_server toneRose
```

## Components

### Teaching Runtime

Standalone cumulative Python agent examples.

- [Single model call](https://github.com/thesyart/claude-agent-examples/blob/main/build-agent-example/code/step01_single_call.py): Python lesson · Curriculum entry point. · `build-agent-example/code/step01_single_call.py`
- [Conversation history](https://github.com/thesyart/claude-agent-examples/blob/main/build-agent-example/code/step03_history.py): Python lesson · Replays prior messages to the model. · `build-agent-example/code/step03_history.py`
- [Tool-use loop](https://github.com/thesyart/claude-agent-examples/blob/main/build-agent-example/code/step05_tool_use.py): Python lesson · Repeats model and tool-result turns. · `build-agent-example/code/step05_tool_use.py`
- [Hooked agent runtime](https://github.com/thesyart/claude-agent-examples/blob/main/build-agent-example/code/step12_hooks.py): Python lesson · Complete teaching runtime with lifecycle hooks. · `build-agent-example/code/step12_hooks.py`
- **Local terminal user**: runtime boundary

### Capabilities

Prompt assets, skills, tools, and delegated work.

- [Skills-enabled agent](https://github.com/thesyart/claude-agent-examples/blob/main/build-agent-example/code/step06_skills.py): Python lesson · Loads knowledge packages only when selected. · `build-agent-example/code/step06_skills.py`
- [Skill packages](https://github.com/thesyart/claude-agent-examples/blob/main/skills/ddg-web-search-1.0.0/SKILL.md): Markdown knowledge · Procedures kept outside the default prompt. · `skills/ddg-web-search-1.0.0/SKILL.md`
- [GitHub skill](https://github.com/thesyart/claude-agent-examples/blob/main/skills/github/SKILL.md): Markdown knowledge · `skills/github/SKILL.md`
- [Todo planning](https://github.com/thesyart/claude-agent-examples/blob/main/build-agent-example/code/step08_plan_todolist.py): Python lesson · Exposes an update_todos planning interface. · `build-agent-example/code/step08_plan_todolist.py`
- [Concurrent subagents](https://github.com/thesyart/claude-agent-examples/blob/main/build-agent-example/code/step09_subagent.py): Python lesson · Dispatches isolated specialist agents. · `build-agent-example/code/step09_subagent.py`
- [Persistent agent team](https://github.com/thesyart/claude-agent-examples/blob/main/build-agent-example/code/step10_agent_team.py): Python lesson · Adds shared team state and inbox communication. · `build-agent-example/code/step10_agent_team.py`
- [Subagent roles](https://github.com/thesyart/claude-agent-examples/blob/main/templates/subagents/general.md): prompt assets · External persona and task specializations. · `templates/subagents/general.md`
- [MCP / skill / tool guide](https://github.com/thesyart/claude-agent-examples/blob/main/build-agent-example/code/sp_mcp-skill-tool.py): appendix example · Explains capabilities, procedures, and actions. · `build-agent-example/code/sp_mcp-skill-tool.py`

### State & Context

Persistent memory and context management.

- [Persistent memory](https://github.com/thesyart/claude-agent-examples/blob/main/build-agent-example/code/step07_memory_system.py): Python lesson · Creates and preserves conversation, notes, memory, and profile state. · `build-agent-example/code/step07_memory_system.py`
- [User profile template](https://github.com/thesyart/claude-agent-examples/blob/main/templates/USER.md): memory template · `templates/USER.md`
- [Compaction prompt](https://github.com/thesyart/claude-agent-examples/blob/main/templates/agent/compact_prompt.md): prompt template · Summarizes older context to control prompt size. · `templates/agent/compact_prompt.md`

### External Integration

Model and MCP service boundaries.

- **Anthropic model API**: external API
- [MCP client stage](https://github.com/thesyart/claude-agent-examples/blob/main/build-agent-example/code/step11_mcp.py): Python lesson · Loads external tool servers over stdio. · `build-agent-example/code/step11_mcp.py`
- [MCP server config](https://github.com/thesyart/claude-agent-examples/blob/main/mcp_servers.json): server definitions · `mcp_servers.json`
- [Reference time server](https://github.com/thesyart/claude-agent-examples/blob/main/build-agent-example/mcp_server_time.py): MCP server · Local capability provider. · `build-agent-example/mcp_server_time.py`

## Connections

- Single model call → Conversation history: adds history
- Conversation history → Tool-use loop: adds tool loop
- Tool-use loop → Skills-enabled agent: adds skill selection
- Skills-enabled agent → Persistent memory: adds persistence
- Persistent memory → Todo planning: adds planning
- Todo planning → Concurrent subagents: adds delegation
- Concurrent subagents → Persistent agent team: adds shared team state
- Persistent agent team → MCP client stage: adds MCP tools
- MCP client stage → Hooked agent runtime: assembled into final runtime
- Local terminal user → Hooked agent runtime: interactive input
- Hooked agent runtime → Anthropic model API: model requests
- Skills-enabled agent → Skill packages: selects and loads
- Skills-enabled agent → GitHub skill: selects and loads
- Persistent memory → User profile template: initializes from
- Persistent memory → Compaction prompt: uses for compaction
- Concurrent subagents → Subagent roles: loads roles
- Persistent agent team → Subagent roles: uses personas
- MCP client stage → MCP server config: reads definitions
- MCP server config → Reference time server: launches via stdio
- MCP / skill / tool guide → MCP client stage: documents capability boundary
- Hooked agent runtime → MCP client stage: uses external tools