How jjyaoao/helloagents works
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: agent.py Agent loop · calculator.py Tools · registry.py Tool registry · llm.py LLM API
Components 18
Runtime
Production agent framework code under hello_agents/
- Agent loop · Central agent runtime that coordinates context, LLM calls, tools, streaming, persistence, and lifecycle.
hello_agents/core/agent.py - LLM API · Provider-neutral model interface used by agents to request completions and function calls.
hello_agents/core/llm.py - Adapters · Backend adapters for OpenAI-compatible, Anthropic, and Gemini model providers.
hello_agents/core/llm_adapters.py - Agent types · Concrete agent patterns including simple, ReAct, reflection, and plan-and-solve variants.
hello_agents/agents/factory.py - Context · History, token budgeting, truncation, and final context assembly before model calls.
hello_agents/context/builder.py - Session store · Durable conversation/session storage across runs.
hello_agents/core/session_store.py - Lifecycle · Async initialization, execution, and cleanup hooks for event-loop-aware agent flows.
hello_agents/core/lifecycle.py - Streaming · Incremental delivery of model and tool events to clients and UIs.
hello_agents/core/streaming.py - Trace log · Execution tracing across reasoning, tool calls, and outcomes.
hello_agents/observability/trace_logger.py - Tool registry · Discovery and registration of tools exposed to agents.
hello_agents/tools/registry.py - Tool contract · Base tool interface and standardized tool response protocol.
hello_agents/tools/base.py - Tools · Built-in action layer including files, tasks, todo tracking, logging, skills, and calculator.
hello_agents/tools/builtin/calculator.py - Safety · Circuit breaking and tool filtering for failure protection and reduced subagent capability scope.
hello_agents/tools/circuit_breaker.py - Skill loader · 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 · Domain-specific skill packages with scripts, schemas, and markdown specs.
skills/ASR/SKILL.md - Docs · Canonical subsystem guides and protocol documentation.
- Examples · Runnable demos for agents, tools, streaming, subagents, observability, and persistence.
- Tests · Coverage for orchestration, context, tools, persistence, skills, and protocol behavior.
Connections 30
- 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.