# jjyaoao/helloagents architecture

> Architecture diagram of the GitHub repository jjyaoao/helloagents, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jjyaoao/helloagents
- Repository: https://github.com/jjyaoao/helloagents

## Overview

1. **Repository purpose and shape**
   - This is a Python 3.10+ agent framework package, not just a demo app.
   - The core runtime lives in `hello_agents/`; everything else is support material: `docs/` for architecture guides, `examples/` for runnable integration samples, `tests/` for verification, and `skills/` for domain skill packs and assets.

2. **Top-level execution model**
   - The framework centers on an agent loop: user input goes into an `Agent`, the agent builds context, calls an LLM, interprets tool calls, executes tools, and feeds tool results back into the conversation.
   - The architectural boundary is between the **LLM-facing orchestration layer** and the **tool/external capability layer**.

3. **Core LLM abstraction and provider adapters**
   - `hello_agents/core/llm.py` and `llm_adapters.py` abstract model access behind a provider-neutral interface.
   - The repo explicitly supports **OpenAI-compatible**, **Anthropic**, and **Gemini** backends, selected from model/base URL configuration.
   - This is the main integration boundary to external AI services.

4. **Agent orchestration layer**
   - `hello_agents/core/agent.py` is the central agent base built around function-calling style interaction.
   - Concrete strategies in `hello_agents/agents/` implement different reasoning patterns:
     - `simple_agent.py`
     - `react_agent.py`
     - `reflection_agent.py`
     - `plan_solve_agent.py`
   - These agents share the same underlying runtime but differ in how they sequence reasoning, tool use, and reflection.

5. **Context engineering subsystem**
   - `hello_agents/context/` handles conversation state before it reaches the LLM.
   - `history.py`, `token_counter.py`, `truncator.py`, and `builder.py` together manage message history, token budgeting, truncation, and final prompt/context assembly.
   - This subsystem is the main boundary for controlling context size and preserving salient state.

6. **Tool system and tool-response protocol**
   - `hello_agents/tools/` is the external action layer.
   - `registry.py` manages discovery/registration, `base.py` defines tool contracts, and `response.py` standardizes output through the repo’s `ToolResponse` protocol.
   - Built-in tools include:
     - `file_tools.py` for file read/write/edit with optimistic locking
     - `task_tool.py` for subagent/task delegation
     - `todowrite_tool.py` for progress tracking
     - `devlog_tool.py` for decision logging
     - `skill_tool.py` for skill lookup/use
     - `calculator.py` as a simple utility tool

7. **Safety, routing, and subagent boundaries**
   - `circuit_breaker.py` adds failure protection around repeated tool/operation errors.
   - `tool_filter.py` controls which tools are exposed in subagent contexts, supporting the subagent mechanism and limiting capability scope.
   - This creates a clear boundary between the parent agent’s full capability set and the reduced tool surface of delegated agents.

8. **Session persistence and lifecycle**
   - `session_store.py` provides persistent conversation/session state across runs.
   - `lifecycle.py` supports async agent lifecycle handling, so agents can be initialized, executed, and cleaned up in event-loop-aware flows.
   - These modules separate transient inference from durable conversational state.

9. **Streaming and delivery**
   - `streaming.py` handles streaming responses, with the docs and examples showing SSE as the transport pattern.
   - The presence of `examples/fastapi_sse_server.py`, `sse_client.html`, and streaming guides indicates that the framework can expose incremental token/tool events to a UI or service endpoint.

10. **Observability and traceability**
   - `hello_agents/observability/trace_logger.py` records execution traces for agent runs.
   - This sits across the orchestration and tool layers, capturing reasoning steps, tool calls, and outcomes for debugging and inspection.

11. **Skills subsystem as externalized knowledge and capability packs**
   - `hello_agents/skills/loader.py` loads skills from the `skills/` directory.
   - The `skills/` tree contains many domain packages with their own markdown specs, scripts, and in some cases TypeScript or schema assets:
     - ASR, LLM, TTS, VLM
     - docx/pptx/xlsx/pdf utilities
     - web-search/web-reader/video/image/podcast/finance/frontend-design
   - Architecturally, skills are a content-and-script boundary: the framework discovers and invokes them, but their implementation lives outside the Python core.

12. **Examples, docs, and tests as validation layers**
   - `examples/` demonstrates integration points: async agents, subagents, streaming, session persistence, custom tools, tool responses, observability, and circuit breakers.
   - `tests/` covers the major subsystems directly: LLM function calling/streaming, context engineering, tool filtering, persistence, subagents, skills, observability, and protocol correctness.
   - `docs/` acts as the canonical explanation layer for each subsystem and is useful for diagramming the intended component boundaries.

13. **Typical data flow through the system**
   - Input arrives at an agent.
   - The agent uses context builders/history/token logic to prepare a bounded prompt.
   - The LLM adapter sends the request to an external model provider.
   - If the model returns tool calls, the registry resolves them, the tool layer executes them, and `ToolResponse` standardizes the result.
   - The updated context may be persisted, traced, streamed, and/or delegated to a subagent before the agent continues or finishes.

14. **What to show in an architecture diagram**
   - Center the diagram on the agent orchestration loop.
   - Surround it with four major subsystems: **LLM adapters**, **context engineering**, **tool execution**, and **state/observability**.
   - Treat `skills/` as an external capability repository feeding the tool/skill layer.
   - Treat `examples/`, `docs/`, and `tests/` as non-runtime support artifacts rather than part of the production execution path.

Main entry points: [`hello_agents/core/agent.py`](https://github.com/jjyaoao/helloagents/blob/main/hello_agents/core/agent.py) (Agent loop), [`hello_agents/tools/builtin/calculator.py`](https://github.com/jjyaoao/helloagents/blob/main/hello_agents/tools/builtin/calculator.py) (Tools), [`hello_agents/tools/registry.py`](https://github.com/jjyaoao/helloagents/blob/main/hello_agents/tools/registry.py) (Tool registry), [`hello_agents/core/llm.py`](https://github.com/jjyaoao/helloagents/blob/main/hello_agents/core/llm.py) (LLM API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_agent_core["Agent loop<br/>orchestration<br/>[agent.py]"]
  node_llm_core["LLM API<br/>model-bridge<br/>[llm.py]"]
  node_llm_adapters["Adapters<br/>[llm_adapters.py]"]
  node_agent_strategies["Agent types<br/>reasoning-strategies<br/>[factory.py]"]
  node_context_engineering["Context<br/>prompt-assembly<br/>[builder.py]"]
  node_session_store[("Session store<br/>persistent-state<br/>[session_store.py]")]
  node_lifecycle["Lifecycle<br/>async-runtime<br/>[lifecycle.py]"]
  node_streaming["Streaming<br/>[streaming.py]"]
  node_trace_logger["Trace log<br/>observability<br/>[trace_logger.py]"]
  node_tool_registry["Tool registry<br/>tool-routing<br/>[registry.py]"]
  node_tool_contract["Tool contract<br/>tool-protocol<br/>[base.py]"]
  node_tool_execution["Tools<br/>external-actions<br/>[calculator.py]"]
  node_tool_safety{{"Safety<br/>scope-control<br/>[circuit_breaker.py]"}}
  node_skills_loader["Skill loader<br/>skill-discovery<br/>[loader.py]"]
end

subgraph group_support["Support"]
  node_skills_repo["Skills packs<br/>external-capabilities<br/>[SKILL.md]"]
  node_docs["Docs<br/>architecture-guides"]
  node_examples["Examples<br/>integration-samples"]
  node_tests["Tests<br/>verification-suite"]
end

node_agent_core -->|"build prompt"| node_context_engineering
node_agent_core -->|"call model"| node_llm_core
node_llm_core -->|"dispatch"| node_llm_adapters
node_agent_core -->|"resolve tools"| node_tool_registry
node_tool_registry -->|"enforce contract"| node_tool_contract
node_tool_registry -->|"invoke"| node_tool_execution
node_tool_execution -->|"guard"| node_tool_safety
node_tool_execution -->|"use skills"| node_skills_loader
node_skills_loader -->|"discover packs"| node_skills_repo
node_agent_core -->|"persist state"| node_session_store
node_agent_core -->|"emit events"| node_streaming
node_agent_core -->|"trace run"| node_trace_logger
node_agent_core -->|"manage async"| node_lifecycle
node_agent_strategies -->|"specialize loop"| node_agent_core
node_agent_strategies -->|"subagent scope"| node_tool_safety
node_docs -.->|"document"| node_context_engineering
node_docs -.->|"document"| node_tool_contract
node_docs -.->|"document"| node_streaming
node_docs -.->|"document"| node_skills_loader
node_examples -.->|"demonstrate"| node_agent_core
node_examples -.->|"demonstrate"| node_streaming
node_examples -.->|"demonstrate"| node_tool_execution
node_examples -.->|"demonstrate"| node_tool_safety
node_examples -.->|"demonstrate"| node_session_store
node_tests -.->|"verify"| node_agent_core
node_tests -.->|"verify"| node_context_engineering
node_tests -.->|"verify"| node_tool_execution
node_tests -.->|"verify"| node_llm_core
node_tests -.->|"verify"| node_session_store
node_tests -.->|"verify"| node_trace_logger

click node_agent_core "https://github.com/jjyaoao/helloagents/blob/main/hello_agents/core/agent.py"
click node_llm_core "https://github.com/jjyaoao/helloagents/blob/main/hello_agents/core/llm.py"
click node_llm_adapters "https://github.com/jjyaoao/helloagents/blob/main/hello_agents/core/llm_adapters.py"
click node_agent_strategies "https://github.com/jjyaoao/helloagents/blob/main/hello_agents/agents/factory.py"
click node_context_engineering "https://github.com/jjyaoao/helloagents/blob/main/hello_agents/context/builder.py"
click node_session_store "https://github.com/jjyaoao/helloagents/blob/main/hello_agents/core/session_store.py"
click node_lifecycle "https://github.com/jjyaoao/helloagents/blob/main/hello_agents/core/lifecycle.py"
click node_streaming "https://github.com/jjyaoao/helloagents/blob/main/hello_agents/core/streaming.py"
click node_trace_logger "https://github.com/jjyaoao/helloagents/blob/main/hello_agents/observability/trace_logger.py"
click node_tool_registry "https://github.com/jjyaoao/helloagents/blob/main/hello_agents/tools/registry.py"
click node_tool_contract "https://github.com/jjyaoao/helloagents/blob/main/hello_agents/tools/base.py"
click node_tool_execution "https://github.com/jjyaoao/helloagents/blob/main/hello_agents/tools/builtin/calculator.py"
click node_tool_safety "https://github.com/jjyaoao/helloagents/blob/main/hello_agents/tools/circuit_breaker.py"
click node_skills_loader "https://github.com/jjyaoao/helloagents/blob/main/hello_agents/skills/loader.py"
click node_skills_repo "https://github.com/jjyaoao/helloagents/blob/main/skills/ASR/SKILL.md"

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_agent_core,node_llm_core,node_llm_adapters,node_agent_strategies,node_context_engineering,node_session_store,node_lifecycle,node_streaming,node_trace_logger,node_tool_registry,node_tool_contract,node_tool_execution,node_tool_safety,node_skills_loader toneBlue
class node_skills_repo,node_docs,node_examples,node_tests toneAmber
```

## Components

### Runtime

Production agent framework code under hello_agents/

- [Agent loop](https://github.com/jjyaoao/helloagents/blob/main/hello_agents/core/agent.py): orchestration · Central agent runtime that coordinates context, LLM calls, tools, streaming, persistence, and lifecycle. · `hello_agents/core/agent.py`
- [LLM API](https://github.com/jjyaoao/helloagents/blob/main/hello_agents/core/llm.py): model-bridge · Provider-neutral model interface used by agents to request completions and function calls. · `hello_agents/core/llm.py`
- [Adapters](https://github.com/jjyaoao/helloagents/blob/main/hello_agents/core/llm_adapters.py): provider-adapters · Backend adapters for OpenAI-compatible, Anthropic, and Gemini model providers. · `hello_agents/core/llm_adapters.py`
- [Agent types](https://github.com/jjyaoao/helloagents/blob/main/hello_agents/agents/factory.py): reasoning-strategies · Concrete agent patterns including simple, ReAct, reflection, and plan-and-solve variants. · `hello_agents/agents/factory.py`
- [Context](https://github.com/jjyaoao/helloagents/blob/main/hello_agents/context/builder.py): prompt-assembly · History, token budgeting, truncation, and final context assembly before model calls. · `hello_agents/context/builder.py`
- [Session store](https://github.com/jjyaoao/helloagents/blob/main/hello_agents/core/session_store.py): persistent-state · Durable conversation/session storage across runs. · `hello_agents/core/session_store.py`
- [Lifecycle](https://github.com/jjyaoao/helloagents/blob/main/hello_agents/core/lifecycle.py): async-runtime · Async initialization, execution, and cleanup hooks for event-loop-aware agent flows. · `hello_agents/core/lifecycle.py`
- [Streaming](https://github.com/jjyaoao/helloagents/blob/main/hello_agents/core/streaming.py): event-streaming · Incremental delivery of model and tool events to clients and UIs. · `hello_agents/core/streaming.py`
- [Trace log](https://github.com/jjyaoao/helloagents/blob/main/hello_agents/observability/trace_logger.py): observability · Execution tracing across reasoning, tool calls, and outcomes. · `hello_agents/observability/trace_logger.py`
- [Tool registry](https://github.com/jjyaoao/helloagents/blob/main/hello_agents/tools/registry.py): tool-routing · Discovery and registration of tools exposed to agents. · `hello_agents/tools/registry.py`
- [Tool contract](https://github.com/jjyaoao/helloagents/blob/main/hello_agents/tools/base.py): tool-protocol · Base tool interface and standardized tool response protocol. · `hello_agents/tools/base.py`
- [Tools](https://github.com/jjyaoao/helloagents/blob/main/hello_agents/tools/builtin/calculator.py): external-actions · Built-in action layer including files, tasks, todo tracking, logging, skills, and calculator. · `hello_agents/tools/builtin/calculator.py`
- [Safety](https://github.com/jjyaoao/helloagents/blob/main/hello_agents/tools/circuit_breaker.py): scope-control · Circuit breaking and tool filtering for failure protection and reduced subagent capability scope. · `hello_agents/tools/circuit_breaker.py`
- [Skill loader](https://github.com/jjyaoao/helloagents/blob/main/hello_agents/skills/loader.py): skill-discovery · Loads externalized skill packs from the skills/ directory into the framework. · `hello_agents/skills/loader.py`

### Support

Docs, examples, tests, and skill packs

- [Skills packs](https://github.com/jjyaoao/helloagents/blob/main/skills/ASR/SKILL.md): external-capabilities · Domain-specific skill packages with scripts, schemas, and markdown specs. · `skills/ASR/SKILL.md`
- **Docs**: architecture-guides · Canonical subsystem guides and protocol documentation.
- **Examples**: integration-samples · Runnable demos for agents, tools, streaming, subagents, observability, and persistence.
- **Tests**: verification-suite · Coverage for orchestration, context, tools, persistence, skills, and protocol behavior.

## Connections

- Agent loop → Context: build prompt · Prepares bounded conversational context before model requests.
- Agent loop → LLM API: call model · Sends the assembled prompt to the provider-neutral LLM interface.
- LLM API → Adapters: dispatch · Routes requests to the configured backend adapter.
- Agent loop → Tool registry: resolve tools · Finds callable tools referenced by model function calls.
- Tool registry → Tool contract: enforce contract · Uses the shared tool interface and response shape.
- Tool registry → Tools: invoke · Dispatches to built-in tools and registered capabilities.
- Tools → Safety: guard · Tool execution is constrained by circuit breaker and filtering boundaries.
- Tools → Skill loader: use skills · Skill-related tool behavior loads external skill packs.
- Skill loader → Skills packs: discover packs · Reads skill definitions and scripts from the skills repository.
- Agent loop → Session store: persist state · Stores and restores durable conversation/session state.
- Agent loop → Streaming: emit events · Streams incremental tokens, tool events, and status updates.
- Agent loop → Trace log: trace run · Records reasoning and tool execution for debugging and inspection.
- Agent loop → Lifecycle: manage async · Coordinates setup, execution, and cleanup in async flows.
- Agent types → Agent loop: specialize loop · Different agent patterns share the same runtime core.
- Agent types → Safety: subagent scope · Delegated agents receive a reduced tool surface.
- Docs → Context: document · Explains context budgeting, truncation, and assembly.
- Docs → Tool contract: document · Describes tool response protocol and tool boundaries.
- Docs → Streaming: document · Covers streaming and SSE delivery patterns.
- Docs → Skill loader: document · Explains skill loading and usage.
- Examples → Agent loop: demonstrate · Shows agent execution patterns and integrations.
- Examples → Streaming: demonstrate · Includes SSE server/client and streaming demos.
- Examples → Tools: demonstrate · Demonstrates custom tools and built-in tool usage.
- Examples → Safety: demonstrate · Includes circuit breaker and subagent examples.
- Examples → Session store: demonstrate · Shows session persistence flows.
- Tests → Agent loop: verify · Validates agent orchestration behaviors.
- Tests → Context: verify · Checks history, truncation, and summary behavior.
- Tests → Tools: verify · Covers built-in tools and tool protocol correctness.
- Tests → LLM API: verify · Exercises function calling and streaming integration.
- Tests → Session store: verify · Covers persistence behavior.
- Tests → Trace log: verify · Checks observability and trace integration.
