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, framework-free AI Agent example. Built without LangChain or LangGraph, it prioritizes readability and simplicity to help you understand core Agent architecture.

Mini Agent

The MVP example in this repository lives in mini_agent/.

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

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 the mini_agent tool handlers and Agent tool-dispatch behavior without calling the OpenAI API.

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
├── tests/              # Automated tests for mini_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. A more complete version can gradually add the following modules:

• 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.

Safety Note

This repository is better suited for learning the basic structure of Agents. For daily use, prefer mature community-maintained projects.

---

💡 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

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.