AI Agent Handbook

中文 | English

Organized around the Agent application lifecycle (architecture, building, operations, governance, and optimization), this open-source project gathers practical experience, lessons learned, and insights from Alibaba Cloud, enterprise customers on the cloud, and developers in the open-source community as they bring enterprise-grade Agents into production. We add the latest practices every week and revise published content from time to time. We'd be honored if this project helps, even a little, with your own learning or your company's Agent rollout.

We dedicate this project to everyone contributing to the development of AI.

Read online

Play the online challenges — we've designed a few mini-games. How high can you score?

We welcome universities and other educational institutions to co-build an enterprise-grade Agent curriculum with us. If you are interested, please reach out on WeChat (max_0928) and mention "curriculum co-building" in your friend request.

---

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.
Putting Intelligence to Work: From Creating Intelligence to Using It Well	00-preface/	—	From intelligent capabilities to reliable delivery through multimodality, full-stack systems, and harness engineering.
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, Jev topic, Personal Agent topic, and FDE topic	Enterprise cases, domain applications, agent infrastructure, structured decisions, Personal Agent observations, and FDE engineering practices.
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, production acceptance, and inference framework basics.
Optimization	18. Agent Optimization: Overview and Practice	Optimization targets, method boundaries, and the data flywheel, plus a first-hand account of selecting and onboarding a flywheel platform.
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 enterprise agents for retail stores.
Practice	29. GOAI Agent Infra: Frontiers in Multi-Agent Collaboration	Open-source competition projects and agent-infrastructure exploration.
Practice	Jev: Structured Decision Making	Model concepts, routing practices, API examples, and decision making throughout the harness lifecycle.
Practice	Personal Agent	Product approaches, technical challenges, business models, and Agent as a Service architecture.
Practice	FDE	End-to-end AI coding delivery, spec-driven development, and engineering practices in enterprise projects.
Conclusion and Outlook	30. From Agentic Application to Agentic OS	From individual applications toward collaborative, governable, evolving systems.

Case-study guide

Chapter	Case study
25. Software engineering	Agent: Targeted Testing and Defect Detection for Kernel Patches
25. Software engineering	Agent: Enhancing Code Review in Practice
25. Software engineering	Agent: Improving Kernel Patch Delivery Efficiency
25. Software engineering	Agent: Evaluation and Tuning for Operations
25. Software engineering	Organizational Collaboration: Restructuring Behind the Self-Evolution of Agentic SOC Security Products
25. Software engineering	Organizational Collaboration: End-to-End Database Operations, from Alerts to Automatic Repair
25. Software engineering	Organizational Collaboration: End-to-End Engineering Delivery in Cloud Communications
25. Software engineering	Organizational Collaboration: Building a Multi-Agent Engineering Team to Improve Delivery Efficiency
26. Design engineering	GenUI: From Answers to Deliverables
26. Design engineering	Vibe Designing: An Intent-Driven AI Design Paradigm
27. Operations and IT	Geely's Intelligent Operations Practice
27. Operations and IT	Tastien's Intelligent Operations Loop Across 10,000 Stores
27. Operations and IT	ChangJieTong's Observability and Intelligent Operations
28. Customer and operations	MiniMax's Long-Horizon Memory Data Foundation
28. Customer and operations	Office Productivity at ShineWing, an Accounting Firm
28. Customer and operations	Bilibili's Cross-Platform Content Insights
28. Customer and operations	Scaling Enterprise Agents at Topsports
Jev topic	Overview: Understanding Jev and Fast Structured Decisions
Jev topic	Development Framework: Teaching Agents to Decide, from Jev Integration to a Complete Harness Decision Workflow
Jev topic	Building a Ticket Triage Assistant with a Jev-Style Decision Model
Jev topic	Intelligent Model Routing with Jev
Personal Agent topic	Personal Agent: Product, Technology, and Business Observations
Personal Agent topic	From Personal Agents to Enterprise Agents: AgentScope's Agent as a Service Architecture
FDE topic	Enterprise FDE Engineering Practices Across the AI Coding Lifecycle

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.