DIY Your AI Agent

中文文档

This project is part of the whitejoce/AI-Agent-Toolkit stack, focusing on the Agent layer.
Full architecture: RAG (Enterprise Knowledge Base) → Agent → Tool Runtime (Hot-reloadable MCP Tools Platform)

---

🔥 Project Overview

Translated by GPT-5.5

A lightweight AI Agent runtime built from scratch for learning and understanding:

• How an LLM enters a tool-calling loop
• How to build from basic tool dispatch without using LangChain / LangGraph as the main runtime framework, then gradually expand into context, memory, approval, Skills, and MCP modules.

Mini Agent

The MVP example in this repository lives in mini_agent/, and the extensible runtime lives in full_agent/.

• Usage guide: mini_agent/README.md
• Entry point: mini_agent/agent.py
• Tool definitions: mini_agent/tools.py

Full Agent

A complete Agent runtime with multiple model providers, tool registration, approval policy, context management, long-term memory, and Skill loading.

• Full Agent guide: full_agent/README.md
• Entry point: full_agent/cli.py

Project Structure

.
├── requirements.txt        # Runtime Python dependencies
├── requirements-dev.txt    # Development and test dependencies
├── pytest.ini              # Pytest configuration
├── mini_agent/
│   ├── agent.py        # Agent loop: model calls, tool dispatch, terminal interaction
│   ├── tools.py        # Tool schemas and execution handlers
│   ├── README_*.md     # Documentation
│   └── .env.example    # Environment variable example
├── full_agent/
│   ├── runtime.py      # Extensible AgentRuntime main loop
│   ├── model.py        # Model provider adapters
│   ├── config.py       # Configuration loading
│   ├── memory.py       # JSONL long-term memory
│   ├── skills.py       # Directory-based instruction skill loading
│   ├── mcp.py          # MCP provider protocol and test double
│   ├── tools/          # ToolSpec / ToolRegistry / ToolExecutor
│   └── README_*.md     # Documentation
├── tests/              # Automated tests for mini_agent and full_agent
├── img/demo.png        # Demo screenshot
├── README_CN.md        # Chinese README
├── README.md           # English README
└── LICENSE

Roadmap

Keep Mini Agent as the learning and testing base. Full Agent already includes:

• ToolRegistry: manage built-in tools, third-party tools, and MCP tools in one place.
• ApprovalPolicy: ask for user confirmation before high-risk actions such as writing files or running commands.
• ContextManager: manage short-term context, conversation compression, and token budgets.
• Memory: store long-term memory, user preferences, and project-level context.

Next steps can add RAG adapters, a real MCP SDK provider, better logging and traces, and stronger context compression.

Testing

Install the development dependencies and run the test suite from the repository root:

pip install -r requirements-dev.txt
python -m pytest

The tests cover tool handlers, configuration, memory, Skills, the MCP provider interface, and Agent tool dispatch for both mini_agent and full_agent without calling the OpenAI API.

Safety Note

This repository is better suited for learning the basic structure and extension boundaries of an Agent runtime. For production use, combine it with mature community projects and a more complete safety policy.

---

💡 Further Reading

1. Talk to a Frontier Model

• LLM

  • OpenAI: model-spec.md
  • Anthropic: System Card and System Prompt
    • knowledge_cutoff

• LLM APIs

  • OpenAI: Responses API and Chat Completions API
  • Anthropic: Messages API

• MCP, Skills: progressive disclosure

  • Prompt engineering, Context Engineering vs Harness Engineering -> Loop Engineering
    • Why are prompts becoming less important?
      • Human-in-the-loop?

• Agentic AI

  • Function calling, Structured Outputs, Hooks
  • Observability and orchestration: logs, tool-call traces, error tracking, and performance monitoring

• Benchmarks and evaluation

  • Artificial Analysis and Deep SWE benchmark

• Multi-agent frameworks and SDKs

  • ADK: A2A protocol and agent.json
  • Design patterns behind frameworks such as LangGraph and LangChain

• LLM output quality

  • Correctness, Completeness, Size, Trjectory: No Vibes Allowed: Solving Hard Problems in Complex Codebases – Dex Horthy, HumanLayer

Looking for an Agent SDK? Check out DeepAgent, OpenAI Agents SDK.

2. Context Management Trade-offs

Recommended: Claude Code's animated context-window demo.

• Short-term memory: select and preserve the most relevant information in the current conversation
  • What is the dumb zone?
  • Context compression: summarize earlier turns to save tokens while preserving continuity
• Long-term memory: retain user preferences, conversation history, and project context for better continuity
  • AGENT.md and CLAUDE.md: global and project-level context files
  • Memory systems: persist command history, user preferences, and related project facts
• External knowledge bases: Retrieval-Augmented Generation (RAG)

3. Explore Harness Design

What is a harness, and why does it matter in agent design?

• OpenClaw, Hermes Agent, OpenHuman, Pi
• Coding agents: Cursor, Codex, Claude Code, OpenCode
  • Deep dive: understand how Pi works

---

📜 License

This project is released under the MIT License.

🤝 Contributions

Issues and PRs are welcome.