English | 简体中文
🚧 WIP: This project is under active development and being continuously improved.
Learn to build AI agents step by step — from a minimal "hello world" to a production-ready CLI agent.
A progressive 8-chapter tutorial for building AI agents from scratch with @mariozechner/pi-coding-agent. Each chapter is independently runnable and builds on the previous one, covering streaming, custom tools, session persistence, skills, and more.
This project includes a full documentation site built with Rspress, with bilingual support (English / Chinese).
# Start the docs dev server
bun run docs:dev
# Build for production
bun run docs:buildThe site contains three sections:
| Section | Description |
|---|---|
| Guide | 8-chapter progressive tutorial with code walkthroughs |
| API Reference | Model and ToolDefinition API reference |
| Reference | Official pi-coding-agent documentation (SDK, Session, Extensions, Skills, etc.) |
The Reference section is ported from the official pi-coding-agent docs, covering 22 topics including SDK usage, session format, compaction, RPC mode, extensions, skills, themes, and platform setup.
# Install dependencies
bun install
# Copy and edit your API keys
cp .env.example .env
# Run any chapter
bun run ch01| # | Chapter | Key Concepts |
|---|---|---|
| 01 | Hello Agent | createAgentSession, session.prompt(), minimal pipeline |
| 02 | Streaming | subscribe() events, text_delta, typewriter output |
| 03 | Custom Tools | ToolDefinition, TypeBox schemas, tool execution events |
| 04 | Session Persistence | SessionManager, JSONL sessions, conversation resumption |
| 05 | Confirmation Pattern | Blocking tool execution, user confirmation flow |
| 06 | System Prompt & Skills | DefaultResourceLoader, loadSkillsFromDir, prompt engineering |
| 07 | Multi-Session | Session listing, switching, creating, SessionManager.list() |
| 08 | Full CLI Agent | All patterns combined into a production-quality CLI agent |
- Bun runtime
- An API key for Anthropic, OpenAI, or Google
Set your provider and API key in .env:
AI_PROVIDER=anthropic # or: openai, google, deepseek
AI_MODEL=claude-sonnet-4-6 # or: gpt-5.2, gemini-2.5-flash
ANTHROPIC_API_KEY=sk-ant-xxx # your API keypi-mono-master/
├── docs/ # Rspress documentation site
│ ├── en/ # English docs
│ │ ├── guide/ # Tutorial chapters
│ │ ├── api/ # API reference
│ │ └── reference/ # Official pi-coding-agent docs
│ ├── zh/ # Chinese docs (same structure)
│ └── public/ # Static assets (logo, etc.)
├── shared/model.ts # Shared model creation from env vars
├── chapters/
│ ├── 01-hello-agent/ # Minimal agent
│ ├── 02-streaming/ # Real-time output
│ ├── 03-custom-tools/ # Tool definitions
│ ├── 04-session-persistence/ # JSONL sessions
│ ├── 05-confirmation-pattern/ # User approval flow
│ ├── 06-system-prompt-and-skills/ # Prompts + skills
│ ├── 07-multi-session/ # Session management
│ └── 08-full-cli-agent/ # Everything combined
├── theme/ # Custom Rspress theme
├── styles/ # Custom CSS
└── .env # Your API keys (git-ignored)
| Package | Purpose |
|---|---|
@mariozechner/pi-coding-agent |
Agent framework (sessions, tools, resources) |
@mariozechner/pi-ai |
Model abstraction (Anthropic, OpenAI, Google) |
@sinclair/typebox |
TypeBox schemas for tool parameters |
dotenv |
Environment variable loading |
tsx |
TypeScript execution |
@rspress/core |
Documentation site framework |