Appearance
README
中文 | English
AI Agent HandBook
Following the agent lifecycle—from architecture and building to operation, governance, and optimization—we share the experience and lessons we have gained from deploying enterprise agents. If this white paper helps individuals learn or organizations put agents into practice, we would be deeply grateful.
We dedicate this project to everyone contributing to the development of AI.
1. Background and Structure
In September 2025, we published the AI-Native Application Architecture White Paper. It examined the full DevOps lifecycle of AI-native applications—from architecture and technology choices to engineering practice, operations, and optimization—breaking down key concepts and difficult problems while offering possible approaches. As models and agent technologies have advanced rapidly, however, attention has shifted from building agents quickly to three new challenges:
- Engineering: Turn probabilistic intelligence into reliable productivity so agents can take on critical tasks.
- Scaling: Address stability, security, performance, and cost as agents move from isolated experiments to intelligent infrastructure that can be deployed at scale.
- Organization: Move beyond isolated agents and bring them into core business processes as part of an intelligent organization.
Last year's white paper can no longer fully address these needs.
We have therefore reworked its structure. With more up-to-date content, a greater share devoted to real-world practice, and a more community-driven approach, we hope to support enterprise technology selection and internal project planning. By maintaining the white paper as an open-source project, we aim to keep sharing emerging thinking and practical experience in AI-native application architecture.
2. Audience and Takeaways
This white paper is primarily for teams building and deploying enterprise agents. It can also support technology selection, architecture reviews, project proposals, and a shared vocabulary across organizations.
| Reader | Recommended sections | What you will gain |
|---|---|---|
| Agent and AI application developers | Building, Runtime, Optimization | Engineering methods for harnesses, context, state, tools, sandboxes, trajectories, and evaluation. |
| Architects and platform engineers | Architecture, Runtime, Governance | An architecture spanning components, platform responsibilities, and the application lifecycle. |
| Technology and engineering leaders | Architecture, Governance, Practice | Criteria for application form, maturity, investment boundaries, and production risk. |
| Product and business leaders | Survey, Architecture, Practice | A way to identify suitable tasks, define human-agent responsibilities, and plan the path beyond pilots. |
| Security, quality, and operations teams | Runtime, Governance, Optimization | Approaches to observation, audit, authorization, release validation, evaluation, and root-cause analysis. |
| Researchers and ecosystem contributors | Entire white paper and Practice | First-hand enterprise problems, reusable abstractions, and open questions for further work. |
By the end, you should be able to:
- Choose the least complex agent architecture sufficient for the business goal, task uncertainty, and risk.
- Distinguish model limitations from harness and systems-engineering problems.
- Design tasks that can advance over time, recover from interruption, and finish based on verifiable evidence.
- Provide an execution environment, state, traffic management, permissions, observability, and cost controls.
- Build an improvement loop using traces, trajectories, golden datasets, and evaluation experiments.
- Apply these methods to software engineering, design, operations, enterprise IT, and customer-facing use cases.
3. Reading Guide
The linked chapters and case studies are currently written in Chinese; this English README is a guide to the existing content, not a translation of the entire white paper.
Repository structure
| Part | Directory | Chapters | Focus |
|---|---|---|---|
| 2026 Agent Developer Survey Report | Repository root | — | Enterprise development, production adoption, architecture choices, toolchains, governance, and evaluation. |
| Preface | 00-preface/ | — | The white paper's structure and background. |
| Architecture | 01-architecture/ | 1–2 | Define the system, select an application form, assess maturity, and establish a reference architecture. |
| Building | 02-build/ | 3–6 | Organize tasks, information, and actions around the harness. |
| Runtime | 03-run/ | 7–12 | From reliable single-agent execution to asynchronous and distributed multi-agent systems. |
| Governance | 04-governance/ | 13–16 | Make operations visible, behavior bounded, assets manageable, and release behavior testable. |
| Optimization | 05-optimization/ | 17–24 | Continuous improvement of both models and agents. |
| Practice | 06-case-study/ | 25–29 | Enterprise cases, domain applications, and agent-infrastructure exploration. |
| Conclusion and Outlook | 07-conclusion/ | 30 | From Agentic Application to Agentic OS. |
Chapter guide
| Part | Chapter | Main topics |
|---|---|---|
| Architecture | 1. A New Stage for AI-Native Applications | Application evolution, Agentic Application boundaries, and enterprise maturity. |
| Architecture | 2. Agentic Application Reference Architecture | Component, platform-responsibility, and lifecycle views. |
| Building | 3. Harness Construction Patterns and Responsibilities | Code-first frameworks, productized harnesses, managed agents, cloud products, and platform boundaries. |
| Building | 4. Tasks: Orchestration and Long-Horizon Collaboration | Agent loops, task state machines, planning, delegation, asynchronous continuation, and completion evidence. |
| Building | 5. Information: Context, State, and Reusable Assets | Context builders, compression, sessions, task state, workspaces, memory, knowledge, and skills. |
| Building | 6. Actions: Controlled Execution and Verification | Action planes, Function Calling, MCP, A2A, environment contracts, permissions, and human approval. |
| Runtime | 7. Agent Runtime and Sandboxes | Sandboxes, runtime, workspaces, environment lifecycle, and production execution. |
| Runtime | 8. Agent State Storage and Semantic Assets | Event logs, checkpoints, snapshots, artifacts, long-term memory, RAG, and business semantics. |
| Runtime | 9. AI Gateways and Unified Traffic Governance | Identity, permissions, budgets, routing, audit, and approval across LLM, MCP, and agent traffic. |
| Runtime | 10. Asynchronous Agent Tasks and Automation | Synchronous/asynchronous boundaries, completion semantics, scheduled work, and workflows. |
| Runtime | 11. Multi-Agent Coordination and Orchestration | Heterogeneous agents, team topology, task assignment, result aggregation, and orchestration roles. |
| Runtime | 12. Distributed Agent Communication | Protocol choices and message governance across capability, collaboration, internal, and human-agent interactions. |
| Governance | 13. Agent Observability | Metrics, logs, traces, events, cost attribution, and audit. |
| Governance | 14. Agent Security | Prompt injection, identity, per-action validation, high-risk authorization, and data-egress controls. |
| Governance | 15. Discovery and Management of AI Assets | Registration, versioning, discovery, dependencies, and releases for prompts, skills, MCP, and agents. |
| Governance | 16. Agent Behavior Generation and Quality Validation | User and environment simulation, scenarios, and pre-release validation. |
| Optimization | 17. Model Tuning | Root-cause criteria, SFT, agentic RL, distillation, and production acceptance. |
| Optimization | 18. Overview of Agent Optimization | Optimization targets, method boundaries, and the data flywheel. |
| Optimization | 19. Agent Trajectory Data | Turning traces into reusable behavioral and decision evidence. |
| Optimization | 20. Processing Agent Runtime Data | Collection, cleaning, processing, and declarative data pipelines. |
| Optimization | 21. Golden Datasets for Agents | Evaluation assets with inputs, trajectories, outcomes, and judging criteria. |
| Optimization | 22. Improving Agents Through Bad Cases | Failure discovery, attribution, fixes, regression checks, and experiments. |
| Optimization | 23. Controlled Self-Evolution | Turning validated experience into memory, skills, tools, and runtime improvements. |
| Optimization | 24. Edge Runtime and Global Optimization | Edge runtime, evaluation, performance, cost, delivery, security, and simulation. |
| Practice | 25. Software Engineering Productivity | Code review, defect detection, patch delivery, and end-to-end engineering. |
| Practice | 26. Design Engineering | Vibe Designing and GenUI. |
| Practice | 27. Operations, Security, and Enterprise IT | Production operations in automotive, retail, and enterprise software. |
| Practice | 28. Customer, Sales, and Operations | Long-term memory, content insights, office productivity, and data agents. |
| Practice | 29. GOAI Agent Infra: Frontiers in Multi-Agent Collaboration | Open-source competition projects and agent-infrastructure exploration. |
| Conclusion and Outlook | 30. From Agentic Application to Agentic OS | From individual applications toward collaborative, governable, evolving systems. |
Case-study guide
Suggested reading paths
- New to enterprise agents: Survey → Chapters 1–2 → Chapters 3–6 → Chapters 13–16.
- Moving an agent into production: Chapters 7–9 → Chapters 13–14 → Chapters 18–23.
- Building a multi-agent system: Chapters 4–6 → Chapters 10–12 → Chapters 13 and 16.
- Responsible for evaluation and optimization: Chapter 13 → Chapters 18–23 → relevant case studies.
- Responsible for selection or project approval: Survey → Chapters 1–3 → Practice → Chapter 30.
4. Roadmap
This white paper is an open, evolving project rather than a document frozen after its first release. Planned work includes:
- More enterprise cases: Add first-hand examples from engineering, operations, customer service, data, security, finance, and industry-specific workflows, including trade-offs and failure modes.
- Hands-on cloud experiences: Create reproducible online exercises for sandboxes, runtimes, AI gateways, state storage, observability, and evaluation.
- Deeper governance coverage: Track enterprise needs in identity, prompt-injection defense, data egress, audit, asset registration, versioning, and pre-release simulation.
- Stronger evaluation methods: Expand coverage of task success rates, trajectory evaluation, LLM-as-Judge, golden datasets, bad-case regression, online experiments, and quality–cost trade-offs.
- Ongoing technical updates: Revisit conclusions as models, harnesses, protocols, runtimes, multi-agent systems, and Agentic OS evolve.
- Community collaboration: Improve content guidelines, case templates, terminology, review processes, and release practices.
Contributing
Developers, architects, researchers, enterprise teams, and product practitioners are welcome to contribute. You can open an Issue to report an error or suggest a topic; submit a Pull Request to improve a chapter, figure, or reference; share a sanitized case study or postmortem; or contribute reproducible code, cloud exercises, datasets, and experiments.
Please respect authorship and permission boundaries. Remove or obtain authorization for enterprise data, customer information, internal-system details, and security-sensitive material before contributing.
5. Contributors
Thanks to everyone who has helped with architecture, writing, case studies, and review.
Alibaba Cloud
| Contribution area | Contributors |
|---|---|
| Preface | 麻芃 |
| Developer Survey Report | 任娟, 王晨 |
| Architecture | 王晨, 刘军, 沈林 |
| Building | 刘军, 泮圣伟, 王晨 |
| Runtime | 赵庆杰, 李诗波, 林清山, 黄晓萌, 张添翼, 赵源筱, 孙校, 宋震, 胡庆达, 柳遵飞, 朱桐, 余华峰, 罗鑫, 孔可青 |
| Governance | 肖长军, 周洋, 张磊, 王方, 张海彬, 程书意, 刘子明, 饶子昊, 任懿, 杨永, 王硕, 马昕, 刘宇轩, 杨翊 |
| Optimization | 张寒萌, 李盛荣, 王亚宁, 孙坚运, 马云雷, 王桢, 郑前祎, 刘航, 陈新 |
| Practice | 杨涛, 朱颜, 余艾琳, 胡峻 |
| Conclusion and Outlook | 林演 |
External Contributors
The project remains open to community contributions. Developers, architects, researchers, enterprise technology teams, and product practitioners are welcome to collaborate through Issues and Pull Requests. Accepted contributors will be acknowledged in this section.
If this white paper helps you better understand, build, operate, govern, and optimize agents, please share it, discuss it, and help improve it.