bojieli/ai-agent-book
32.2
Weak · 15 November 2026
267.2k
lines of production code
Python
with JavaScript
5
measurements over time
What this system is
This repository is a comprehensive educational resource and codebase for building AI agents, structured as a multi-chapter book with accompanying executable experiments. It provides a unified framework for implementing agent architectures, covering core concepts like context management, tool use, memory systems, and multi-agent collaboration through reproducible code labs. The system supports a wide range of LLM providers and includes extensive infrastructure for internationalization, documentation generation, and rigorous experimental validation.
Features
Add Brazilian Portuguese translation of the book
The book is now available in Brazilian Portuguese, including all ten chapters, the afterword, and a PDF build script.
book-ptbr · high confidence
Add English translation of the book
Adds the English translation of the book in the book-en/ directory, including all chapters, an afterword, and a script to build the PDF.
book-en · high confidence
Add Korean edition of the AI Agents book
Introduces a complete Korean translation of the book, including all chapters, the afterword, and a PDF build script. The translation covers the core concepts of agent architecture, context engineering, memory, and tool use, providing Korean-speaking users with the same detailed explanations, code examples, and experimental findings as the original.
book-ko · high confidence
Add Russian translation of the book
Introduces a complete Russian-language edition of the book (book-ru), including all chapters, the afterword, and a build script to generate the PDF. This adds a new localized version to the i18n structure, allowing Russian-speaking users to access the full content.
book-ru · high confidence
Add chapter 2 attention visualization frontend
A new Next.js-based frontend has been added to visualize attention mechanisms for chapter 2. It provides a dashboard to load and inspect agent trajectories, featuring a sampled heatmap preview, a full interactive modal with zoom and multiple value transformations (log, sqrt, power, exclude-sink), and a statistics panel displaying average attention, maximum attention, and entropy per token. The visualization correctly labels heatmap rows with output tokens rather than input tokens, and the modal cancels its rendering chain on re-run or unmount to prevent visual artifacts.
_chapter2/attention\visualization/frontend · high confidence
Add complete Arabic edition of the book
The Arabic translation of the book is now available, including all chapters, the afterword, and a script to build a single RTL PDF.
book-ar · high confidence
Add image-generation workflow experiment (Experiments 1-4) with three comparison routes
Introduces a new executable experiment in \chapter1/image-gen-workflow\ that compares three text-to-image generation approaches: a workflow route using a Kimi (Moonshot) LLM to rewrite prompts followed by DashScope's Wanx 2.2 for image generation, a native route using Google's Gemini 3 Pro Image, and a native GPT-Image 2 route via OpenAI. The implementation includes a CLI entry point (\main.py\) to run five specific and broad Chinese-language requirements across all routes, an evidence system (\evidence.py\) that builds and validates JSON manifests with SHA-256 checksums for generated images and API call records, and offline tests (\tests/\) for configuration consistency, manifest schema, and prompt-parsing logic. The experiment is documented in a rewritten Chinese README and includes an \.env.example\ for required API keys.
chapter1/image-gen-workflow · high confidence
Added conversational UI validation run with chatbot backend and React frontend
This change introduces a new validation run for the conversational UI experiment, containing a FastAPI backend and a React frontend. The backend provides a /api/chat endpoint that supports both a default echo mode and an optional LLM mode (triggered via the --model flag or CHAT\_MODEL environment variable), with automatic fallback to OpenRouter for specific models. The frontend is a minimal React application that displays a chat interface, allowing users to send messages and receive replies from the backend. The setup includes Vite configuration for local development with HMR and API proxying.
_chapter5/conversational-ui/validation/runs/20260729T212616Z-5\_11-hmr, chapter5/conversational-ui/validation/runs/20260729T212727Z-5\_11-hmr, chapter5/conversational-ui/validation/runs/20260729T212933Z-5\11-hmr · high confidence
Added formal validation runner and stricter judging criteria for Experiment 6-14
This change introduces a new formal validation suite for Experiment 6-14 (native async steering). It adds a new \experiment.py\ runner in the \exp6-14-20260905-formal\ directory that executes real WebSocket calls against the OpenAI Responses API (with only venue lookup simulated) and records detailed wire-event traces. Crucially, it implements a stricter \judge\ function that validates specific behavioral constraints—such as ensuring steering is accepted before a successor response is created, verifying that tool call IDs match exactly, and rejecting results with invented receipts or stale parent IDs. A corresponding \test\_judging.py\ file is added to falsify pilot traces against these stricter criteria, ensuring that only evidence meeting the new rigorous acceptance standards passes validation.
chapter6/astra-async-steering/validation/runs/exp6-14-20260905-formal, chapter6/astra-async-steering/validation/runs/pilot-20260905-v1, chapter6/astra-async-steering/validation/runs/pilot-20260905-v2 · high confidence
Chapter 3 documentation and experiment ledger added
This change introduces the complete documentation for Chapter 3, including a new \EXPERIMENT\_LEDGER.md\ that defines acceptance criteria and evidence paths for 12 experiments (3-1 through 3-12) covering user memory, RAG pipelines, and knowledge extraction. It also adds localized README files in English, Arabic, Spanish, Hungarian, Indonesian, Japanese, Korean, Russian, Tamil, Turkish, and Vietnamese, which outline the chapter's scope, reading order, and companion projects.
chapter3 · high confidence
Chapter 6 documentation and experiment ledger introduced
Chapter 6 (Interaction) is now a standalone section with a comprehensive README and a bilingual experiment ledger. The ledger records the status, canonical run paths, and SHA-256 manifests for experiments 6-1 through 6-3, and provides a mapping table that aligns the current reading-order numbering (6-1 to 6-14) with archived run identifiers. The READMEs (English, Chinese, Arabic, Spanish, Hungarian, Indonesian, Japanese, Korean, Russian, and Tamil) describe the chapter’s scope—event-driven agents, asynchronous control, streaming and end-to-end speech, Computer Use, and robotic manipulation—and provide reading guidance for Starter, Builder, and Maintainer workflows. The ledger notes that experiment 6-1 is blocked due to credential authentication failures, while 6-2 and 6-3 have passed their manuscript gates. The documentation also details external reproduction anchors for experiments 6-8 through 6-14, including pinned upstream commits for Anthropic’s Computer Use demo, browser-use, XLeRobot, RoboCrew, and sim2real environments, along with instructions for local verification and evidence collection.
chapter6 · high confidence
Chapter 7 introduces a formal experiment ledger and standardized multilingual documentation
Chapter 7 now includes an \EXPERIMENT\_LEDGER.md\ that formally tracks the acceptance status, evidence paths, and audit results for experiments 7-1 through 7-14, distinguishing between complete campaigns, incomplete long-running tests, and external reproduction guides. The chapter's \README\ files have been standardized across all supported languages (Arabic, English, Spanish, Hungarian, Indonesian, Japanese, Korean, and Chinese) to align with this ledger, providing consistent navigation instructions for Starter, Builder, and Maintainer roles and clarifying the distinction between standalone code and external benchmark dependencies.
chapter7 · high confidence
Chapter 8 documentation and experiment infrastructure overhaul
This change introduces comprehensive documentation, training reports, and evaluation scripts for multiple Chapter 8 experiments, including AWorld-train, AdaptThink, Intuitor, and MiniMind-pretrain. It adds detailed READMEs explaining the methodologies (e.g., RLIF, AdaptThink routing, QK-Norm + Muon optimizer), training configurations, and results. It also includes an experiment ledger tracking the status of all Chapter 8 experiments, validation scripts for auditing training reports, and regression tests for answer extraction and normalization in the Intuitor experiment.
chapter8 · high confidence
Chapter 9 documentation restructured with multilingual READMEs and new writing-style Skill experiment
The chapter9 area has been updated with new README files in 11 languages (Arabic, English, Spanish, Hungarian, Indonesian, Japanese, Korean, Russian, Tamil, Turkish, Vietnamese, and Traditional Chinese) that reorganize the chapter's navigation and project catalog. The documentation now explicitly lists nine companion experiments (9-1 through 9-9), including trajectory verification, prompt auto-optimization, browser-use RPA, self-modifying agents, and a self-evolution evaluation, while marking Experiment 9-4 as a design document. A new 'ai-style-skill' project has been added, which implements an open-ended rule extraction pipeline using an LLM judge to convert user feedback on 'AI-flavored' writing into verifiable style rules, complete with candidate rule definitions and validation evidence.
chapter9 · high confidence
Coding agent gains multi-provider support with OpenRouter fallback
The coding agent in chapter5/coding-agent now supports Anthropic, OpenAI, and OpenRouter as LLM providers. Users can select their provider via the PROVIDER environment variable and supply the corresponding API key. A key behavioral change is the automatic OpenRouter fallback: if a user selects Anthropic or OpenAI but lacks that provider's API key, the agent transparently routes requests through OpenRouter using the OPENROUTER\_API\KEY, automatically mapping model names (e.g., claude-sonnet-\ to anthropic/claude-sonnet-4.6). This is enabled by new configuration logic in config.py and provider-aware client initialization in agent.py, along with updated documentation in PROVIDERS.md and .env.example.
chapter5/coding-agent · high confidence
Context-aware agent with ablation studies and secure calculator
The chapter1/context experiment now provides a complete, runnable context-aware agent that supports multiple LLM providers (including Kimi K3, GPT-5, DeepSeek, and OpenRouter fallback) and four tools (PDF parsing, currency conversion, calculation, and code execution). It introduces five ablation modes (Full, No History, No Reasoning, No Tool Calls, No Tool Results) to study how removing specific context components affects agent behavior, with a new grounding module that detects when models generate unsupported numbers without tool observations. The calculator sandbox has been hardened to use AST whitelist validation instead of eval, preventing code injection attacks. The experiment includes a validation report visualizer, bilingual documentation, and a sample financial report PDF for testing.
chapter1/context · high confidence
Contextual Retrieval system with semantic IDs and conversation history fix
The chapter3/contextual-retrieval experiment now implements Anthropic-style contextual retrieval by prepending LLM-generated context to document chunks before indexing, significantly improving top-1 recall in offline BM25 evaluations. Document and chunk identifiers have shifted from opaque MD5 hashes to human-readable semantic IDs derived from filenames, making the indexed data transparent and debuggable. The agentic RAG agent now supports a conversation history limit, correctly treating a limit of zero as no history retention, and includes a universal OpenRouter fallback for LLM providers when primary API keys are missing.
chapter3/contextual-retrieval · high confidence
Experiment 5-5: Automated paper-to-lecture video generation
Adds a new end-to-end pipeline for Experiment 5-5 that converts academic papers into narrated lecture videos. The process generates slide screenshots, creates oral narration using LLMs (defaulting to Kimi K3 via Moonshot), and synthesizes audio using Fish Audio S1. An independent visual reviewer (Qwen-VL-Max) validates the narration against the slides to ensure factual accuracy. The final video is assembled using ffmpeg, ensuring precise synchronization between the audio and slide display times. The entry includes a \campaign.py\ runner for production-grade execution with strict acceptance criteria (e.g., 5–15 minute duration, \<0.2s per-page drift) and a \demo.py\ for quick testing or offline simulation.
chapter5/paper-to-video · high confidence
Hebrew edition of the book is published and integrated
The Hebrew translation of the book is now available, including all ten chapters, an afterword, and a dedicated script to build a right-to-left PDF using LuaLaTeX.
book-he · high confidence
Hungarian edition of the book is published
The Hungarian translation of the book is now available, including all ten chapters, an afterword, and a script to build the PDF.
book-hu · high confidence
Indonesian translation of the book is now available
The book is now available in Indonesian. This release includes the full text of all chapters, the afterword, and the introduction, along with a build script to generate the PDF. The translation covers the core concepts of AI Agents, including the formula Agent = LLM + Context + Tools, the ReAct loop, tool design, and multi-agent collaboration.
book-id · high confidence
Initial release of Traditional Chinese (book-zhtw) translation
Adds the Traditional Chinese translation of the book, including all chapter source files (chapters 1–10), the afterword, and the PDF build script. This provides a complete, localized version of the content for Traditional Chinese readers.
book-zhtw · high confidence
Initial release of the English Slidev course structure and generator
The slides directory now contains the complete scaffolding for the 42-lesson English video course, including a course outline, a Slidev build script, and a generator that produces individual lesson decks from a central curriculum definition. This adds the foundational content structure and tooling for the course, establishing the lesson numbering, chapter allocations, and slide generation pipeline.
slides · high confidence
Introduce Experiment 10-4: Parallel real-browser web research with multi-agent coordination
This location adds a complete, runnable experiment (Experiment 10-4) that demonstrates parallel web research using multiple independent Playwright Chromium browser contexts. The implementation features a central Coordinator and homogeneous WorkerAgents communicating via an in-process asynchronous message bus. Key capabilities include dynamic N-way launch per real university URL, per-site timeout and error isolation, lock-protected single-winner settlement for the first \target\_found\ event, and a cascade terminate broadcast that racing workers acknowledge before safely closing their browser contexts. The experiment includes a CLI demo (\demo.py\) that runs both parallel and serial baselines on live Stanford pages to measure wall-clock speedup, alongside an official experiment runner (\run\_official\_experiment.py\) that captures provenance-complete receipts (browser observations, LLM request/response bodies, and bus events) and runs acceptance gates. Tests verify coordination logic, such as handling terminate signals before task assignment and correctly excluding self-completed workers from expected loser acknowledgements.
chapter10/parallel-web-research · high confidence
Introduce Experiment 5-11: Conversational UI Customization
Adds a new experiment that allows an AI agent to customize a React frontend (Vite) via natural language requests. The agent modifies specific source files (App.jsx, theme.css) using a function-calling tool, with changes applied via Vite's Hot Module Replacement (HMR) for immediate visual feedback. The package includes a FastAPI backend for chat interactions, a baseline snapshot for reproducible testing, and automated demo scripts that verify code modifications and build integrity.
chapter5/conversational-ui · high confidence
Introduce Experiment 5-8: Automated Production Log Diagnosis and Regression
Adds a new experiment (Experiment 5-8) that provides an end-to-end pipeline for diagnosing production issues from agent trajectory logs. The system uses an LLM-based agent to analyze trajectory data, system architecture, and product requirements to identify root causes and generate structured reports. It automatically creates regression test cases based on these findings and executes them against a deterministic simulation of the system to verify bug reproduction and fix validation. The experiment also includes a mock (and optional real via MCP) GitHub Issue creation step to demonstrate automated workflow integration.
chapter5/log-diagnosis · high confidence
Introduce Tamil (ta) edition of the book
Added a new Tamil translation of the book, including the full chapter content, an afterword, and a dedicated PDF build script (build\_pdf.sh) to generate the final document. This brings the total supported languages to include Tamil alongside the existing English, Chinese, and others.
book-ta · high confidence
Introduce Vietnamese edition of the book
Adds the Vietnamese translation of the book, including source Markdown files for all chapters, an afterword, a PDF build script, and a gitignore file.
book-vi · high confidence
Introduce active tool discovery experiment in Chapter 4
This change adds a new experiment to the Chapter 4 location that compares three tool discovery strategies: full injection, retrieval prefiltering, and active discovery. The experiment uses a library of 126 tools and demonstrates how active discovery reduces token usage and improves tool selection accuracy by retrieving tools on-demand rather than injecting all schemas into the context. It includes a demo script for running the experiment with real models or in offline mode, an agent implementation using a text-based ReAct protocol, and a discovery module for semantic tool retrieval. The experiment also includes a runner for executing the exact Chapter 4 Experiment 4-1 contract with MCP tools and Ollama, along with tests for the experiment runner.
chapter4/active-tool-discovery · high confidence
Introduce context compression experiment with OpenRouter fallback and Kimi K3 support
The chapter2/context-compression directory now provides a complete, runnable experiment comparing six context compression strategies (no compression, individual/combined summaries, context-aware summaries, citations, and windowed context) for an AI research agent. The implementation upgrades the default model from the retired Kimi K2 to Kimi K3 and adds GPT-5 support, while introducing a universal OpenRouter fallback that activates when the primary Moonshot API key is missing. The agent now correctly tracks the current context size against the window limit using per-request prompt tokens rather than a cumulative cost counter, and includes robust error handling for malformed tool arguments and null content to prevent crashes during tool dispatch.
chapter2/context-compression · high confidence
Introduce educational BM25 sparse search engine with CLI, API, and benchmarks
Adds a from-scratch BM25 sparse vector search engine to chapter 3, featuring an inverted index, a TextProcessor that handles technical tokens (codes, emails, version numbers, apostrophes), and a FastAPI server on port 4241. Users can run offline CLI experiments with per-term TF/IDF explanations and evaluation metrics (recall@k, precision@k, MRR) against a labeled corpus, or interact via the HTTP API and web UI. The package includes acceptance benchmarks that verify scoring correctness against hand calculations and demonstrate BM25’s exact-keyword strength versus synonym gaps, plus a quickstart script for interactive exploration.
chapter3/sparse-embedding · high confidence
Introduce multi-agent book translation with manager orchestration and bilingual consistency auditing
This location adds a complete book-translation experiment demonstrating a four-agent orchestration pattern (Manager, Glossary, Translation, and Proofreading) that controls context growth by persisting full translations to the file system while the Manager only tracks metadata and file indices. The implementation includes a bilingual consistency auditor module to verify terminology mapping, code block synchronization, LaTeX formula preservation, and link targets across source and translated Markdown files, alongside a demo script that supports offline dry-runs and automatic fallback to OpenRouter when only an OpenRouter API key is configured. Robustness fixes ensure the system gracefully handles non-dictionary JSON, null values, and empty lists in proofreading reports and glossaries, preventing crashes during agent interactions.
chapter10/book-translation · high confidence
Introduce three-layer user memory evaluation framework with offline comparison and LLM-as-judge
Adds a new evaluation suite for AI agent memory capabilities in Chapter 3, structured across three progressive complexity layers: basic recall, contextual disambiguation, and cross-session synthesis. The framework includes 60 test cases (20 per layer) featuring realistic business conversations with 50+ rounds each, supporting interactive, batch, and programmatic evaluation modes. Users can run fully offline keyword-recall comparisons against example memory configurations (full context, JSON cards, simple notes, no memory) or switch to an LLM-as-judge mode using Kimi K3 or GPT-5.6 via OpenRouter fallback, with detailed scoring across precision, recall, reasoning, and proactivity dimensions.
chapter3/user-memory-evaluation · high confidence
Introduces Agent Skills PPT experiment with progressive disclosure and runtime-agnostic support
Adds a new Chapter 2 experiment that demonstrates how an agent can generate a PowerPoint presentation from a research paper using a 'progressive disclosure' skill mechanism. The location provides a self-contained Python demo (\demo.py\) that implements a custom skill loader—scanning a thin metadata catalog, then loading full skill instructions and scripts on demand—using \python-pptx\ to generate the output. It also includes a protocol definition (\experiment\_protocol.json\) and runner scripts (\run\_official\_experiment.py\) that support both the official Anthropic PPTX Skill via Claude Code and an alternative runtime via Kimi Code CLI, ensuring the experiment can be reproduced without Anthropic credentials.
chapter2/agent-skills-ppt · high confidence
Introduces Paper-to-PPT experiment with Proposer-Reviewer agent loop
Adds the Chapter 5 'Paper-to-PPT' experiment, which automates the generation of Slidev presentations from academic papers using a dual-agent workflow. The Proposer agent generates and refines Slidev markdown, while a Reviewer agent uses a Vision LLM to render the slides as PNGs and provide structured feedback on layout issues like text overflow and image sizing. The demo script supports a 'single agent self-review' mode for comparison, tracks token consumption via a TokenMeter, and includes offline smoke tests and dry-runs to validate the rendering pipeline without requiring API keys.
chapter5/paper-to-ppt · high confidence
Introduces Permission-Embedded Data Objects (PEDO) prototype with BaxBench security evaluation
This change adds the core Permission-Embedded Data Objects (PEDO) library, including data models, a PostgreSQL-backed object store with a three-tier permission pipeline, and a comprehensive evaluation suite. The evaluation suite includes a BaxBench adapter that translates security scenarios (SecretStorage, UserCreation, ShoppingCart, ImageTransfer) into function-level tests, reference implementations for secure and insecure raw patterns, and an end-to-end hiring pipeline benchmark to compare PEDO against raw SQL and API-based authorization.
chapter5/permission-embedded-data-objects/pedo · high confidence
Introduces active tool discovery experiment with hierarchical semantic routing
Adds a new chapter 4 experiment that implements an active tool discovery agent (inspired by MCP-Zero), allowing the model to iteratively request specific tools on-demand rather than injecting all schemas upfront. The system uses a two-stage hierarchical semantic router (server-level then tool-level matching via TF-IDF) to find relevant tools, significantly reducing context token usage compared to passive injection. The location includes the agent implementation, routing logic, a tool knowledge base, offline benchmarking utilities, and comparison demos against passive and retrieval-based strategies.
chapter4/active-tool-selection · high confidence
Introduces judicial case analysis pipeline with bottom-up factor discovery and archetype clustering
This location adds a complete experiment for extracting latent knowledge from structured legal data. It provides a four-stage pipeline: \discovery.py\ performs bottom-up factor discovery to generate a modular schema from case text; \extractor.py\ uses that schema for structured extraction; \archetypes.py\ clusters cases by charge into 'archetypes' and calculates global factor importance; and \advisor\_agent.py\ implements a conversational agent that matches new cases to these archetypes to provide explainable sentencing advice. The directory includes a synthetic dataset (\data/cases.jsonl\) for teaching, a canonical \campaign.py\ for running the pipeline on the official CAIL2018 dataset, and a \config.py\ that supports OpenAI, DashScope (Qwen), and a universal OpenRouter fallback.
chapter3/structured-knowledge-extraction · high confidence
Introduces self-healing adaptive log parser with automatic code generation and hot-reloading
Adds a new experiment (5-7) that demonstrates a self-evolving log parsing system. When the parser encounters an unknown log format, it triggers a self-healing loop: an AI agent generates a Python parsing function, which is then validated by an automated tester. If the test passes, the new parser is hot-loaded into the running engine and persisted to disk for future use, allowing the system to adapt to new log formats without manual intervention. The package includes a demo script, an offline mode for deterministic testing without API keys, and a live campaign script that can generate real-time log samples to test the adaptation process.
chapter5/adaptive-log-parser · high confidence
Introduces voice-enabled Werewolf game with multi-agent information isolation
This change adds a new voice-enabled Werewolf game system in the \chapter10/voice-werewolf/werewolf\ package. It implements a multi-agent architecture where each player is an independent LLM agent with strictly isolated private context (memory), ensuring information asymmetry (e.g., wolves only see teammate identities, seers only see verification results). The system includes a deterministic Judge agent to orchestrate game phases and enforce information permissions, along with an audit log to verify information visibility. It supports real human players via live voice sessions (ASR/TTS) and simulated users via LLM-driven voice simulation, with fallback to offline rule-based strategies for reproducibility. The implementation also includes strategy acceptance audits to validate agent behavior against role-specific criteria.
chapter10/voice-werewolf/werewolf · high confidence
Japanese edition of the book is added
The Japanese translation of the book is added, including all chapters, the afterword, and a PDF build script.
book-ja · high confidence
Mem0 v3 agent with Kimi K3 and OpenRouter fallback
The chapter3/mem0 experiment now implements a memory agent using Mem0 v3's ADD-only fact extraction and hybrid retrieval, integrated with the Kimi K3 language model. It supports persistent, cross-session memory via local Chroma or Mem0 Cloud backends, and includes a universal OpenRouter fallback for the chat LLM (with automatic model mapping) while retaining OpenAI embeddings for the memory store. The update adds interactive, batch, and LOCOMO benchmark modes, along with contract tests for the v3 memory filters and result extraction.
chapter3/mem0 · high confidence
New \<agent-trajectory\> Web Component for replaying agent runs
The agent-lab area now includes a self-contained \\<agent-trajectory\>\ Web Component that replays an agent's ReAct loop step-by-step in the browser. It consumes a JSON trajectory (defined by the new SCHEMA.md) containing thought, action, observation, and answer steps, and renders them in a timeline with toolbar controls and progress indication. Two sample trajectories are provided to demonstrate usage: one showing a successful GPT-5.6 run solving an ASEAN capitals distance problem, and another illustrating an ablation scenario where missing tool results cause the agent to loop.
extras/agent-lab · high confidence
New API-driven smart video editing experiment with vision-based scene detection
This location introduces Experiment 5-6, an automated video editing workflow that takes natural language requests (e.g., "cut the surfing part") and executes them via a multi-agent system. The system uses a two-step vision process to locate scene boundaries in a video, then generates a Blender Python API (bpy) script to perform the actual editing (trimming, slow motion, subtitles). If Blender is not installed, it falls back to ffmpeg. The experiment includes a demo script, agent logic for proposal and review, and validation campaigns to verify the accuracy of the vision-based scene detection.
chapter5/video-edit · high confidence
New Agentic RAG experiment for user memory with LLM evaluation and OpenRouter fallback
This location introduces a new Chapter 3 experiment (\agentic-rag-for-user-memory\) that applies Agentic RAG to user conversation memory. The system chunks long conversations, indexes them via an optional external retrieval pipeline (port 4242) or a local BM25 fallback, and uses a ReAct agent to retrieve context. It includes automatic LLM-based evaluation of agent responses (reward scoring and pass/fail) and supports multiple LLM providers (Kimi K3, GPT-5.6-luna, etc.) with a universal OpenRouter fallback when primary keys are missing.
chapter3/contextual-retrieval-for-user-memory · high confidence
New Astro-based web reader for the AI Agents book
A new static-site reader built with Astro has been added, providing a responsive, multilingual interface for the full 10-chapter book across 15 language editions. The reader features a persistent reading bar, adjustable text sizing, light/dark themes, and focus mode. It supports passage highlighting with local IndexedDB storage, note-taking with draft persistence, and JSON backup export/import. Chapter 2 includes new web-optimized SVG diagrams for cache evolution, compression strategies, and agent status bars. The site is configured for GitHub Pages deployment and includes a deployment verification suite to ensure link and asset integrity across all locales.
web-astro · high confidence
New Collaboration Tools MCP Server with sub-agent management and HITL workflows
A new Collaboration Tools MCP Server has been added to chapter4/collaboration-tools, providing 19 tools across five categories: browser automation (using browser-use and Playwright), human-in-the-loop (HITL) approval and input workflows, multi-channel notifications (Email via SMTP/SendGrid, Telegram, Slack, Discord), timer and scheduling (one-time and recurring with persistent JSON storage), and sub-agent management (spawn, send messages, cancel, and status checks with sync/async modes and minimal/llm\_generated context strategies). The server is implemented with FastMCP, includes a Dockerfile for containerized deployment, and is accompanied by comprehensive documentation, installation guides, and runnable demo scripts.
chapter4/collaboration-tools · high confidence
New Execution Tools MCP Server with multi-language support and safety mechanisms
This location introduces the Experiment 4-4 Execution Tools MCP Server, providing a unified CLI and server interface for file operations, code execution, and external integrations. The server supports multi-language code execution (Python, JavaScript, Go, Java, C++, Rust, PHP, Bash) via a Dockerfile-based environment and includes built-in safety mechanisms such as LLM-driven approval for dangerous operations, automatic syntax verification, and long-output truncation with persistence. It also integrates with Google Calendar and GitHub, and offers a universal OpenRouter fallback for LLM steps when primary provider keys are missing.
chapter4/execution-tools · high confidence
New Experiment 5-13: Agent Creator with Scratch and Template Comparison
This location introduces a runnable experiment that compares two methods for generating specialized agents: building from scratch versus adapting a proven template. The \creator.py\ module orchestrates this comparison using a real model, while \validator.py\ enforces strict structural, security, and behavioral gates (including bounded loops and tool protocol audits). The \demo.py\ entry point runs the full campaign, producing a \comparison.json\ report that details token usage, costs, and validation results for both strategies.
chapter5/agent-creator · high confidence
New Experiment 5-9: Dynamic Form Intent Clarification
This location introduces Experiment 5-9, a new capability where an AI agent generates a self-contained HTML form to clarify incomplete user requests (e.g., flight booking) in a single step, rather than asking sequential questions. The \demo.py\ script supports two modes: an online mode that uses an LLM (defaulting to \gpt-5.6-luna\ via OpenAI or OpenRouter) to generate the form, and an offline mode that deterministically renders a schema-based form without API keys. The generated forms include cascading JavaScript logic (e.g., showing return dates only for round-trip selections) and submit structured JSON back to the agent. A companion \campaign.py\ script provides a rigorous live validation path using Playwright/Chromium to execute the form's JavaScript and verify the end-to-end flow. The experiment also includes specific fixes for handling numeric zero baggage counts and ensuring trip-type modifiers do not leak into destination fields.
chapter5/dynamic-form · high confidence
New Memobase agent experiment with multi-provider LLM support and LOCOMO benchmark
This location introduces a new Chapter 3 experiment featuring two parallel implementations: a hand-rolled memory agent (\agent.py\, \main.py\) that persists episodic, semantic, procedural, and working memories via pickle, and a demo of the official Memobase SDK (\profile\_demo.py\) for Profile and Event Memory. The hand-rolled agent now supports Alibaba Cloud Qwen (via DashScope) and provides a universal OpenRouter fallback when primary API keys are missing, alongside a new LOCOMO benchmark suite (\locomo\_benchmark.py\) for evaluating long-context and memory-intensive tasks. Robustness improvements include guards for empty inputs and environment file loading, supported by new regression tests for benchmark evaluation edge cases.
chapter3/memobase · high confidence
New NL-to-SQL ERP Agent experiment with artifact-mode architecture
Adds Experiment 5-10, a new CLI-based agent that converts natural-language questions into SQL queries for an ERP dataset (employees and salaries). The agent operates in 'artifact mode', meaning it only generates the SQL text while the system executes it against a database (SQLite by default, with a PostgreSQL campaign script provided) and returns result tables. The package includes a reproducible seed data generator, a Python reference implementation for validation, gold-standard SQL for offline testing, and a demo CLI with subcommands to run online agent generations, execute offline gold queries, ask single questions, or initialize the database.
chapter5/erp-agent · high confidence
New attention visualization experiment suite for Chapter 2
This location introduces a complete, reproducible attention visualization toolkit for Chapter 2. It provides a standalone CLI (\attention\_cli.py\) to render self-attention heatmaps as PNGs for arbitrary prompts, layers, and heads, and a full interactive frontend (React app) that loads and compares agent-generated trajectories. The suite includes two canonical experiment runners (\run\_attention\_experiment.py\ for Experiment 2-2 and \run\_status\_bar\_experiment.py\ for Experiment 2-8) that execute real Qwen3-0.6B models with eager attention, capture lossless attention matrices, and verify acceptance gates. It also adds a ReAct tool-calling agent (\main.py\), a base attention-tracking agent (\agent.py\), a tool registry (\tools.py\), and a suite of regression tests to ensure correct trajectory saving, metric calculation, and experiment logic.
_chapter2/attention\visualization · high confidence
New autonomous phone/browser orchestration experiment (10-3) with WebRTC
This location introduces the autonomous arm of Experiment 10-3, where a Playwright Computer Use Agent inspects a real registration form and an LLM with \tool\_choice=auto\ decides whether to spawn a Phone Agent. The default transport is a local WebRTC call (no PSTN provider or public webhook required), carrying agent and participant audio on separate RTP tracks. The Phone Agent collects field values via speech, validates them against page constraints, and streams valid values back to the browser Agent for concurrent filling; format errors trigger re-asking. Submission is opt-in via \--submit\ to prevent accidental account creation. The implementation includes a message bus with redacted traces, decision records preserving raw LLM request/response metadata, and acceptance tests that verify the full audio/media path and localhost form submission using synthetic data.
chapter10/autonomous-phone-registration · high confidence
New browser-agent demo applications and chapter content
This update introduces several new example applications that use browser agents with Google Gemini to automate web tasks: an ad generator that creates Instagram image and TikTok video ads from landing pages, a WhatsApp message scheduler that parses natural language instructions to send or schedule messages, and a news monitor that extracts articles with sentiment analysis. It also adds a localized timeout configuration module for a model-action task and includes new book content for Chapter 6 on interactions.
(repo-wide) · high confidence
New dense embedding vector search service with ANNOY/HNSW backends
Introduces a new educational vector similarity search service in chapter3/dense-embedding, featuring a FastAPI HTTP server and a CLI tool for offline benchmarking. The service uses the BGE-M3 embedding model and supports two approximate nearest-neighbor backends: ANNOY and HNSW. The CLI tool allows users to run semantic retrieval experiments, compare recall and latency between the two index types, and evaluate performance against ground-truth labels, with support for both online (BGE-M3) and offline (MiniLM) models.
chapter3/dense-embedding · high confidence
New evaluation framework and dataset for Chinese legal RAG comparison
This change introduces a new evaluation suite in the \chapter3/agentic-rag/evaluation\ directory to compare agentic versus non-agentic RAG performance on Chinese criminal law questions. It adds \dataset\_builder.py\ to generate a structured dataset of 15 legal cases (simple and complex), \evaluate.py\ to run the \RAGEvaluator\ against both agentic and non-agentic modes and compute metrics like keyword/analysis recall and citation presence, and \offline\_qa.json\ for offline retrieval comparison. The evaluation logic now safely handles empty \expected\_keywords\ or \expected\_analysis\ lists by returning a recall of 1.0 instead of raising a ZeroDivisionError, a behavior verified by new unit tests in \test\_evaluate\_empty\_expected.py\.
chapter3/agentic-rag/evaluation · high confidence
New experiment comparing CAD code generation vs. 3D generative models
Added a new experiment (5-7) that contrasts two approaches for creating 3D parts: Route A uses an LLM (Kimi) to generate CadQuery code for precise, parametric modeling, while Route B uses a two-step text-to-image (Gemini) and image-to-3D (Hunyuan3D-2.1) pipeline. The experiment includes a main task (a flange with specific mechanical constraints) and a control group (a potted plant) to demonstrate that code generation is superior for precise engineering tasks, whereas generative models are better for natural, aesthetic content. It provides the full implementation, measurement scripts, and a structured manifest for validating results.
chapter5/cad-vs-diffusion · high confidence
New experiment for Permission-Embedded Data Objects (PEDO) with live security evaluation
Added a new experimental module in chapter5/permission-embedded-data-objects that demonstrates how to enforce authorization and data integrity through a stable data layer rather than generated application code. The module includes a deterministic demo (demo.py) and a live security evaluator (run\_live\_security\_eval.py) that test agent-generated code against PEDO access control models, covering row-level security, field visibility, privilege escalation, and performance metrics. It also provides a targeted cross-provider evaluation (run\_targeted\_eval.py) comparing PEDO interfaces against raw SQL for adversarial prompts across Claude and GPT models.
chapter5/permission-embedded-data-objects · high confidence
New experiment harness for logic puzzles with constraint-solver baseline and LLM comparison
This location introduces the complete code and data for Experiment 5-2, which evaluates how using code tools improves logical reasoning on 'Knights and Knaves' puzzles. The \demo.py\ script runs three modes: a pure natural-language baseline, a code-assisted mode where an LLM uses a \run\_python\ tool to solve constraints, and an offline \solver\ baseline using \python-constraint\ for deterministic verification. The setup includes a curated set of 12 puzzles (\build\_puzzles.py\) and a stratified 84-puzzle test set from the Hugging Face \K-and-K/perturbed-knights-and-knaves\ dataset (\build\_hf\_puzzles.py\), along with a sandboxed code execution environment (\sandbox.py\) and comprehensive tests for parsing logic and solver edge cases.
chapter5/code-for-logic · high confidence
New experiment: Code-assisted math solving with AIME 2024 benchmark
Adds Experiment 5-1, a new lab that compares pure Chain-of-Thought reasoning against code-assisted solving (using a Python sandbox with sympy/numpy/scipy) on the official 2024 AIME math competition problems. The entry includes the \demo.py\ runner, a \sandbox.py\ for safe code execution, the \aime\_2024.json\ dataset, and validation scripts to verify results.
chapter5/code-for-math · high confidence
New experiment: Codified rules for small models (Experiment 5-3)
This location introduces a new controlled experiment demonstrating that codifying business rules into code-based guards allows a small model (qwen3:4b) to match the reliability of a large model. The implementation includes a simulated airline environment with a server-side clock and a strict \is\_refundable\ policy function. It provides two agent modes: a 'control' group where the model relies solely on natural language prompts, and a 'codified' group that uses a checklist tool and a server-grounded truth gate to reject policy violations. The experiment runs a 60-case factorial matrix across cabin types, booking ages, and flight statuses, providing a reproducible benchmark for rule adherence.
chapter5/small-model-codified-rules · high confidence
New experiments for cross-provider agent handoff and streaming interruption recovery
Added a new \chapter5/provider-failover\ module that implements and validates two key resilience strategies for AI agents: cross-provider trajectory handoff (Experiment 5-1) and streaming output continuation after interruption (Experiment 5-2). The module provides a neutral trace format to decouple reasoning and tool states from vendor-specific JSON structures, enabling three handoff strategies (direct pass-through, stripping, and neutral) across Moonshot, Anthropic, and Gemini. It also includes a streaming interruption simulator to test recovery via full resend, prefix prefill, and meta-instructions, complete with offline tests and a judging system to verify data integrity and prevent duplicate side effects.
chapter5/provider-failover · high confidence
New flat 'fenix' theme and client-side machine translation for unsupported languages
The site now applies a new flat, minimal visual style (referred to as 'fenix') that removes Material Design shadows and rounded corners, featuring a white background, a 57px header, and a collapsible 320px sidebar. Additionally, an opt-in machine-translation tier is introduced for languages not yet officially supported; this feature uses a third-party library to translate page text in the browser, clearly labeling the content as machine-translated and excluding code blocks and diagrams from translation.
extras · high confidence
New hybrid retrieval pipeline with dense, sparse, and reranking stages
This location introduces the complete companion code for Chapter 3 Experiment 3-6, providing a hybrid retrieval pipeline that combines dense embeddings (e.g., Qwen3-Embedding-0.6B or BGE-M3), sparse keyword search (BM25), and neural reranking (e.g., BGE-Reranker-v2-M3). The package includes a FastAPI service (\main.py\) listening on port 4242 for indexing and searching, alongside an offline evaluation CLI (\evaluate.py\) and a canonical campaign script (\campaign.py\) for reproducible benchmarking. It also provides configuration (\config.py\), result fusion logic (\fusion.py\), and educational demo scripts (\demo.py\) to illustrate the strengths of each retrieval method.
chapter3/retrieval-pipeline · high confidence
New log-sanitization experiment in chapter 3
A new experiment has been added to chapter 3 that demonstrates how to detect and redact sensitive information from agent logs. It provides two complementary engines: an offline rule-based engine using regex and validation algorithms (Luhn, ID card checksums) that requires no external dependencies, and a local LLM engine using Ollama (defaulting to qwen3:0.6b) for semantic PII detection. The experiment includes a benchmarking script to compare regex, LLM, and hybrid approaches, along with performance metrics and structured output validation.
chapter3/log-sanitization, chapter4/multimodal-agent · high confidence
New multi-role transfer experiment comparing system prompt switching vs. skill loading
A new Chapter 10 experiment (10-1) has been added to compare two methods for implementing multi-role agent behavior within a shared conversation history. The first method, 'transfer\_to\_agent', dynamically swaps the system prompt and tool set for the current role while preserving the full chat history. The second method, 'load\_skill', keeps the system prompt and tool definitions static, instead appending role-specific instructions (SKILL.md) as tool results to the trajectory. The package includes a demo entry point, an orchestrator for the transfer mechanism, a skill loader, five predefined professional roles (triage, research, coding, data\_analysis, writing), and a comprehensive evaluation suite with deterministic rubrics and blind quality judges to measure pass rates, token costs, and instruction following.
chapter10/multi-role-transfer · high confidence
New prompt engineering ablation study framework for Chapter 2
Adds a complete experiment suite in \chapter2/prompt-engineering\ to quantify how prompt structure affects agent performance on the τ-bench benchmark. The new \AblationAgent\ and associated scripts (\run\_ablation.py\, \analyze\_results.py\) support three specific modifications: applying distinct tone styles (e.g., 'Trump' or 'casual'), randomizing the instruction wiki, and removing tool descriptions. The agent logic includes specific handling for reasoning models like GPT-5 (setting \reasoning\_effort='low'\) and Kimi K3 (adjusting token limits) to ensure stable execution. The directory also includes configuration guides, debug scripts, and example result files to facilitate reproducible teaching and evaluation.
chapter2/prompt-engineering · high confidence
New prompt injection attack and defense experiment for Chapter 2
Adds a new companion experiment (Experiment 2-5) that demonstrates prompt injection risks and layered defenses. The module includes an agent with sensitive capabilities (a hidden secret key and high-risk tools like write\_file and send\_email), three attack scenarios (direct, indirect, and memory injection), and four progressive defense configurations (no defense, prompt hardening, source tagging, and runtime guard). Users can run the experiment via demo.py to generate an attack-by-defense success-rate matrix, with support for multiple LLM providers (OpenAI, DashScope, OpenRouter) and offline listing of attacks and defenses.
chapter2/prompt-injection · high confidence
New staged system-prompt experiment with multi-stage agent behavior
Adds a new Chapter 10 experiment (\staged-system-prompt\) that demonstrates a single Coding Agent switching roles and toolsets across three explicit stages: Requirements Analysis, Code Implementation, and Code Review. The \StagedAgent\ implementation in \agent.py\ manages a state machine where the system prompt and available tools change at each stage (e.g., asking clarifying questions vs. writing code vs. running linters), while preserving conversation history across transitions. The demo (\demo.py\) supports running the full pipeline, starting from specific stages, or listing stage configurations offline. It includes a fallback configuration in \config.py\ to route requests through OpenRouter if the primary OpenAI key is missing or for specific models like \gpt-5.6-luna\. The project also provides a protocol definition (\experiment\_protocol.json\) and a runner (\run\_official\_experiment.py\) to execute and validate the experiment against real provider receipts, ensuring that stage transitions and review feedback loops are correctly recorded.
chapter10/staged-system-prompt · high confidence
New structured indexing experiment comparing RAPTOR and GraphRAG
Added a new Chapter 3 experiment that implements and compares two advanced document indexing approaches: RAPTOR (a hierarchical tree-based index using recursive summarization and GMM clustering) and GraphRAG (a graph-based index using entity/relation extraction and community detection). The change includes the core Python implementations (indexers, document processor, and configuration), a FastAPI service for building and querying these indexes, a CLI tool for running offline demos and full campaigns, and comprehensive bilingual documentation. This allows users to evaluate how hierarchical abstractions and knowledge graphs handle complex technical documentation compared to flat retrieval.
chapter3/structured-index · high confidence
New utility scripts for site assembly, i18n validation, and MkDocs hooks
The repository now includes a suite of Python and Bash scripts to build, validate, and enhance the online documentation site. \build\_site.sh\ assembles the MkDocs documentation directory, promoting chapter files for navigation and rewriting relative links for translated editions. \check\_i18n\_consistency.py\ enforces structural integrity across all language editions by verifying that chapter counts, project lists, and git clone commands match the Chinese baseline. Several MkDocs hooks improve the user experience: \mkdocs\_figure\_captions.py\ adds visible captions to standalone images, \mkdocs\_pandoc\_strip.py\ removes unsupported Pandoc attributes, \seo\_meta.py\ injects Open Graph and Twitter Card tags for rich social sharing, and \site\_edit\_urls.py\ fixes 404s on 'edit this page' buttons by mapping generated paths to source files. Additional scripts handle performance and data: \split\_search\_index.py\ divides the large search index by edition to reduce download sizes, \gen\_star\_history.py\ generates star history charts via GitHub GraphQL, \gen\_og\_card.py\ creates social share images, \homepage\_index.py\ generates chapter cards from manuscripts, \clean\_site\_files.py\ filters out unnecessary assets, and \git\_revision\_dates.py\ ensures accurate revision dates for generated files.
scripts · high confidence
Perception Tools MCP server introduced with 18+ tools and zero-API-key defaults
A new perception-tools MCP server is added to chapter 4, providing a unified CLI and stdio-based server that exposes tools across five categories: search (web, knowledge base, file download), multimodal understanding (webpage, document, image, video, audio), filesystem operations, public data sources (weather, stocks, crypto, currency, location, POI, Wikipedia, ArXiv, Wayback), and private data sources (Google Calendar, Notion). The server ships with a comprehensive documentation suite (README, SETUP, ARCHITECTURE, TOOL\_REFERENCE, INDEX, QUICK\_START, CHANGES, PROJECT\_SUMMARY), a Dockerfile for containerized deployment, and a .gitignore that preserves experiment evidence. By default, it uses free, open APIs (DuckDuckGo, Open-Meteo, CoinGecko, Nominatim, Overpass, Yahoo Finance, ExchangeRate-API, Wikipedia, ArXiv, Wayback) so no API keys are required for core functionality; optional keys enable enhanced search (Google Custom Search), vision analysis (OpenAI/OpenRouter), and private integrations (Notion, Google Calendar).
chapter4/perception-tools · high confidence
Repository restructured for v2.0 with EPUB support and Apache 2.0 license
The repository has been reorganized to support version 2.0 of the book, which restructures chapters (e.g., merging previous chapters 4 and 9 into a new chapter 6 on interaction). A new EPUB build pipeline has been added via \build\_epub.sh\ and \EPUB.md\, allowing users to generate EPUB editions for 15 languages. The project license has been updated to Apache 2.0, and the README files have been restructured to reflect the new chapter layout, language availability, and local build instructions.
(repo-wide) · high confidence
Reproduces Stanford Generative Agents with modern LLMs and ablation arms
This location introduces the full runtime and analysis infrastructure for Experiment 10-5, pinning the upstream \joonspk-research/generative\_agents\ source to commit \fe05a71d3e4ed7d10bf68aa4eda6dd995ec070f4\ and replacing its obsolete GPT-3 API calls with current OpenAI-compatible endpoints (defaulting to DashScope's \qwen3.7-flash\ and \text-embedding-v4\). The setup runs three 17,280-step (two-virtual-day) arms—baseline, custom\_goal, and no\_reflection—using a shared 25-persona history seed, while \action\_arena\_compat.py\ patches legacy prompt-response parsing to prevent crashes on malformed model output. Users can launch, monitor, and analyze these simulations via \launch\_campaigns.py\, \monitor\_campaign.py\, and \analyze\_campaign.py\, with \judge\_plausibility.py\ providing blind, arm-blind Anthropic judgments to evaluate behavioral plausibility across the ablations.
chapter10/generative-agents · high confidence
Spanish edition of the book is now available
The Spanish (Español) translation of the book is now available, including all chapters, the afterword, glossary, and reference answers. A build script is provided to generate the PDF.
book-es · high confidence
Turkish translation of the book is added
The Turkish edition of the book is now available, including all chapters, the afterword, and a PDF build script.
book-tr · high confidence
User Memory System now supports multiple LLM providers with OpenRouter fallback
The User Memory System in chapter3/user-memory has been updated to support multiple LLM providers, including Kimi/Moonshot (default), Alibaba Cloud DashScope (Qwen), SiliconFlow, Doubao, and OpenRouter. Users can now select their preferred provider via the \--provider\ CLI flag or the \PROVIDER\ environment variable, and configure specific models using \--model\ or \MODEL\_NAME\. A universal OpenRouter fallback is also implemented: if the primary provider's API key is missing but \OPENROUTER\_API\_KEY\ is set, the system automatically routes requests through OpenRouter, mapping provider-native model names to supported OpenRouter model IDs (e.g., \gpt-5\, \gemini-3.5-flash\, \claude-sonnet-4\). This change is reflected in the new \PROVIDERS.md\ documentation, updated \config.py\ with provider-specific base URLs and default models, and modifications to \agent.py\ and \conversational\_agent.py\ to handle multi-provider client initialization and API key resolution.
chapter3/user-memory · high confidence
Removals
Removal of Kimi-based Web Search Agent
The Kimi Web Search Agent implementation in the \week1/web-search-agent\ directory has been removed. This deletes the core agent logic (\agent.py\), the main entry point (\main.py\), configuration files (\config.py\, \env.example\), and documentation (\README.md\) that previously enabled users to perform web searches using the Kimi (Moonshot AI) API. Users can no longer run this specific agent to query real-time information via the Kimi model.
week1 · high confidence
Behavioural changes
Added missing experiment evidence and protocols for Chapter 2 runs
This change adds the missing experiment protocol and evidence files for Chapter 2 experiments 2-2 and 2-7, ensuring that the run artifacts for the Qwen3-0.6B model are complete and reproducible. Specifically, it includes the full run data for experiment 2-2 (testing attention on simple and reasoning prompts) across three versions, and the comparison data for experiment 2-7 (testing the impact of a status bar on tool-use refusal).
_chapter2/attention\visualization/runs · high confidence
Agentic RAG experiment updated with modern models, OpenRouter fallback, and chunking fixes
The Agentic RAG experiment in chapter3/agentic-rag has been updated to use current model versions (Kimi K3 and GPT-5.6-luna) and now supports a universal OpenRouter fallback when primary provider keys are missing. The chunking logic was fixed to preserve trailing sentence fragments and ensure chunk steps remain at least 1, while bare except clauses and missing load\_dotenv() calls were corrected across the codebase. The README and configuration files were synchronized to reflect these changes and provide bilingual instructions.
chapter3/agentic-rag · high confidence
Book updated to version 2.0 with new afterword and PDF build script
The book content has been updated to version 2.0, marked by a new afterword that synthesizes the core formula (Agent = LLM + Context + Tools) and discusses the co-evolution of models and harnesses. The PDF build script has been updated to generate a file named '深入理解-AI-Agent-李博杰-v2.0.pdf' and now explicitly includes the new afterword.md in the compilation sequence.
book · high confidence
Centralized provider registry with unified resolution and new provider support
The \agentbook/providers\ package now provides a single source of truth for LLM provider configuration, replacing scattered, per-experiment setup code with a shared registry. Users can now select from a broader set of supported providers (including Krill AI and Atlas Cloud) via a unified \resolve\_backend\ interface, which automatically handles credential resolution, base URL overrides, and model ID mapping. The system intelligently routes \gpt-5.x\ requests through OpenRouter to bypass direct API restrictions, while also supporting zero-cost local execution via Ollama or free OpenRouter models. A legacy shim ensures backward compatibility for existing chapter experiments during migration.
agentbook/providers · high confidence
Chapter 1 learning-from-experience experiment updated to Kimi K3 with OpenRouter fallback and bug fixes
The learning-from-experience experiment (comparing Q-learning and LLM in-context learning) now uses the Kimi K3 model instead of the discontinued Kimi K2, with GPT-5.6 as the default OpenRouter fallback. A universal OpenRouter fallback is added: if the Moonshot API key is missing but an OpenRouter key is set, the LLM agent automatically routes through OpenRouter. The LLM agent now honours the KIMI\_BASE\_URL environment variable for proxy/regional endpoint support. Several bugs are fixed: division-by-zero errors are prevented when evaluation windows or episode victories are empty, and the global random number generator is no longer reseeded on every episode reset to avoid repetitive episode patterns.
chapter1/learning-from-experience · high confidence
Chapter 1 search-codegen experiment now supports multi-provider Responses API with DashScope
The search-codegen experiment in Chapter 1 has been updated to support the OpenAI Responses API alongside Alibaba Model Studio (DashScope) as an eligible acceptance backend. The agent now uses the official \/v1/responses\ protocol with typed tool traces (\web\_search\_call\, \code\_interpreter\_call\) and URL citations, replacing previous proxy-based approaches. Configuration now includes DashScope-specific settings (model \qwen3.7-plus\, streaming requirements, native thinking) and OpenRouter as a diagnostic-only path. The experiment validates multi-round search and code execution, clarification before tool use, and model identity exactness. Tests verify citation extraction from both OpenAI and DashScope response formats, ASEAN capital distance calculations, and clarification flow validation.
chapter1/search-codegen · high confidence
Custom search index routing via template override
A new \overrides/main.html\ template has been added to inject a custom JavaScript file (\extras/search-index-router.js\) into the page configuration block. This script runs before the main bundle to enable dynamic routing of search index requests, supporting the per-book edition search index split.
overrides · high confidence
Introduce agentbook package for shared dependency management
The agentbook package has been added to centralize dependency declarations via the root pyproject.toml, allowing users to install specific chapter requirements (e.g., chapter 1 or chapter 7) using optional dependency groups instead of managing separate requirements.txt files. This package handles plumbing tasks such as provider resolution, environment loading, and trace printing, while keeping teaching code isolated within individual chapter directories.
agentbook · medium confidence
Introduce parallel tool execution and structured streaming support for local LLM agents
The local LLM serving experiment now executes independent tool calls concurrently using a thread pool, significantly reducing latency when multiple tools are triggered in a single turn. Additionally, the Ollama backend has been updated to correctly parse and stream structured thinking output (the \thinking\ field) and tool calls, ensuring that reasoning content and tool invocations are delivered as distinct, typed stream chunks rather than raw text tags.
_chapter2/local\_llm\serving · high confidence
KV Cache experiment now supports offline reporting and OpenRouter fallback
The KV Cache demonstration in chapter2/kv-cache now includes an offline comparison mode (via the \--report\ flag in main.py) that generates performance tables from previously saved JSON results without requiring an API key, and adds automatic fallback to OpenRouter when the primary Moonshot/Kimi API key is not configured. The default model has been updated to kimi-k2.6, and the sliding window mode now correctly preserves tool-call pairs to avoid breaking cache continuity.
chapter2/kv-cache · high confidence
Replace language tabs with a dropdown selector in the header
The site header now uses a dropdown menu for language switching instead of the previous tab bar. This change is implemented via a new \overrides/partials/header.html\ file that injects the dropdown between the search and repository source links. The dropdown is populated using \window.LANG\_CONFIG\ exposed from the site configuration, and it also exposes \window.AUTO\_TRANSLATE\_CONFIG\ to support optional machine-translation fallbacks for unbuilt languages.
overrides/partials · high confidence
Retains Experiment 10-3 TalkAct reproduction with Anthropic caller validation
The chapter10/talkact-reproduction area now includes a complete, validated reproduction of Experiment 10-3, comparing a fixed-topology duplex agent setup (fast claude-haiku-4-5 and slow claude-opus-4-8) against a single-model strawman control. Because the original Gemini caller credentials were invalid, the campaign used an Anthropic caller (claude-sonnet-4-5-20250929) and this deviation is explicitly documented and validated. The included validate\_campaign.py script and acceptance.json confirm that all 16 episodes (4 tasks × 2 conditions × 2 seeds) ran successfully, preserving detailed latency, token usage, and transcript data for users to analyze the trade-offs between response speed and total task time.
chapter10/talkact-reproduction · high confidence
System-Hint agent upgrades default model to Kimi K3 and adds offline status-bar preview
The System-Hint agent in chapter2/system-hint now defaults to the \kimi-k3\ reasoning model (replacing the retired \kimi-k2\ preview line) and handles its \reasoning\_content\ field correctly by forcing \temperature=1\ and replaying assistant turns with \model\_dump()\. It also introduces an offline \--mode preview\ CLI option that renders all five status-bar techniques (timestamps, tool counters, TODO lists, detailed errors, and system state) as before/after comparisons without making any LLM calls, while retaining the existing fallback to OpenRouter when no Kimi API key is set.
chapter2/system-hint · high confidence
Validation suite for voice-based Werewolf multi-agent campaigns
The validation directory now contains a comprehensive set of acceptance reports, game logs, and audit traces for the Chapter 10 voice-based Werewolf agent system. These files document the results of experiments (primarily experiment 10-6) that test the system's core behaviors, including information isolation between roles (e.g., wolves, seers, villagers), real-time speech-to-text (ASR) and text-to-speech (TTS) integration, and LLM-driven strategy. The reports cover various execution modes, from offline all-AI diagnostics to simulated user runs using providers like OpenRouter and Volcengine ARK, capturing detailed metrics on game cycles, role consistency, and safety gates to verify the system's functionality and compliance.
chapter10/voice-werewolf/validation · high confidence
Voice Werewolf experiment introduces real-LLM user simulator and hardened acceptance gates
The voice-werewolf demo now supports an automated user path via the \--simulate-user\ flag, where an independent real LLM calls game tools (speak, vote) and the output is synthesized to audio and transcribed back via ASR, with strict mismatch detection that fails closed if the ASR transcript does not match the tool selection. The game logic has been hardened to prevent a witch killed by wolves from using poison in the same night and to correctly report an UNDECIDED result when all players die simultaneously. Additionally, the experiment enforces stricter post-game strategy acceptance gates that require specific evidence for each of the four criteria (werewolf concealment, seer timing, villager reasoning, role consistency) rather than accepting a generic pass, and adds independent validation scripts to verify the audio/action boundary and information isolation.
chapter10/voice-werewolf · high confidence
Web search agent upgraded to Kimi K3 with OpenRouter fallback and increased timeout
The web-search-agent now defaults to the Kimi K3 model (replacing the discontinued Kimi K2) and increases the default search timeout from 30 to 180 seconds to accommodate K3's reasoning latency. It also introduces a generic OpenRouter fallback: if the primary Moonshot API key is missing, requests automatically route to OpenRouter (mapping kimi-k3 to moonshotai/kimi-k2.6), though the built-in web\_search tool is unavailable in this mode. The agent now distinguishes between rate-limit and timeout errors in failure messages, handles JSON parsing errors in tool arguments, and applies truncation to long trace steps.
chapter1/web-search-agent · high confidence
Fixes
Introduce coding-agent tools module with robust file, shell, and notebook operations
The \chapter5/coding-agent/tools\ package now provides a complete set of tool implementations for the coding agent, including Bash, Read, Write, Edit, MultiEdit, Grep, Glob, LS, NotebookEdit, and BashOutput. This release fixes several behavioral issues: the Bash tool now supports sub-second timeouts and treats timeout values of 0 or null as omitting the timeout; the BashOutput tool correctly returns only new output since the last check; the NotebookEdit tool preserves newlines when writing cell source; the Grep tool clamps negative context counts to zero, treats negative head limits as unlimited, and honors head\_limit=0 as zero results; the Read tool treats negative limits as reading to EOF and no longer reports non-empty files as empty when the limit is 0; the Edit and MultiEdit tools reject empty old\_string on existing files and ensure MultiEdit creates are atomic; and the Bash tool now supports shell commands on Windows via PowerShell or cmd.
chapter5/coding-agent/tools · high confidence
Test coverage
Added regression and basic tests for learning experiment components; Added test suite for the Chapter 1 web search agent; Added tests for core object store and application scenarios; Added tests for the tier-3 machine translation feature; Comprehensive test suite for Coding Agent tools; Expanded test coverage for Chapter 10 modules and site asset cleanup.
Dependencies
Explicit dependency manifests added for all chapter experiments
Every experiment directory across chapters 1 through 10 now includes a dedicated \requirements.txt\ (Python) or \package.json\/\package-lock.json\ (Node.js) file. This change replaces implicit or shared dependency resolution with explicit, per-experiment lockfiles, ensuring that each experiment installs only the specific libraries and versions it requires (such as \openai\, \playwright\, \mcp\, and \mem0ai\) and can be reproduced in isolation.
(dependencies) · high confidence
Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
How this codebase got here
Score
- CAI 32 → 32 (-0.2)
- Rubric changed (rubric-2026.11.1 → rubric-2026.11.4) — scores are not directly comparable.
Lenses
- Code Health 42 → 40 (-1.5)
- Architecture 97 → 97 (+0.1)
- Maturity 74 → 68 (-6.4)
- Readiness 14 → 15 (+0.4)
- Security 64 → 63 (-0.6)
- Domain Modelling 100 → 100 (+0.0)
- Accessibility 38 → 38 (-0.0)
- Performance 60 → 60 (+0.0)
Resolved (207)
- Duplicated block (10 lines × 2) (chapter10/voice-werewolf/werewolf/game.py)
- Duplicated block (10 lines × 2) (chapter3/agentic-rag-for-user-memory/main.py)
- Duplicated block (11 lines × 2) (chapter2/prompt-injection/demo.py)
- Duplicated block (11 lines × 2) (chapter6/astra-async-steering/experiment.py)
- Duplicated block (12 lines × 2) (chapter5/permission-embedded-data-objects/pedo/eval/case_studies.py)
- Duplicated block (12 lines × 6) (book-ar/svg_lib.py)
- Duplicated block (12–14 lines × 6) (chapter4/perception-tools/src/document_processing_tools.py)
- Duplicated block (13 lines × 2) (chapter3/agentic-rag-for-user-memory/evaluator.py)
- Duplicated block (14 lines × 2) (chapter1/context/main.py)
- Duplicated block (14 lines × 4) (chapter3/agentic-rag/quickstart.py)
- Duplicated block (14–19 lines × 2) (chapter5/code-for-math/demo.py)
- Duplicated block (15 lines × 2) (chapter10/book-translation/consistency_auditor.py)
- Duplicated block (15–16 lines × 2) (chapter2/system-hint/main.py)
- Duplicated block (16 lines × 2) (chapter4/perception-tools/src/search_tools.py)
- Duplicated block (16 lines × 3) (chapter4/perception-tools/src/filesystem_tools.py)
- Duplicated block (16 lines × 4) (chapter4/perception-tools/src/document_processing_tools.py)
- Duplicated block (17 lines × 3) (chapter3/agentic-rag/quickstart.py)
- Duplicated block (18 lines × 2) (chapter3/mem0/quickstart.py)
- Duplicated block (19 lines × 6) (book-en/strip_titles.py)
- Duplicated block (19–20 lines × 2) (chapter4/perception-tools/src/yahoo_finance_tools.py)
- …and 187 more
New (233)
- Critical CVE: [GHSA redacted] (chapter8/prompt-distillation/requirements.txt)
- Duplicated block (27 lines × 2) (chapter5/permission-embedded-data-objects/pedo/scenarios/banking.py)
- Duplicated block (34 lines × 6) (book-ar/svg_lib.py)
- Duplicated block (6 lines × 5) (chapter5/permission-embedded-data-objects/pedo/eval/benchmark_comparisons.py)
- Edited copies of one member (3 members, 1+ corresponding lines) (chapter8/curly-quote-sft/evaluate.py)
- Edited copies of one member (3 members, 1+ corresponding lines) (chapter8/curly-quote-sft/quality_audit.py)
- Edited copies of one member (3 members, 11+ corresponding lines) (chapter5/permission-embedded-data-objects/pedo/scenarios/ecommerce.py)
- Edited copies of one member (3 members, 12+ corresponding lines) (chapter3/dense-embedding/cli.py)
- Edited copies of one member (3 members, 12+ corresponding lines) (chapter5/permission-embedded-data-objects/pedo/eval/benchmark_safety_final.py)
- Edited copies of one member (3 members, 13+ corresponding lines) (chapter3/user-memory/memory_manager.py)
- Edited copies of one member (3 members, 13+ corresponding lines) (chapter8/MiniMind-pretrain/validation/run_training_report_audit.py)
- Edited copies of one member (3 members, 14+ corresponding lines) (chapter7/user-memory-system-evaluation/probe_candidates.py)
- Edited copies of one member (3 members, 15+ corresponding lines) (chapter10/autonomous-phone-registration/decision.py)
- Edited copies of one member (3 members, 15+ corresponding lines) (chapter5/permission-embedded-data-objects/pedo/eval/dataguardbench/harness.py)
- Edited copies of one member (3 members, 15+ corresponding lines) (chapter9/harness-safety-gate/evolution.py)
- Edited copies of one member (3 members, 17+ corresponding lines) (chapter5/permission-embedded-data-objects/pedo/eval/benchmark_harness_focused.py)
- Edited copies of one member (3 members, 18+ corresponding lines) (chapter3/contextual-retrieval-for-user-memory/advanced_memory_manager.py)
- Edited copies of one member (3 members, 19+ corresponding lines) (chapter5/permission-embedded-data-objects/pedo/eval/benchmark_overhead.py)
- Edited copies of one member (3 members, 2+ corresponding lines) (chapter4/active-tool-discovery/run_exact_experiment.py)
- Edited copies of one member (3 members, 2+ corresponding lines) (chapter6/robotics_lab_common.py)
- …and 213 more
Architecture
- Unchanged — 0 containers · 1 contexts · 0 edges
Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
Survey your own repository
bojieli/ai-agent-book was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.
About this page
- The score is its most recent published measurement, taken on 15 November 2026 at a pinned commit. It is not a live figure and does not change until the project is measured again.
- Measured at commit dbc046eb896ac4e39aa19c7774c8bf49583b89a6 — the exact code this score is about.
- Scored under rubric-2026.11.4 — the same rubric and the same method as every other entry in this index.
- Measured by Canine Code Analyzer (cca.canine.dev) using cca measure-2026.11.73+preprod-52de90b74216.