# jiayuxu0/zipagent architecture

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

- Interactive diagram: https://gitdiagram.com/jiayuxu0/zipagent
- Repository: https://github.com/jiayuxu0/zipagent

## Overview

##### Project Type and Purpose
- ZipAgent is an open-source, Python-based AI Agent framework (library/tool) for building conversational assistants.
- It provides core engine components—Agent, Context, Model abstraction, Runner, Tool system, Stream processing, and MCP integration—behind a simple API to construct AI assistants.

##### High-Level Architecture Overview
- The framework is organized into a modular, layered architecture:
a. Core Agent Layer (agent.py)
b. Context & State Layer (context.py)
c. Model Abstraction Layer (model.py)
d. Execution/Orchestration Layer (runner.py)
e. Tool System Layer (tool.py, mcp_tool.py)
f. Streaming Layer (stream.py)
g. Error & Exception Layer (exceptions.py)

##### Main Components and Responsibilities
- Agent
- Holds agent configuration (name, instructions, tools, model)
- Coordinates tool invocation and message generation
- Context
- Manages conversation history, turn counts, token usage
- Model
- Defines LLM interface (e.g., OpenAIModel)
- Sends prompts, receives responses
- Runner
- Orchestrates a single request or streaming session
- Calls Model, updates Context, triggers Tool calls
- Tool System
- @function_tool decorator for local tools
- MCPTool for external tool integration (spawn subprocess, JSON protocol)
- Stream
- Emits incremental events (ANSWER_DELTA, TOOL_CALL) for real-time UI
- Exceptions
- ToolExecutionError, MaxTurnsError, etc., for robust error handling

##### Component Interactions and Data Flow
- User → Runner.run or Runner.run_stream
- Runner:
- Fetches Context state
- Builds prompt from Agent.instructions + Context.history + user input
- Calls Model.send (or stream)
- Parses response → either plain text or Tool call request
- If tool call: Runner dispatches to Tool System → executes and returns result
- Appends tool result to Context → reiterates until termination or max turns
- Stream mode: each partial Model/Tool output is emitted as StreamEvent
- Context persists state between turns

##### Architectural Patterns & Design Principles
- Layered modular design: each concern (model, context, tools) isolated
- Strategy pattern for pluggable Model implementations
- Plugin/Decorator pattern for registering local tools
- Pipeline/Orchestration in Runner managing iterative cycles
- Observer pattern via StreamEvent for real-time updates
- Separation of concerns: Agent definition vs execution vs I/O

##### Final Advice
- Iterative loops for multi-turn conversations.
- Extension mechanisms (decorator hooks, MCP protocols).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Application Layer
    User["End User / Application"]:::external
    BasicDemo["examples/basic_demo.py"]:::external
    MCPDemo["examples/mcp_demo.py"]:::external
    StreamDemo["examples/stream_demo.py"]:::external
    QuickStream["examples/quick_streaming_test.py"]:::external
    ToolStreamDemo["examples/streaming_tool_calling_demo.py"]:::external

    User -->|invokes Runner.run/run_stream| Runner
    BasicDemo -->|uses Library| Runner
    MCPDemo -->|uses Library| Runner
    StreamDemo -->|uses Library| Runner
    QuickStream -->|uses Library| Runner
    ToolStreamDemo -->|uses Library| Runner

    %% Library Layer
    subgraph "Library (src/zipagent)"
        direction TB
        Runner["Runner"]:::internal
        Agent["Agent"]:::internal
        Context["Context"]:::internal
        Model["Model"]:::internal
        LocalTool["@function_tool (Local Tools)"]:::extension
        MCPTool["MCPTool (External Tools)"]:::extension
        StreamComp["Stream (StreamEvent)"]:::internal
        Exceptions["Exceptions"]:::internal
    end

    %% External Services
    LLMAPI["LLM API (OpenAI, etc.)"]:::external
    MCPService["MCP Subprocess/Service"]:::external

    %% Data Flows
    Runner -->|reads config| Agent
    Runner -->|reads/writes history| Context
    Runner -->|submits prompt| Model
    Model -->|HTTP/gRPC| LLMAPI
    LLMAPI -->|response| Model
    Model -->|returns text or tool call| Runner
    Runner -->|dispatches| LocalTool
    Runner -->|dispatches| MCPTool
    MCPTool -->|JSON RPC| MCPService
    MCPService -->|result| MCPTool
    Runner -->|emits events| StreamComp
    StreamComp -->|real-time updates| User

    Runner -->|raises| Exceptions

    %% Click Events
    click Runner "https://github.com/jiayuxu0/zipagent/blob/master/src/zipagent/runner.py"
    click Agent "https://github.com/jiayuxu0/zipagent/blob/master/src/zipagent/agent.py"
    click Context "https://github.com/jiayuxu0/zipagent/blob/master/src/zipagent/context.py"
    click Model "https://github.com/jiayuxu0/zipagent/blob/master/src/zipagent/model.py"
    click LocalTool "https://github.com/jiayuxu0/zipagent/blob/master/src/zipagent/tool.py"
    click MCPTool "https://github.com/jiayuxu0/zipagent/blob/master/src/zipagent/mcp_tool.py"
    click StreamComp "https://github.com/jiayuxu0/zipagent/blob/master/src/zipagent/stream.py"
    click Exceptions "https://github.com/jiayuxu0/zipagent/blob/master/src/zipagent/exceptions.py"
    click BasicDemo "https://github.com/jiayuxu0/zipagent/blob/master/examples/basic_demo.py"
    click MCPDemo "https://github.com/jiayuxu0/zipagent/blob/master/examples/mcp_demo.py"
    click StreamDemo "https://github.com/jiayuxu0/zipagent/blob/master/examples/stream_demo.py"
    click QuickStream "https://github.com/jiayuxu0/zipagent/blob/master/examples/quick_streaming_test.py"
    click ToolStreamDemo "https://github.com/jiayuxu0/zipagent/blob/master/examples/streaming_tool_calling_demo.py"

    %% Styles
    classDef internal fill:#D6EAF8,stroke:#1B4F72,color:#1B2631
    classDef extension fill:#D5F5E3,stroke:#196F3D,color:#145A32
    classDef external fill:#FDEDEC,stroke:#922B21,color:#641E16
```
