# hardness1020/learn-agent-architecture architecture

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

- Interactive diagram: https://gitdiagram.com/hardness1020/learn-agent-architecture
- Repository: https://github.com/hardness1020/learn-agent-architecture

## Overview

Learn Agent Architecture is a staged educational repository, not a single deployed agent. Its principal workflow is to study the sections in order and run a section demo to observe a harness loop: model calls, tool execution, and repeated observations. The README documents the broader progression through planning, memory, asynchronous work, coordination, interfaces, observability, engineering, and evaluation. Relationships for later capabilities are shown conservatively because their source implementations were not sampled.

Main entry points: [`sections/23-evaluation/src/loop.py`](https://github.com/hardness1020/learn-agent-architecture/blob/main/sections/23-evaluation/src/loop.py) (Agent loop), [`sections/23-evaluation/src/demo.py`](https://github.com/hardness1020/learn-agent-architecture/blob/main/sections/23-evaluation/src/demo.py) (Runnable demo), [`sections/23-evaluation/src/tools.py`](https://github.com/hardness1020/learn-agent-architecture/blob/main/sections/23-evaluation/src/tools.py) (Tool runtime), [`sections/23-evaluation/src/subagents.py`](https://github.com/hardness1020/learn-agent-architecture/blob/main/sections/23-evaluation/src/subagents.py) (Subagents)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core harness"]
  node_demo["Runnable demo<br/>[demo.py]"]
  node_loop["Agent loop<br/>[loop.py]"]
  node_tools["Tool runtime<br/>[tools.py]"]
  node_permissions["Permissions<br/>[permissions.py]"]
  node_hooks["Lifecycle hooks<br/>[hooks.py]"]
end

subgraph group_reasoning["Reasoning and context"]
  node_planning["Planning and todos<br/>[planning.py]"]
  node_subagents["Subagents<br/>[subagents.py]"]
  node_skills["On-demand skills<br/>[skills.py]"]
  node_context["Context management<br/>[context.py]"]
  node_memory["Persistent memory<br/>[memory.py]"]
end

subgraph group_operations["Long-running work"]
  node_tasks["Durable tasks<br/>[tasks.py]"]
  node_scheduler["Scheduling<br/>[scheduler.py]"]
  node_background["Background execution<br/>[background.py]"]
  node_worktree["Worktree isolation<br/>[worktree.py]"]
  node_mailbox["Agent coordination<br/>[mailbox.py]"]
end

subgraph group_extensions["Interfaces and resilience"]
  node_protocols["External protocols<br/>[protocols.py]"]
  node_mcp["MCP plugins<br/>[mcp.py]"]
  node_recovery["Error recovery<br/>[recovery.py]"]
  node_telemetry["Observability<br/>[telemetry.py]"]
end

subgraph group_engineering["Quality and learning"]
  node_graph["Graph engineering<br/>[graph.py]"]
  node_verify["Loop verification<br/>[verify.py]"]
  node_evaluation["Evaluation<br/>[evaluation.py]"]
end

node_learner(("Learner"))
node_model(("Language model"))

node_learner -->|"runs example"| node_demo
node_demo -->|"starts loop"| node_loop
node_loop -->|"requests response"| node_model
node_loop -->|"dispatches calls"| node_tools
node_loop -->|"gates actions"| node_permissions
node_loop -->|"emits lifecycle"| node_hooks
node_loop -->|"supports planning"| node_planning
node_loop -->|"delegates work"| node_subagents
node_loop -->|"loads capabilities"| node_skills
node_loop -->|"manages context"| node_context
node_loop -->|"uses memory"| node_memory
node_loop -->|"tracks tasks"| node_tasks
node_loop -->|"recovers failures"| node_recovery
node_loop -->|"records activity"| node_telemetry
node_scheduler -->|"schedules work"| node_background
node_mailbox -->|"coordinates agents"| node_subagents
node_worktree -->|"isolates execution"| node_background
node_protocols -.->|"connects clients"| node_loop
node_mcp -.->|"extends tools"| node_tools
node_graph -->|"structures control"| node_loop
node_verify -->|"checks behavior"| node_loop
node_evaluation -->|"evaluates runs"| node_loop

click node_demo "https://github.com/hardness1020/learn-agent-architecture/blob/main/sections/23-evaluation/src/demo.py"
click node_loop "https://github.com/hardness1020/learn-agent-architecture/blob/main/sections/23-evaluation/src/loop.py"
click node_tools "https://github.com/hardness1020/learn-agent-architecture/blob/main/sections/23-evaluation/src/tools.py"
click node_permissions "https://github.com/hardness1020/learn-agent-architecture/blob/main/sections/23-evaluation/src/permissions.py"
click node_hooks "https://github.com/hardness1020/learn-agent-architecture/blob/main/sections/23-evaluation/src/hooks.py"
click node_planning "https://github.com/hardness1020/learn-agent-architecture/blob/main/sections/23-evaluation/src/planning.py"
click node_subagents "https://github.com/hardness1020/learn-agent-architecture/blob/main/sections/23-evaluation/src/subagents.py"
click node_skills "https://github.com/hardness1020/learn-agent-architecture/blob/main/sections/23-evaluation/src/skills.py"
click node_context "https://github.com/hardness1020/learn-agent-architecture/blob/main/sections/23-evaluation/src/context.py"
click node_memory "https://github.com/hardness1020/learn-agent-architecture/blob/main/sections/23-evaluation/src/memory.py"
click node_tasks "https://github.com/hardness1020/learn-agent-architecture/blob/main/sections/23-evaluation/src/tasks.py"
click node_scheduler "https://github.com/hardness1020/learn-agent-architecture/blob/main/sections/23-evaluation/src/scheduler.py"
click node_background "https://github.com/hardness1020/learn-agent-architecture/blob/main/sections/23-evaluation/src/background.py"
click node_worktree "https://github.com/hardness1020/learn-agent-architecture/blob/main/sections/23-evaluation/src/worktree.py"
click node_mailbox "https://github.com/hardness1020/learn-agent-architecture/blob/main/sections/23-evaluation/src/mailbox.py"
click node_protocols "https://github.com/hardness1020/learn-agent-architecture/blob/main/sections/23-evaluation/src/protocols.py"
click node_mcp "https://github.com/hardness1020/learn-agent-architecture/blob/main/sections/23-evaluation/src/mcp.py"
click node_recovery "https://github.com/hardness1020/learn-agent-architecture/blob/main/sections/23-evaluation/src/recovery.py"
click node_telemetry "https://github.com/hardness1020/learn-agent-architecture/blob/main/sections/23-evaluation/src/telemetry.py"
click node_graph "https://github.com/hardness1020/learn-agent-architecture/blob/main/sections/23-evaluation/src/graph.py"
click node_verify "https://github.com/hardness1020/learn-agent-architecture/blob/main/sections/23-evaluation/src/verify.py"
click node_evaluation "https://github.com/hardness1020/learn-agent-architecture/blob/main/sections/23-evaluation/src/evaluation.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_demo,node_loop,node_tools,node_permissions,node_hooks toneBlue
class node_planning,node_subagents,node_skills,node_context,node_memory toneAmber
class node_tasks,node_scheduler,node_background,node_worktree,node_mailbox toneMint
class node_protocols,node_mcp,node_recovery,node_telemetry toneRose
class node_graph,node_verify,node_evaluation,node_learner,node_model toneIndigo
```

## Components

### Core harness

- [Runnable demo](https://github.com/hardness1020/learn-agent-architecture/blob/main/sections/23-evaluation/src/demo.py): `sections/23-evaluation/src/demo.py`
- [Agent loop](https://github.com/hardness1020/learn-agent-architecture/blob/main/sections/23-evaluation/src/loop.py): `sections/23-evaluation/src/loop.py`
- [Tool runtime](https://github.com/hardness1020/learn-agent-architecture/blob/main/sections/23-evaluation/src/tools.py): `sections/23-evaluation/src/tools.py`
- [Permissions](https://github.com/hardness1020/learn-agent-architecture/blob/main/sections/23-evaluation/src/permissions.py): `sections/23-evaluation/src/permissions.py`
- [Lifecycle hooks](https://github.com/hardness1020/learn-agent-architecture/blob/main/sections/23-evaluation/src/hooks.py): `sections/23-evaluation/src/hooks.py`

### Reasoning and context

- [Planning and todos](https://github.com/hardness1020/learn-agent-architecture/blob/main/sections/23-evaluation/src/planning.py): `sections/23-evaluation/src/planning.py`
- [Subagents](https://github.com/hardness1020/learn-agent-architecture/blob/main/sections/23-evaluation/src/subagents.py): `sections/23-evaluation/src/subagents.py`
- [On-demand skills](https://github.com/hardness1020/learn-agent-architecture/blob/main/sections/23-evaluation/src/skills.py): `sections/23-evaluation/src/skills.py`
- [Context management](https://github.com/hardness1020/learn-agent-architecture/blob/main/sections/23-evaluation/src/context.py): `sections/23-evaluation/src/context.py`
- [Persistent memory](https://github.com/hardness1020/learn-agent-architecture/blob/main/sections/23-evaluation/src/memory.py): `sections/23-evaluation/src/memory.py`

### Long-running work

- [Durable tasks](https://github.com/hardness1020/learn-agent-architecture/blob/main/sections/23-evaluation/src/tasks.py): `sections/23-evaluation/src/tasks.py`
- [Scheduling](https://github.com/hardness1020/learn-agent-architecture/blob/main/sections/23-evaluation/src/scheduler.py): `sections/23-evaluation/src/scheduler.py`
- [Background execution](https://github.com/hardness1020/learn-agent-architecture/blob/main/sections/23-evaluation/src/background.py): `sections/23-evaluation/src/background.py`
- [Worktree isolation](https://github.com/hardness1020/learn-agent-architecture/blob/main/sections/23-evaluation/src/worktree.py): `sections/23-evaluation/src/worktree.py`
- [Agent coordination](https://github.com/hardness1020/learn-agent-architecture/blob/main/sections/23-evaluation/src/mailbox.py): `sections/23-evaluation/src/mailbox.py`

### Interfaces and resilience

- [External protocols](https://github.com/hardness1020/learn-agent-architecture/blob/main/sections/23-evaluation/src/protocols.py): `sections/23-evaluation/src/protocols.py`
- [MCP plugins](https://github.com/hardness1020/learn-agent-architecture/blob/main/sections/23-evaluation/src/mcp.py): `sections/23-evaluation/src/mcp.py`
- [Error recovery](https://github.com/hardness1020/learn-agent-architecture/blob/main/sections/23-evaluation/src/recovery.py): `sections/23-evaluation/src/recovery.py`
- [Observability](https://github.com/hardness1020/learn-agent-architecture/blob/main/sections/23-evaluation/src/telemetry.py): `sections/23-evaluation/src/telemetry.py`

### Quality and learning

- [Graph engineering](https://github.com/hardness1020/learn-agent-architecture/blob/main/sections/23-evaluation/src/graph.py): `sections/23-evaluation/src/graph.py`
- [Loop verification](https://github.com/hardness1020/learn-agent-architecture/blob/main/sections/23-evaluation/src/verify.py): `sections/23-evaluation/src/verify.py`
- [Evaluation](https://github.com/hardness1020/learn-agent-architecture/blob/main/sections/23-evaluation/src/evaluation.py): `sections/23-evaluation/src/evaluation.py`

### Other components

- **Learner**
- **Language model**

## Connections

- Learner → Runnable demo: runs example
- Runnable demo → Agent loop: starts loop
- Agent loop → Language model: requests response
- Agent loop → Tool runtime: dispatches calls
- Agent loop → Permissions: gates actions
- Agent loop → Lifecycle hooks: emits lifecycle
- Agent loop → Planning and todos: supports planning
- Agent loop → Subagents: delegates work
- Agent loop → On-demand skills: loads capabilities
- Agent loop → Context management: manages context
- Agent loop → Persistent memory: uses memory
- Agent loop → Durable tasks: tracks tasks
- Agent loop → Error recovery: recovers failures
- Agent loop → Observability: records activity
- Scheduling → Background execution: schedules work
- Agent coordination → Subagents: coordinates agents
- Worktree isolation → Background execution: isolates execution
- External protocols → Agent loop: connects clients
- MCP plugins → Tool runtime: extends tools
- Graph engineering → Agent loop: structures control
- Loop verification → Agent loop: checks behavior
- Evaluation → Agent loop: evaluates runs