DIY Your AI Agent

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/](./miniagent/), and the extensible runtime lives in [full_agent/](./fullagent/).

• Usage guide: [miniagent/README.md](./miniagent/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: [fullagent/README.md](./fullagent/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.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: whitejoce
• Source: whitejoce/DIY-your-AI-agent
• License: MIT

Install and usage instructions live in the source repository linked above.