Donggua's AI Learning Notes: In-depth Pi-Agent SDK Tutorial
A systematic source-code breakdown of the production-grade Agent SDK Pi-Agent, with TypeScript and Python dual-language comparison, helping developers understand internal Agent architecture.
- Source repo
- buchidonggua/dg-ai-notes
- Stars
- ★ 3.4k
- Last updated
- 1mo ago
- License
- MIT
- Primary language
- MDX
- FA score
- 23/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platform
- Cost
- Free, no paid service needed
- Setup effort
- Low · running in minutes
- Typical use
- Developers planning to build an AI Agent from scratch using the pi-agent SDK can quickly grasp core concepts and source implementation through this tutorial.
- Not a fit if
- Hands-on learners: companion lab code L00-L31 is not public
- Python-only readers: source analysis is TypeScript-centric
- Teams needing closed-source reuse: docs are CC-BY-SA-4.0
- Source review
- 23/100 · Major gaps 8 safety controls not found
What does this agent do, and when should you use it?
This repository is a collection of learning notes for deeply analyzing the source code of Pi-Agent, an open-source Agent SDK by earendil-works. The tutorial consists of 10 chapters that systematically dissect Pi's core design, including three-layer architecture, Agent Loop, tool system, message system, event-driven model, context engineering and compression, and session management. Each chapter provides both TypeScript (matching Pi's original language) and Python versions. The content is stored as Markdown docs under pi-agent/docs, with a web version (three-column layout, figure linking, theme switching) and a PDF version (v1.0 Release). Additionally, an executable Jupyter Notebook serves as an experimental playground for Chapter 3 (Agent Loop). The tutorial is suitable for developers wanting to build agents with the Pi SDK, engineers who want to understand the internals of production-grade agents, and curiosity-driven folks who aren't satisfied with just using tools like Claude Code. Code is licensed under MIT, documentation under CC-BY-SA-4.0.
The repository provides a systematic tutorial on the Pi-Agent SDK, centered on source-code analysis. It covers Pi's Agent Loop (model loop invocation, stop conditions, error guardrails), tool system (five-step pipeline: define/register/intercept/execute/reclaim), message system (7 internal free expressions translated to 3 standard Messages), event-driven architecture (synchronous barriers + pub/sub), session management (Session Tree), and extension mechanism (factory functions + throwing stubs + event bus). Readers can follow the chapters sequentially (ch01 to ch10) or directly access Markdown docs under pi-agent/docs (TypeScript and Python folders). The web version and PDF version offer alternative reading modes. The Notebook (notebooks/agent-loop.ipynb) allows step-by-step execution and parameter adjustments for the Agent Loop. Three reading methods are provided: web (recommended), Markdown download, and PDF. The repository also includes a content map and contribution guidelines.
- Developers planning to build an AI Agent from scratch using the pi-agent SDK can quickly grasp core concepts and source implementation through this tutorial.
- Engineers who want to deeply understand the internal architecture of production-grade agents (e.g., Claude Code, Cursor, Cline) can learn by comparing with Pi's source code.
- Python-centric developers can use the Python documentation (pi-agent/docs/python) to learn Agent SDK design without TypeScript hurdles.
- Learners preferring an immersive reading experience can access the web version (dg-ai-notes.pages.dev) with a three-column layout, figures, and theme switching.
- Those needing offline or archival reading can download the PDF version (v1.0 Release).
- Researchers interested in Agent Loop mechanics can use the Notebook playground (notebooks/agent-loop.ipynb) for interactive exploration and debugging.
How do you install or deploy this agent?
This is a learning notes repository; no installation is required for runtime. For online reading, visit https://dg-ai-notes.pages.dev. To read locally, clone the repo: git clone https://github.com/buchidonggua/dg-ai-notes.git, then open the Markdown files under pi-agent/docs in a Markdown reader. The PDF can be downloaded from the GitHub Releases (v1.0).
How do you use this agent?
Choose a reading method: 1) Access the web version (recommended) for an immersive three-column experience; 2) Clone the repo and read Markdown files under pi-agent/docs (TypeScript: pi-agent/docs/typescript/, Python: pi-agent/docs/python/); 3) Download the PDF for offline reading. It's suggested to read chapters sequentially (ch01 to ch10). You can also run the Notebook (requires Jupyter Notebook or JupyterLab) notebooks/agent-loop.ipynb to experiment with Agent Loop, adjusting parameters and observing loop state.
What are this agent's strengths and limitations?
- In-depth analysis of a production-grade Agent SDK (Pi-Agent), covering core modules like Agent Loop, tool system, and message system, with clear explanations of design tradeoffs.
- Offers both TypeScript and Python versions, catering to readers with different language backgrounds.
- Multiple reading modes (web, Markdown, PDF) plus an interactive Agent Loop Notebook, enhancing learning.
- Systematic 10-chapter structure, each chapter answering what, how, and why.
- The tutorial is read-focused; companion experiment code (L00-L31) is not public, limiting hands-on practice.
- The content is tied to Pi-Agent source; readers unfamiliar with TypeScript or Agent basics may face a steep learning curve.
- Documentation is CC-BY-SA-4.0, requiring derivative works to be open-sourced, which may restrict commercial use.
- No direct installation/run instructions; relies on external web service (pages.dev) for best experience, and full hands-on requires manual source inspection.
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Donggua's AI Learning Notes: In-depth Pi-Agent SDK Tutorial This agent | 23 · Major gaps | Web appFree | ★ 3.4k | 1mo ago | MDX | — |
| Claude Code From Scratch | 60 · Some gaps | CLIFree + model costs | ★ 2.8k | 3mo ago | Python | OpenAI API · Claude API |
| PI from Scratch | 56 · Major gaps | CLIFree + model costs | ★ 1.3k | 2mo ago | TypeScript | OpenAI API |
| BeeAI Framework | 51 · Major gaps | Library / SDKFree + model costs | ★ 3.4k | today | Python | — |
How does FollowAgents rate this agent?
Why each dimension lost points
The evidence shows this is a learning notes repository without executable code or runtime behavior. Therefore, all trust-related criteria (least privilege, user confirmation, data flow transparency, sensitive data handling, dependency security, external effects, rollback, source attribution) have no supporting evidence and score 0. For source attribution, the README mentions the Pi-Agent official team and author, but lacks specific source links or verification, so it is only partially satisfied.
Self-consistency: The README describes the tutorial structure and content, which is broadly consistent with the repository's directory structure, but lacks detailed content verification, so score 1. Dependency availability: No dependency information is provided, score 0. Failure messages: No error handling or failure message descriptions are provided, score 0.
Audience and scenarios: The README clearly lists target audiences (developers wanting to use pi-agent SDK, engineers wanting to understand production-grade Agents, etc.) and provides multiple reading modes (Web, Markdown, PDF), score 2. Capability boundaries: The README describes the chapters and content covered, but does not explicitly state what is not covered, score 1. Trigger precision: Not applicable as this is not a triggerable Agent, score 0. Environment fit: Provides TypeScript and Python versions, but does not specify runtime environment requirements, score 1.
Information architecture: The README provides a clear table of contents and content map, score 2. Install notes: No installation or usage instructions are provided, score 0. Naming stability: Chapter naming is clear, but no information on naming changes across versions, score 1. Examples and FAQ: Provides a Notebook as an example, but no FAQ, score 1. Known limitations: The README mentions that companion experiment code is not public, but does not detail other limitations, score 1. License: Provides MIT license, score 2. Versioning and changelog: Mentions v1.0 Release, but no detailed changelog, score 1. Maintenance responsibility: The README provides contribution guidelines and author info, but does not explicitly state maintenance responsibility, score 1.
Output usability: Tutorials are provided in Markdown and PDF formats, but usability of output formats is not described, score 1. Marginal value: The tutorial provides in-depth analysis of Pi-Agent, high value for target audience, score 2. Cost-benefit: No cost or benefit analysis provided, score 1.
Claim traceability: The README mentions Pi-Agent official team and author, but lacks specific source links, score 1. Cross-source corroboration: No external verification provided, score 0. Fact-inference separation: The README distinguishes tutorial content and author opinions, but does not explicitly label them, score 1.
- Not found in source: least-privilege scopingGrant only what the task needs: a dedicated account or read-only token, scoped to specific directories and repos.
- Not found in source: confirmation before actingTurn on (or add) a confirmation step before it acts, and try it in a sandbox or test environment before real data.
- Not found in source: data-flow disclosureWatch which external services it contacts (proxy or firewall logs) and keep sensitive data out until you know where it goes.
- Not found in source: sensitive-data handlingUse dedicated, low-privilege, revocable API keys — never production credentials — and keep secrets out of logs.
- Not found in source: dependency securityPin versions and run a dependency audit (npm audit, pip-audit) before installing; prefer running it in a container.
- Not found in source: disclosed external effectsEstablish which external systems it writes to, sends to or changes, and verify with test accounts or repos before production.
- Not found in source: rollback or recovery pathBack up first, or work on a git branch or snapshot, so its changes can be undone.
- Not found in source: verifiable attributionInstall from the official repo or registry and check the publisher and URL to avoid look-alike packages.
- This repository is a learning notes repository without executable code, so runtime security and reliability cannot be assessed.
- No dependency information is provided, so dependency security cannot be evaluated.
- No installation or usage instructions are provided, which may affect practical use.
- No detailed changelog is provided, making it difficult to track updates.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
v1.0 v1.0 · Pi-Agent 教程首发（TS + Python 双版本 PDF）
Release notes excerpt
📚 Pi-Agent 教程首发 10 章深度拆解 [pi-agent](https://github.com/earendil-works/pi) SDK 的设计与实现，提供 TypeScript 与 Python 双版本。 📥 下载 | 文件 | 适用读者 | 大小 | |------|---------|------| | \pi-agent-book-ts.pdf\ | TypeScript / 前端 / 全栈 | 14 MB | | \pi-agent-book-python.pdf\ | Python / AI 工程师 | 16 MB | 🌐 在线版本 - Web 版（推荐 PC 阅读）：https://dg-ai-notes.pages.dev/ - Markdown 版（边读边问 AI）：见仓库 \pi-agent/docs/{typescript,python}/\ 📋 覆盖内容（10 章） ch01 开篇总览 → ch02 三层架构 → ch03 Agent Loop → ch04 模型调用 → ch05 工具系统 → ch06 消息系统 → ch07 事件驱动 → ch08 上下文工程 → ch09 上下文压缩 → ch10 会话管理 ⚠️ 关于版本 …View on GitHub ↗