A field manual for agents that have to survive production
Aliyun open-sources its enterprise agent playbook, on the theory that building agents is now the easy part — running them at scale inside core business is not.

What it does
This is a book, not a codebase: roughly 30 chapters of Markdown covering an agent’s full lifecycle — architecture, build, run, governance, optimization, and case studies — plus a 2026 agent developer survey report. It’s Aliyun’s rewrite of their September 2025 AI-native application architecture whitepaper, restructured around three challenges they say the market has moved to: turning probabilistic intelligence into reliable productivity, scaling from single experiments to infrastructure, and getting agents into core business processes instead of leaving them on islands. The stated purpose is reference material for tech selection, architecture review, and building cross-team consensus.
The interesting bit
Two ideas carry real weight. First, a “minimum sufficient architecture” principle: pick the least agent your task’s determinism and risk justify, not the most. Second, a sharp responsibility boundary between Model and Harness — the build chapters argue you shouldn’t blame the model for what is actually an engineering problem. The closing chapter gestures at an “Agentic OS,” which is either a thesis or a prophecy depending on your mood.
Key highlights
- Full lifecycle coverage: Harness construction (context, state, tools, MCP, A2A, human-in-the-loop), runtime (sandbox, async tasks, multi-agent orchestration, distributed communication), and governance (observability, prompt-injection defense, asset management, pre-launch simulation).
- An optimization loop built on Trace → Trajectory → golden datasets → badcase regression — a data flywheel rather than vibes.
- Case studies from real deployments: kernel patch testing, the Kitta code-review agent, PolarDB-X’s alert-to-auto-remediation loop, plus design, ops, and customer-operations practices.
- A role-based reading map telling developers, architects, managers, and security folks which chapters are theirs.
- Maintained openly, with an explicit invitation for community contribution.
Caveats
- No software here — it’s a whitepaper in Markdown form; don’t clone it expecting a framework.
- Chinese-first: the default README and chapter files are in Chinese; an English README (
README_EN.md) exists, but how much of the 30 chapters is translated isn’t clear from the front page. - Case studies lean on Alibaba-internal engineering, so expect one company’s practitioner view rather than a neutral survey of the field.
Verdict
Worth a bookmark if you’re moving agents from pilot to production and need shared vocabulary for architecture reviews and project approval. Skip it if you want runnable code or an English-only read.
Frequently asked
- What is aliyun/ai-agent-handbook?
- Aliyun open-sources its enterprise agent playbook, on the theory that building agents is now the easy part — running them at scale inside core business is not.
- Is ai-agent-handbook open source?
- Yes — aliyun/ai-agent-handbook is open source, released under the Apache-2.0 license.
- What language is ai-agent-handbook written in?
- aliyun/ai-agent-handbook is primarily written in JavaScript.
- How popular is ai-agent-handbook?
- aliyun/ai-agent-handbook has 3.5k stars on GitHub.
- Where can I find ai-agent-handbook?
- aliyun/ai-agent-handbook is on GitHub at https://github.com/aliyun/ai-agent-handbook.