# junlinghu/agent-code architecture

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

- Interactive diagram: https://gitdiagram.com/junlinghu/agent-code
- Repository: https://github.com/junlinghu/agent-code

## Overview

##### Project Type and Purpose
- This is an open-source collection of Python “agent” scripts that illustrate how to build LLM-based agents from scratch (no frameworks).
- Each script (agent_toolcall, agent_searchWeb, agent_computer, agent_kb) demonstrates a different tool-calling capability (generic tool, web search, local OS commands, knowledge-base lookup).
- A client.py file glues everything together by taking user input, selecting/running an agent, and returning the answer.

##### Key Components
a. Client Interface (client.py)
b. Core Agent Engine (abstract Agent class or logic shared by agent_*.py)
c. LLM Service (OpenAI API, with API token from environment)
d. Tool Adapters:
- ToolCaller (agent_toolcall.py)
- WebSearch (agent_searchWeb.py → external search API)
- LocalComputer (agent_computer.py → OS commands)
- KnowledgeBase (agent_kb.py → reads kb.json)
e. Knowledge Base Storage (kb.json)
f. External Services:
- OpenAI LLM endpoint
- Web search API endpoint
- Operating system shell

##### Relationships and Data Flows
1. User issues a query via client.py
2. client.py instantiates the chosen agent module
3. Agent formats prompt and calls the OpenAI API (reads API token from environment)
4. LLM returns a response that often includes an instruction to call a tool
5. Agent dispatches to the appropriate Tool Adapter
- WebSearch → issues HTTP request to search API → parses results
- LocalComputer → executes shell commands → captures stdout
- KnowledgeBase → loads & searches kb.json → returns matched content
- Generic ToolCaller → calls an abstract “tool” interface
6. Agent receives tool output, may re-prompt the LLM for final answer
7. client.py prints or returns the answer to the user

##### Architectural Patterns and Principles
- Modular design: each tool is encapsulated in its own script/module following a consistent interface
- Separation of concerns: client (I/O) ↔ agent logic (LLM orchestration) ↔ tool adapters ↔ data/external services
- Extensibility: new agent_*.py modules can be added by implementing the same call/response pattern

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client["Client Interface\n(client.py)"]:::internal
    AgentCore["Agent Core\n(shared logic)"]:::internal
    LLMService("OpenAI API"):::external

    subgraph "Tool Adapters"
        TC["ToolCaller\n(agent_toolcall.py)"]:::internal
        WS["WebSearch\n(agent_searchWeb.py)"]:::internal
        LC["LocalComputer\n(agent_computer.py)"]:::internal
        KB["KnowledgeBase\n(agent_kb.py)"]:::internal
    end

    KBjson[(kb.json)]:::datastore
    SearchAPI("External Search API"):::external
    OSShell("OS Shell"):::external
    abstract("Generic Tool Endpoint"):::external

    Client -->|"user input"| AgentCore
    AgentCore -->|"prompt"| LLMService
    LLMService -->|"response"| AgentCore

    AgentCore -->|"tool instruction"| TC
    AgentCore -->|"tool instruction"| WS
    AgentCore -->|"tool instruction"| LC
    AgentCore -->|"tool instruction"| KB

    TC -->|"tool call"| abstract
    abstract -->|"tool result"| TC

    WS -->|"HTTP request"| SearchAPI
    SearchAPI -->|"results"| WS

    LC -->|"exec shell"| OSShell
    OSShell -->|"stdout"| LC

    KB -->|"read/search"| KBjson
    KBjson -->|"content"| KB

    TC --> AgentCore
    WS --> AgentCore
    LC --> AgentCore
    KB --> AgentCore

    AgentCore -->|"final answer"| Client

    click Client "https://github.com/junlinghu/agent-code/blob/main/client.py"
    click TC "https://github.com/junlinghu/agent-code/blob/main/agent_toolcall.py"
    click WS "https://github.com/junlinghu/agent-code/blob/main/agent_searchWeb.py"
    click LC "https://github.com/junlinghu/agent-code/blob/main/agent_computer.py"
    click KB "https://github.com/junlinghu/agent-code/blob/main/agent_kb.py"
    click KBjson "https://github.com/junlinghu/agent-code/blob/main/kb.json"

    classDef internal fill:#D0E8FF,stroke:#1f77b4
    classDef external fill:#FFD580,stroke:#ff7f0e
    classDef datastore fill:#C1FFC1,stroke:#2ca02c
```
