site_name: AI Agents in Depth
site_description: AI Agents in Depth — Design Principles and Engineering Practice. An open-source book covering AI Agents from theory to production, with 10 chapters and 94 companion experiments.
site_url: https://bojieli.github.io/ai-agent-book
repo_url: https://github.com/bojieli/ai-agent-book
repo_name: bojieli/ai-agent-book
edit_uri: edit/main
# The actual docs are assembled into `_web/` by `scripts/build_site.sh`
# (only the Markdown sources + images are copied; code/PDFs are left out).
docs_dir: _web
# Strip Pandoc/LaTeX attributes the source Markdown uses (e.g. `{.unnumbered}`,
# `{#sec:foo}`, image `{height=55%}`) which Python-Markdown cannot parse.
hooks:
- scripts/homepage_index.py
# `_web/` is an ignored staging tree, so map each staged page back to its
# tracked source before the revision-date plugin asks Git for timestamps.
- scripts/git_revision_dates.py
# `_web/` promotes book/chapterN.md to book/chapterN/index.md, a path that
# does not exist in the repository. Retarget the "edit this page" / "view
# source" buttons at the tracked source so they don't 404 (issue #1019).
- scripts/site_edit_urls.py
# Validates every configured language and generates the browser-side
# translation catalog from Material's locales + our book navigation labels.
- scripts/site_i18n.py
- scripts/mkdocs_pandoc_strip.py
# Wrap every standalone book figure in <figure>/<figcaption> so the label the
# author already wrote in the image alt text ("图0-2 …", "Figure 0-2: …")
# becomes a visible caption on the reading site. Works on the rendered HTML
# (on_page_content), which is what lets the experiment figures stay inside
# their `> ` blockquote box; the Pandoc strip above is a Markdown-stage hook,
# so it has always run by then whatever the order here. See the module
# docstring for why this is a build-time hook rather than a browser script.
- scripts/mkdocs_figure_captions.py
- scripts/seo_meta.py
# Splits the search plugin's single 55 MB search_index.json into one file
# per book edition. Runs last: MkDocs appends `hooks:` to the plugin list,
# so this sees the index the search plugin just wrote.
- scripts/split_search_index.py
theme:
name: material
language: zh
# Custom overrides: injects the language-tab switcher into the header.
custom_dir: overrides
logo: assets/logo.svg
favicon: assets/logo.svg
# Brand colours — indigo accent matches the book cover and SVG figures.
font:
text: Noto Sans SC, -apple-system, BlinkMacSystemFont, Helvetica, Arial, sans-serif
code: JetBrains Mono, SFMono-Regular, Consolas, monospace
icon:
logo: material/robot-outline
repo: fontawesome/brands/github
palette:
- media: "(prefers-color-scheme: light)"
scheme: default
primary: indigo
accent: indigo
toggle:
icon: material/weather-night
name: 切换夜间模式
- media: "(prefers-color-scheme: dark)"
scheme: slate
primary: indigo
accent: indigo
toggle:
icon: material/weather-sunny
name: 切换日间模式
features:
# ── Navigation ──────────────────────────────────────────────
# Two-sidebar layout: the left sidebar is the BOOK structure only
# (a clean chapter tree), the right sidebar is the CURRENT PAGE
# outline. Do NOT use navigation.tabs — that would cram all 10
# chapters into a horizontal bar. Do NOT use toc.integrate — it
# folds each chapter's ~40-heading outline into the left sidebar,
# burying chapters 3-10 below the fold.
- navigation.instant # SPA-like page swaps, no full reload
- navigation.instant.progress # show a loading bar on slow swaps
- navigation.tracking # URL changes with scroll
- navigation.sections # group nav entries into titled sections
# navigation.expand OFF — with it on, all chapter subtrees are force-
# expanded and can't be collapsed (clicking the title does nothing).
- navigation.indexes # chapter title = link to the chapter prose.
# Requires each chapter section's first child to be an index page;
# scripts/build_site.sh promotes book/chapterN.md to
# book/chapterN/index.md (the URL /book/chapterN/ is unchanged).
# The collapse chevron next to the title still toggles the subtree.
- navigation.top # "back to top" button
- navigation.footer # prev/next pager in footer
# ── Table of contents (right sidebar) ──────────────────────
- toc.follow # TOC tracks scroll position
# ── Content ─────────────────────────────────────────────────
- content.code.copy # copy button on code blocks
- content.code.annotate # rendered annotations in code
- content.action.edit # "edit this page" pencil
- content.action.view # "view source" link
- content.tooltips # rich hover tooltips
- content.tabs.link # sync same-named tabs across page
# ── Search ─────────────────────────────────────────────────
- search.suggest # autocomplete-style suggestions
- search.highlight # highlight matches in results
- search.share # shareable search URLs
plugins:
# Default Material plugins, made explicit so we can tune them.
- search:
lang:
- ja # CJK-aware tokenizer; far better for Chinese than `en`
- ko # Korean tokenizer for the Korean edition
- en
- ar
# Stamp each page with its git commit date — readers see "最后更新" trust signal.
- git-revision-date-localized:
enable_creation_date: true
enable_git_follow: false # avoids noisy "First revision older than last" warnings
type: date
fallback_to_build_date: true
# Auto-generate Open Graph / Twitter card images so links look rich when
# shared to WeChat / Twitter / Slack.
- social:
markdown_extensions:
- admonition
- attr_list
# Render the book's `[^label]` citations as superscript links with a
# collected reference list at the bottom of each page (issue #328).
- footnotes
- md_in_html
- toc:
permalink: true
# Default slugify drops CJK, so Chinese headings collapse to useless ids
# (`蒸馏：提升样本效率` -> `_1`). pymdownx's slugify keeps them and matches
# GitHub's anchors, so in-page section links work in both places.
slugify: !!python/object/apply:pymdownx.slugs.slugify
kwds:
case: lower
- pymdownx.arithmatex:
generic: true
- pymdownx.highlight:
anchor_linenums: true
- pymdownx.superfences:
# Render ```mermaid blocks as <div class="mermaid">…</div> so the
# mermaid.js runtime (loaded below in extra_javascript) picks them up.
# fence_div_format wraps raw content in a <div class="...">, which is
# exactly what mermaid.js expects. Any other fenced language still
# uses the default highlighted <pre><code>.
custom_fences:
- name: mermaid
class: mermaid
format: !!python/name:pymdownx.superfences.fence_div_format
- pymdownx.inlinehilite
- pymdownx.tabbed:
alternate_style: true
- pymdownx.details
extra_javascript:
# Generated into _web/ by scripts/site_i18n.py during each MkDocs build.
- extras/site-i18n.generated.js
- extras/lang-switcher.js
# Must load after lang-switcher.js: it appends to the menu the switcher
# builds, and relies on `window.langSwitcher` to map the current page to
# the English edition.
- extras/auto-translate.js
- extras/nav-collapse.js
- https://unpkg.com/mermaid@11/dist/mermaid.min.js
- extras/mermaid-init.js
# mathjax.js must load first: it sets the `window.MathJax` config that
# the MathJax bundle reads at startup (see the file header).
- extras/mathjax.js
- https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js
extra_css:
- extras/lang-switcher.css
- extras/auto-translate.css
- extras/book-theme.css
# Language definitions for the switcher tab bar.
# Each entry maps its prefix + suffix rules to rewrite URLs across editions.
extra:
languages:
# `prefix` and `suffix` apply to chapter prose (book*/chapterN[.suffix]/).
# `readmeSuffix` is the URL slug used for the per-language experiment
# index page (chapterN/README.<readmeSuffix>/), which mkdocs renders
# from the source file README.<suffix>.md.
zh: { label: 中文, prefix: book/, default: true }
zhtw: { label: 繁體中文（台灣）, prefix: book-zhtw/, suffix: .zhtw, readmeSuffix: zh-TW }
en: { label: English, prefix: book-en/, readmeSuffix: en }
es: { label: Español, prefix: book-es/, suffix: .es, readmeSuffix: es }
id: { label: Bahasa Indonesia, prefix: book-id/, readmeSuffix: id }
ru: { label: Русский, prefix: book-ru/, readmeSuffix: ru }
ta: { label: தமிழ், prefix: book-ta/, suffix: .ta, readmeSuffix: ta }
vi: { label: Tiếng Việt, prefix: book-vi/, suffix: .vi, readmeSuffix: vi }
ja: { label: 日本語, prefix: book-ja/, suffix: .ja, readmeSuffix: ja }
ko: { label: 한국어, prefix: book-ko/, suffix: .ko, readmeSuffix: ko }
ar: { label: العربية, prefix: book-ar/, suffix: .ar, readmeSuffix: ar }
tr: { label: Türkçe, prefix: book-tr/, suffix: .tr, readmeSuffix: tr }
hu: { label: Magyar, prefix: book-hu/, readmeSuffix: hu }
he: { label: עברית, prefix: book-he/, suffix: .he }
ptbr: { label: Português (Brasil), prefix: book-ptbr/, suffix: .ptbr }
# Tier 3 — languages the book has no edition for. Selecting one loads
# translate.js (MIT, https://github.com/xnx3/translate) on demand and
# machine-translates the English edition in the browser. See
# extras/auto-translate.js for why it is opt-in, lazy, and always labelled.
#
# This is explicitly a lesser tier than the 14 built editions: figures stay
# in English (they are <img> SVGs, unreachable from page scripts) and the
# text is unreviewed. Anything worth shipping properly should get a real
# edition instead.
auto_translate:
label: 机器翻译 / Machine translation
# The edition to translate *from*: MT out of English beats MT out of
# Chinese for most targets, and that edition is reviewed. `source` is the
# site language code; `sourceLanguage` is translate.js' name for it.
source: en
sourceLanguage: english
# Free, keyless channel. NOT `client.edge`: that channel authenticates
# against https://edge.microsoft.com/translate/auth, an undocumented Edge
# browser endpoint that now returns 404, so it fails for every visitor.
# `giteeAI` posts to giteeai.zvo.cn/translate.json (verified working,
# keyless) and fails over to two backup hosts on its own.
# Alternatives: `siliconflow`, or `translate.service` against a self-host.
service: giteeAI
# translate.js' MutationObserver (translate.listener.start) throws
# "Cannot read properties of null (reading 'nodeValue')" against Material's
# navigation.instant DOM swaps, and queues a redundant translation pass per
# mutation. We re-translate on Material's own `document$` instead, so it
# stays off unless you explicitly want it.
listener: false
# How long a translation pass may go without any sign of life before the
# notice tells the reader the service is not answering. It is a stall
# window, not a deadline: every batch that comes back restarts it, and a
# pass that lands after it expired still clears the warning. The states in
# between ("translating", "translated") come from translate.lifecycle.
failureTimeoutMs: 12000
# Pinned version + SRI hash: this is third-party code from a public CDN,
# so the exact bytes are fixed. Both must be updated together.
cdn: https://cdn.staticfile.net/translate.js/3.18.66/translate.js
integrity: sha384-J3fM1QvC/Px5E8QNZj9KjrYuADHneSN4vCpv//WZPKUVzJocwGpZO/byDiEjaPCL
# `name` is translate.js' v2 language name (note German is `deutsch`);
# `locale` becomes the <html lang> attribute.
languages:
- { name: french, label: Français, locale: fr }
- { name: deutsch, label: Deutsch, locale: de }
- { name: italian, label: Italiano, locale: it }
- { name: polish, label: Polski, locale: pl }
- { name: dutch, label: Nederlands, locale: nl }
- { name: ukrainian, label: Українська, locale: uk }
- { name: czech, label: Čeština, locale: cs }
- { name: romanian, label: Română, locale: ro }
- { name: greek, label: Ελληνικά, locale: el }
- { name: swedish, label: Svenska, locale: sv }
- { name: danish, label: Dansk, locale: da }
- { name: finnish, label: Suomi, locale: fi }
- { name: norwegian, label: Norsk, locale: "no" }
- { name: thai, label: ไทย, locale: th }
- { name: hindi, label: हिन्दी, locale: hi }
- { name: bengali, label: বাংলা, locale: bn }
- { name: malay, label: Bahasa Melayu, locale: ms }
- { name: filipino, label: Filipino, locale: fil }
- { name: swahili, label: Kiswahili, locale: sw }
- { name: urdu, label: اردو, locale: ur, dir: rtl }
- { name: persian, label: فارسی, locale: fa, dir: rtl }
nav:
# The left sidebar is a clean chapter tree. With navigation.indexes,
# each chapter's index page (book/chapterN/index.md, promoted from
# book/chapterN.md by scripts/build_site.sh) is attached to its section:
# clicking the chapter title opens the prose directly, and the chevron
# expands the subtree to reveal "配套实验" (the experiment index).
- 首页: index.md
- 引言: book/introduction.md
- 第1章 Agent基础知识:
- book/chapter1/index.md
- 配套实验: chapter1/README.md
- 第2章 上下文工程:
- book/chapter2/index.md
- 配套实验: chapter2/README.md
- 第3章 用户记忆和知识库:
- book/chapter3/index.md
- 配套实验: chapter3/README.md
- 第4章 工具:
- book/chapter4/index.md
- 配套实验: chapter4/README.md
- 第5章 CodingAgent与通用Agent:
- book/chapter5/index.md
- 配套实验: chapter5/README.md
- 第6章 交互：观察与动作空间的扩展:
- book/chapter6/index.md
- 配套实验: chapter6/README.md
- 第7章 Agent的评估:
- book/chapter7/index.md
- 配套实验: chapter7/README.md
- 第8章 模型后训练:
- book/chapter8/index.md
- 配套实验: chapter8/README.md
- 第9章 Agent的持续进化:
- book/chapter9/index.md
- 配套实验: chapter9/README.md
- 第10章 多Agent协作:
- book/chapter10/index.md
- 配套实验: chapter10/README.md
- 后记: book/afterword.md
- 思考题参考答案: book/reference-answers.md