ADK框架：无需画图，用代码高效构建智能体（Agent）

1. 项目概述：当“画图”不再是Agent开发的唯一路径

最近在跟几个刚入行Agent开发的朋友聊天，发现一个挺有意思的现象：一提到搭建一个智能体（Agent），大家脑子里蹦出来的第一反应就是画流程图。无论是用LangChain、AutoGen这类框架，还是自己手撸状态机，似乎“用节点和连线定义工作流”成了Agent开发的标配动作。这当然没错，图形化编排直观、易于理解，尤其对于复杂业务流程的梳理，优势明显。但这也无形中给很多开发者，特别是那些更习惯用代码思考、或者项目需要快速迭代验证的朋友，筑起了一道心理和操作上的门槛——难道不精通某个可视化工具，就玩不转Agent了？

直到我深度体验了ADK（Agent Development Kit），这个观念被彻底刷新了。ADK提出的核心理念，恰恰是“不写图，也能搭Agent”。它并不是要取代图形化工具，而是提供了另一条截然不同、且在某些场景下效率更高的路径：通过纯代码、声明式的配置，甚至是自然语言描述，来快速构建和迭代你的智能体。这就像给你一把瑞士军刀，除了常规的剪刀（流程图），它还提供了开瓶器（代码）、螺丝刀（配置）等多种工具，让你能根据手头的任务，选择最趁手的那一个。

那么，ADK到底是什么？简单说，它是一个旨在降低Agent开发门槛、提升开发体验的工具包或框架。它关注的核心不是提供一个庞大的、无所不包的“超级框架”，而是解决Agent开发中的几个关键痛点：环境隔离、技能（Skill）管理、运行控制以及记忆（Memory）处理。当你不再需要为“我的Agent代码和依赖会不会污染主环境”、“这个工具函数怎么优雅地封装成Agent可调用的技能”、“多个Agent之间怎么传递状态和记忆”这些问题头疼时，你就能更专注于Agent本身的逻辑设计。结合网络上的热门讨论，无论是探索Hermes Agent的安装，还是研究多Agent协作，抑或是纠结于如何为本地模型（如Ollama）赋予Agent能力，ADK都提供了一套务实、可落地的解决思路。

这篇文章，我就以一个一线开发者的视角，带你抛开复杂的流程图工具，直接上手ADK，看看如何用最“程序员友好”的方式，从零搭建一个具备实用技能的Agent。我们会涉及环境准备、核心概念、代码实操、问题排查以及我踩过的一些坑。无论你是想快速验证一个AI点子，还是希望将Agent能力集成到现有系统，这篇内容都能给你提供一条清晰的路径。

2. ADK核心设计理念与优势解析

在深入代码之前，我们有必要先厘清ADK的设计哲学。它之所以敢说“不写图也能搭”，是因为它从根本上重新思考了Agent的构成单元和组装方式。

2.1 从“编排”到“组装”的思维转变

传统基于流程图的Agent开发，思维模式是“编排”（Orchestration）。你需要预先设计好整个工作流：从哪里开始，经过哪些判断节点，调用哪些工具，最终到哪里结束。这就像导演一部电影，需要事先写好分镜脚本（流程图）。这种方式适合流程固定、边界清晰的场景。

而ADK倡导的是一种“组装”（Assembly）思维。它将Agent视为一个由核心引擎（Runner）、可插拔技能（Skills）、持久化记忆（Memory）和交互界面（Interface）构成的复合体。你的工作不是绘制完整的路线图，而是准备好高质量的“零部件”（Skills），并定义一个清晰的“决策引擎”（通常是基于大语言模型的推理逻辑），然后让它们自行协作。这更像是组建一个特种作战小队：你为每个队员（Skill）配备好专业技能和装备，明确指挥官（核心逻辑）的决策原则，然后下达任务目标，具体的战术动作由小队内部协同完成。这种方式对开放域、动态性强的任务更加灵活。

2.2 ADK的核心组件拆解

基于“组装”思维，ADK通常包含以下几个关键部分，理解它们是你顺利上手的基础：

1. Runner（运行器）：这是Agent的“心脏”和“调度中心”。它负责生命周期管理（启动、运行、停止）、技能的路由与调用、记忆的存取、以及与外部大模型（如OpenAI API、本地Ollama服务）的通信。一个健壮的Runner能有效隔离故障，确保一个技能的崩溃不会导致整个Agent宕机。在搜索热词中频繁出现的“Runner failed”等问题，其根源往往在于Runner的配置或环境依赖上。

2. Skill（技能）：这是Agent的“手脚”和“专业工具”。一个Skill就是一个独立的功能单元，它可以是一个简单的计算器函数，一个查询数据库的模块，也可以是调用一个复杂API的服务。ADK强调技能的“可插拔性”和“标准化”。好的Skill应该职责单一、接口清晰、自带依赖描述（比如需要哪些Python包）。这样，你可以像搭积木一样，将不同的Skill组合到不同的Agent中。

3. Memory（记忆）：这是Agent的“笔记本”和“经验库”。记忆使Agent能够跨对话轮次保持上下文，学习用户偏好，甚至积累历史经验。ADK通常会提供多种记忆后端，如临时的会话记忆、持久化的向量数据库（用于语义搜索记忆片段）、甚至传统数据库。热词中提到的“Agent记忆”是评价一个Agent是否“智能”的关键维度。

4. Development Kit（开发工具包）：这部分是提升开发效率的关键，包括项目脚手架生成、技能创建模板、本地测试工具、打包部署脚本等。它把那些重复性的工程化工作标准化，让你能聚焦于业务逻辑。

2.3 为何选择“不画图”的开发方式？

相比于图形化，纯代码/配置驱动的方式有几点独特优势：

• 版本控制友好：所有的逻辑都以代码（.py, .yaml, .json）的形式存在，可以完美地用Git进行版本管理、代码审查和协作。你可以清晰地看到每次迭代具体修改了哪一行代码，而不用去对比两张复杂的流程图图片。
• 易于调试和测试：你可以用熟悉的单元测试框架（如pytest）对每个Skill进行独立测试。可以通过日志、断点等方式深入追踪Agent的内部状态和决策过程。这对于排查复杂问题至关重要。
• 更适合复杂逻辑：当Agent的判断逻辑非常复杂，涉及多层条件嵌套、动态循环或复杂数据结构处理时，用代码表达往往比用图形连线更简洁、更精确，可读性也更高。
• 便于集成与自动化：代码化的Agent可以轻松地被CI/CD管道调用，可以封装成Web API、命令行工具或库，无缝集成到现有的软件系统中。这对于生产环境部署至关重要。
• 降低学习成本：对于开发者而言，学习一套新框架的API，比学习一个复杂的可视化工具的操作界面，通常成本更低，也更容易形成肌肉记忆。

当然，这并非全盘否定可视化。在项目初期进行头脑风暴、向非技术人员展示整体架构时，图形化工具依然无可替代。ADK的思路是给你多一种选择，在需要快速编码和迭代时，你可以毫不犹豫地选择代码优先。

注意：市面上名为“ADK”的项目可能不止一个，本文讨论的概念更偏向于一种设计模式和工具集思想。在实际选型时，你需要仔细查看具体项目（例如热词中提到的Hermes Agent或许提供了自己的ADK）的文档，确认其组件划分是否清晰，是否符合你的“组装”预期。

3. 环境搭建与第一个“无图”Agent实战

理论说得再多，不如动手一试。我们假设一个非常实际的需求：构建一个“技术文档问答助手”Agent。它需要能读取本地Markdown文档库，理解用户的技术问题，并从文档中找出相关答案。我们不用画任何流程图，全程用代码和配置来实现。

3.1 基础环境与项目初始化

首先，我们需要一个干净的Python环境。强烈建议使用conda或venv创建虚拟环境，这是避免依赖冲突的黄金法则。

# 使用 conda 创建环境 conda create -n adk-agent python=3.10 conda activate adk-agent # 或使用 venv python -m venv venv # Windows: venv\Scripts\activate # Linux/Mac: source venv/bin/activate

接下来，安装核心依赖。由于ADK是一个概念集合，我们这里以一个假设的、集成了ADK思想的框架agent-framework为例（在实际中，它可能是你调研的某个具体开源项目）。我们还会安装用于文档处理的langchain和向量数据库chromadb。

pip install agent-framework langchain langchain-community chromadb pypdf sentence-transformers

初始化项目结构。一个清晰的目录结构能让后续开发事半功倍。ADK风格的项目通常如下：

tech_doc_agent/ ├── agent.yaml # Agent的主配置文件，声明核心组件 ├── skills/ # 技能目录 │ ├── __init__.py │ ├── document_loader.py # 文档加载技能 │ └── doc_qa.py # 文档问答技能 ├── memory/ # 记忆相关配置（可选） │ └── config.yaml ├── runners/ # 自定义运行器（可选，通常使用框架默认） │ └── custom_runner.py └── main.py # 应用入口文件

3.2 定义核心技能（Skills）

技能是Agent能力的基石。我们创建两个技能。

技能一：DocumentLoaderSkill (skills/document_loader.py)这个技能负责加载指定目录下的所有Markdown和PDF文档，并进行文本分割和向量化存储。

import os from typing import List, Dict, Any from langchain_community.document_loaders import DirectoryLoader, PyPDFLoader from langchain.text_splitter import RecursiveCharacterTextSplitter from langchain_community.vectorstores import Chroma from langchain_huggingface import HuggingFaceEmbeddings from agent_framework.skill import Skill, skill @skill class DocumentLoaderSkill(Skill): """加载并向量化文档的技能""" def __init__(self, persist_directory: str = "./chroma_db"): super().__init__() self.persist_directory = persist_directory # 使用开源嵌入模型，避免调用API self.embeddings = HuggingFaceEmbeddings(model_name="all-MiniLM-L6-v2") self.vectorstore = None def load_documents(self, data_dir: str) -> Dict[str, Any]: """加载文档并创建向量存储""" try: # 加载Markdown文件 md_loader = DirectoryLoader(data_dir, glob="**/*.md") md_docs = md_loader.load() # 加载PDF文件 pdf_loader = DirectoryLoader(data_dir, glob="**/*.pdf", loader_cls=PyPDFLoader) pdf_docs = pdf_loader.load() all_docs = md_docs + pdf_docs if not all_docs: return {"status": "error", "message": f"No documents found in {data_dir}"} # 文本分割 text_splitter = RecursiveCharacterTextSplitter(chunk_size=1000, chunk_overlap=200) splits = text_splitter.split_documents(all_docs) # 创建并持久化向量数据库 self.vectorstore = Chroma.from_documents( documents=splits, embedding=self.embeddings, persist_directory=self.persist_directory ) self.vectorstore.persist() return { "status": "success", "message": f"Loaded and indexed {len(splits)} chunks from {len(all_docs)} documents.", "num_chunks": len(splits) } except Exception as e: return {"status": "error", "message": str(e)} def get_retriever(self, k: int = 4): """获取检索器，供其他技能使用""" if self.vectorstore is None: raise ValueError("Vectorstore not initialized. Please load documents first.") return self.vectorstore.as_retriever(search_kwargs={"k": k})

技能二：DocQASkill (skills/doc_qa.py)这个技能利用已加载的向量数据库，根据用户问题检索相关文档片段，并组织答案。

from typing import Dict, Any from langchain.chains import RetrievalQA from langchain_community.llms import Ollama # 假设使用本地Ollama模型 from agent_framework.skill import Skill, skill from .document_loader import DocumentLoaderSkill @skill class DocQASkill(Skill): """基于文档的问答技能""" def __init__(self, document_loader: DocumentLoaderSkill, model_name: str = "llama3.2"): super().__init__() self.document_loader = document_loader # 连接本地Ollama服务 self.llm = Ollama(model=model_name, base_url="http://localhost:11434") self.qa_chain = None def setup(self): """技能初始化，创建问答链""" retriever = self.document_loader.get_retriever() self.qa_chain = RetrievalQA.from_chain_type( llm=self.llm, chain_type="stuff", retriever=retriever, return_source_documents=True ) return {"status": "success", "message": "QA chain initialized."} def answer_question(self, question: str) -> Dict[str, Any]: """回答用户问题""" if self.qa_chain is None: self.setup() try: result = self.qa_chain.invoke({"query": question}) answer = result.get("result", "Sorry, I couldn't find an answer.") sources = [doc.metadata.get("source", "Unknown") for doc in result.get("source_documents", [])] return { "status": "success", "answer": answer, "sources": list(set(sources))[:3] # 去重并取前3个来源 } except Exception as e: return {"status": "error", "message": f"QA process failed: {str(e)}"}

实操心得：在定义Skill时，务必做好错误处理，并将结果以结构化的字典形式返回。这能让Runner更好地处理技能执行状态，也为后续的日志和监控打下基础。另外，将DocumentLoaderSkill作为依赖注入到DocQASkill中，是一种清晰的解耦方式，符合ADK的“组装”理念。

3.3 配置与组装Agent (agent.yaml)

现在，我们不再画图，而是用一个YAML配置文件来“声明”我们的Agent。这个文件告诉Runner：这个Agent由哪些技能构成，它们之间如何关联，以及使用什么配置。

# agent.yaml name: "TechDocQA_Agent" version: "1.0.0" description: "一个基于本地文档库的技术问答助手" runner: type: "default" # 使用框架提供的默认运行器 settings: max_concurrent_skills: 2 timeout: 30 skills: - id: "doc_loader" class: "skills.document_loader.DocumentLoaderSkill" config: persist_directory: "./data/chroma_db" auto_init: true # Agent启动时自动初始化 - id: "doc_qa" class: "skills.doc_qa.DocQASkill" config: model_name: "llama3.2" # 指定本地Ollama模型 dependencies: ["doc_loader"] # 声明依赖，Runner会按顺序初始化 memory: type: "conversation_buffer" # 使用简单的对话缓冲记忆 config: buffer_size: 5 # 定义Agent的默认工作流（非图形化，而是事件-技能映射） workflow: default: trigger: "user_message" # 触发条件：收到用户消息 action: "doc_qa.answer_question" # 执行动作：调用doc_qa技能的answer_question方法 input_mapping: # 输入映射：将用户消息映射为技能参数 question: "{{event.message}}"

这个配置文件清晰地定义了Agent的蓝图：它有两个技能，问答技能依赖于加载器技能；它使用一个简单的对话记忆；当收到用户消息时，会自动触发问答流程。整个过程，没有拖拽任何一个图形节点。

3.4 编写主程序并运行 (main.py)

最后，我们写一个简单的主程序来启动这个Agent。

# main.py import yaml import asyncio from agent_framework import AgentRunner def load_config(): with open('agent.yaml', 'r', encoding='utf-8') as f: return yaml.safe_load(f) async def main(): # 1. 加载配置 config = load_config() # 2. 创建并启动Agent运行器 runner = AgentRunner.from_config(config) await runner.start() print("TechDocQA Agent 已启动！输入 'quit' 退出。") # 3. 简单的命令行交互循环 try: while True: user_input = input("\n你: ") if user_input.lower() == 'quit': break # 4. 将用户输入作为事件触发默认工作流 response = await runner.process_event("user_message", {"message": user_input}) # 5. 处理并显示结果 if response.get("status") == "success": print(f"\n助手: {response.get('answer')}") if response.get('sources'): print(f" 参考来源: {', '.join(response.get('sources'))}") else: print(f"\n助手: 出错了 - {response.get('message')}") finally: # 6. 优雅关闭 await runner.stop() if __name__ == "__main__": asyncio.run(main())

运行这个程序前，请确保你的Ollama服务已经启动，并且拉取了llama3.2模型（ollama pull llama3.2）。同时，在项目根目录下创建一个docs文件夹，放入你的Markdown或PDF技术文档。

# 启动Agent python main.py

如果一切顺利，你将看到一个完全通过代码和配置构建的、具备文档问答能力的Agent在命令行中运行起来。你可以问它关于你文档内容的问题，它会从本地向量库中检索并生成答案。

4. 核心机制深度剖析：Runner、记忆与技能协作

通过上面的实战，我们已经搭建了一个可运行的Agent。但要让这个Agent更健壮、更智能，我们需要深入理解ADK框架下几个核心机制是如何工作的。

4.1 Runner：不止是调度器

在agent.yaml中，我们指定了runner.type: "default"。这个默认Runner至少承担了以下几项关键工作：

1. 依赖解析与技能初始化：它读取配置文件，根据dependencies字段构建技能初始化顺序图（注意，是内存中的逻辑图，不是可视化图）。它会先初始化doc_loader，然后将初始化好的实例注入到doc_qa的构造函数中。这个过程如果循环依赖或初始化失败，Runner会明确报错。
2. 生命周期管理：runner.start()和runner.stop()方法确保了所有技能能正确地获取和释放资源（比如数据库连接、网络会话）。这比手动管理要可靠得多。
3. 事件驱动与技能路由：runner.process_event(“user_message”, …)是核心。Runner内部维护了一个事件-监听器映射表。当user_message事件被触发时，它会找到配置中workflow.default对应的action（即doc_qa.answer_question），并调用该技能的方法。这种模式非常灵活，你可以轻松定义多种事件（如timer_tick,webhook_call）来触发不同的技能组合。
4. 隔离与容错：一个设计良好的Runner会将每个技能放在独立的执行上下文或线程/进程中运行。这意味着即使doc_qa技能在处理某个复杂问题时超时或崩溃，Runner本身以及doc_loader技能通常不会受到影响，它可以选择重启该技能或返回一个友好的错误信息。

4.2 记忆系统：让Agent拥有“过去”

我们配置了type: “conversation_buffer”记忆。这是一个简单的内存记忆，只保留最近几次的对话。但在实际项目中，这远远不够。ADK的强大之处在于可以灵活切换记忆后端。

例如，如果你想实现“记住用户偏好”或“从历史长对话中寻找相关上下文”，就需要向量记忆。我们可以修改agent.yaml：

memory: type: “vector” # 切换为向量记忆 config: embedding_model: “all-MiniLM-L6-v2” # 与技能中使用的嵌入模型保持一致 storage_path: “./memory_vectors” search_kwargs: {“k”: 5} # 每次检索最相关的5段记忆

在技能中，你可以通过Runner提供的上下文接口来存取记忆：

# 在某个技能的方法中 class PersonalizeSkill(Skill): async def some_method(self, event, context): # 存入记忆 await context.memory.store(f”user_preference:{user_id}”, {“theme”: “dark”, “lang”: “zh”}) # 读取记忆 past_prefs = await context.memory.search(f”user_preference:{user_id}”)

向量记忆会使用嵌入模型将你存储的文本（或结构化数据的文本表示）转换为向量，当你需要时，它能根据当前对话的语义，自动找出最相关的历史记忆片段，并注入到给大模型的提示词中。这是实现高级Agent（如热词中提到的“Hermes Agent”所强调的长期记忆）的关键。

4.3 技能间的通信与数据流

在我们的例子里，DocQASkill通过构造函数依赖注入了DocumentLoaderSkill。这是一种紧密的、编译时确定的依赖关系，适合固定组合。

对于更动态的协作，ADK通常支持通过事件总线（Event Bus）或共享上下文（Shared Context）进行技能间通信。

• 事件总线：技能A完成工作后，可以发布一个事件（如document_processed），而技能B可以订阅这个事件。这样它们完全解耦，Runner负责中间的消息传递。这在异步、流水线式处理中非常有用。
• 共享上下文：在runner.process_event()处理一个事件的过程中，会生成一个本次执行的上下文对象。技能可以将中间结果存入这个上下文（如context[“retrieved_docs”] = docs），后续的技能可以从这里读取。这适合顺序执行且有数据传递需求的场景。

在agent.yaml的workflow部分，input_mapping就是一种声明式的数据流配置，它定义了如何将事件数据或上下文数据“映射”到技能方法的参数上。这种声明式的方式，再次体现了“不写图”但清晰定义流程的思想。

5. 进阶实践：多技能协作与外部工具集成

单一问答技能只是开始。ADK“组装”思想的威力在于轻松组合多个技能完成复杂任务。让我们扩展之前的Agent，让它还能在找不到答案时，自动去互联网搜索。

5.1 新增网络搜索技能

我们创建一个新的技能文件skills/web_search.py。这里我们使用一个假设的搜索工具库。

from typing import Dict, Any import aiohttp from agent_framework.skill import Skill, skill @skill class WebSearchSkill(Skill): """网络搜索技能""" def __init__(self, api_key: str = None): super().__init__() self.api_key = api_key self.search_url = “https://api.search.example.com/v1/search” # 示例URL async def search(self, query: str, num_results: int = 3) -> Dict[str, Any]: """执行网络搜索""" if not self.api_key: return {“status”: “error”, “message”: “Search API key not configured.”} headers = {“Authorization”: f”Bearer {self.api_key}”} params = {“q”: query, “limit”: num_results} try: async with aiohttp.ClientSession() as session: async with session.get(self.search_url, headers=headers, params=params, timeout=10) as resp: if resp.status == 200: data = await resp.json() # 假设返回格式为 {“results”: [{“title”: “…”, “snippet”: “…”, “url”: “…”}]} return {“status”: “success”, “results”: data.get(“results”, [])} else: return {“status”: “error”, “message”: f”Search API error: {resp.status}”} except Exception as e: return {“status”: “error”, “message”: f”Network error: {str(e)}”}

5.2 设计决策逻辑与工作流编排

现在，我们有了两个核心技能：DocQASkill（本地文档问答）和WebSearchSkill（网络搜索）。我们需要一个“决策者”来协调它们。我们可以创建一个简单的OrchestratorSkill，或者更ADK风格地，利用工作流条件分支。

修改agent.yaml，定义更复杂的工作流：

workflow: handle_query: trigger: “user_message” # 第一步：先尝试本地文档问答 action: “doc_qa.answer_question” input_mapping: question: “{{event.message}}” # 根据第一步的结果，决定下一步 next: - when: “{{result.status == ‘success’ and result.answer|length > 10}}” # 成功且有实质内容 goto: “reply_with_answer” # 跳转到回复步骤 - when: “{{result.status == ‘error’ or result.answer|length <= 10}}” # 失败或答案太短 goto: “fallback_to_search” # 跳转到搜索回退步骤 reply_with_answer: action: “builtin.reply” # 假设框架内置了一个回复技能 input_mapping: message: “{{‘根据文档：’ + result.answer if result.sources else result.answer}}” fallback_to_search: action: “web_search.search” input_mapping: query: “{{event.message}}” next: - when: “{{result.status == ‘success’ and result.results}}” goto: “format_search_results” - default: “reply_not_found” format_search_results: action: “builtin.reply” input_mapping: message: | {{‘在文档中未找到明确答案，以下是根据网络搜索的结果：\n’ + result.results|map(attribute=’snippet’)|join(‘\n---\n’)}} reply_not_found: action: “builtin.reply” input_mapping: message: “抱歉，在文档和网络中均未找到相关答案，请尝试换一种方式提问。”

这个YAML配置定义了一个清晰的状态机：先查本地库，如果找到满意答案就回复；如果没找到，就触发网络搜索；最后格式化搜索结果或告知未找到。全程没有使用图形化界面，但通过声明式的YAML，我们同样定义了一个逻辑清晰的、多技能协作的复杂工作流。这种方式的优势在于，逻辑一目了然，且易于版本化管理。

5.3 集成外部工具与API

WebSearchSkill已经展示了如何集成外部API。对于更通用的工具调用，ADK框架通常会提供一种标准化方式来描述和调用工具，使其能够被大语言模型（LLM）理解和规划使用。这通常涉及创建一个Tool类，并注册到技能或Agent的上下文中。

例如，我们可以将计算器、查询天气、发送邮件等功能都封装成独立的Tool，然后Agent的核心推理引擎（LLM）可以根据用户目标，自动规划并调用这些Tool。这才是真正意义上的“智能体”。虽然这部分的实现更复杂，涉及提示词工程和LLM的规划能力，但ADK的职责是提供一套简洁的注册、发现和调用这些Tool的机制，让开发者无需关心底层的通信和调度细节。

6. 部署、监控与常见问题排查

一个只能在开发环境运行的Agent价值有限。ADK项目通常也关注如何将组装好的Agent部署到生产环境。

6.1 打包与部署

1. 依赖管理：确保每个技能在__init__方法或一个单独的requirements.txt中声明其依赖。Runner在初始化技能前，可以检查并提示缺失依赖。更工程化的做法是使用Docker容器化每个技能或整个Agent。
2. 配置外化：像API密钥、模型路径、数据库连接字符串等敏感或环境相关的配置，绝不应该硬编码在技能代码或YAML里。应该通过环境变量或外部配置服务（如Consul）注入。agent.yaml可以支持变量替换，如api_key: “{{ env.SEARCH_API_KEY }}”。
3. 部署为服务：最常见的部署方式是将Agent封装为HTTP API（FastAPI、Flask）或gRPC服务。ADK框架应提供相应的适配器或Runner，让你能快速将Agent实例挂载到Web框架上。这样，前端应用或其他微服务就可以通过RESTful接口与你的Agent交互。

6.2 日志、监控与可观测性

生产环境下的Agent必须有完善的监控。

• 结构化日志：在每个技能的关键步骤（开始、结束、出错）记录结构化的日志（JSON格式），包含技能ID、执行ID、时间戳、输入/输出摘要、耗时等。这便于后续用ELK或Loki进行聚合分析。
• 性能指标：在Runner层面收集指标，如事件处理延迟、技能调用成功率、队列长度等，并暴露给Prometheus等监控系统。
• 链路追踪：对于一个用户请求，如果触发了多个技能调用，最好能生成一个唯一的追踪ID（Trace ID），并贯穿整个处理链路。这能帮你快速定位性能瓶颈或错误根源。

6.3 常见问题与排查清单

结合热词中提到的“Runner failed”等问题，以下是一些常见坑点及解决方案：

踩坑心得：在开发中期，一定要尽早搭建一个简单的、覆盖主流程的集成测试。这个测试不依赖外部服务（可以用Mock），只验证从事件触发到最终响应的整个链条是否通畅。这能帮你快速发现配置错误和数据流断裂问题，比在复杂的交互中调试要高效得多。

7. 总结与展望：超越图形化，拥抱工程化

回顾整个“不写图，搭Agent”的旅程，我们从ADK的核心设计理念出发，通过纯代码和声明式配置，一步步构建了一个具备文档问答、并能联网搜索补充的智能体。我们深入剖析了Runner、Skill、Memory等核心组件的协作机制，探讨了多技能编排和外部集成，最后还讨论了部署监控和常见问题。

这条路径的优势正在于它的工程化友好和灵活性。它将Agent开发从单一的“画图”思维中解放出来，允许开发者用自己最熟悉的工具（代码编辑器、版本控制、测试框架）来构建复杂、可维护的智能系统。当你的Agent逻辑需要频繁迭代、需要与现有代码库深度集成、或者需要严格的CI/CD流程时，这种代码优先的方式优势尽显。

当然，这并不意味着你要完全抛弃可视化工具。在项目架构设计、与业务方沟通等场景，图形化视图依然非常有价值。未来的趋势很可能是双向同步：你可以用代码定义核心逻辑和技能，框架自动生成架构图；你也可以在可视化界面进行高层级的流程编排，并自动生成对应的配置代码。ADK为你提供了代码这“一侧”的强大能力。

对于想深入学习Agent开发的朋友，我的建议是：不要被各种炫酷的框架和工具迷惑，先从理解Agent的核心构成（感知、规划、行动、记忆）开始，然后用最简单的方式（比如像本文这样）实现一个最小可行产品（MVP）。在这个过程中，你会遇到真实的问题（比如工具调用的可靠性、记忆的管理、长上下文处理），带着这些问题再去研究LangChain、AutoGen、Semantic Kernel乃至热词中提到的Hermes等框架，你就能更清楚地知道它们各自在解决什么痛点，应该如何选择。

Agent开发的浪潮已然到来，但它的基石依然是扎实的软件工程能力。ADK所代表的“不写图”的开发范式，正是将AI能力工程化、产品化的一条务实路径。希望这篇长文能为你打开一扇新的大门，让你在构建智能体的道路上，多一份从容，少一份对复杂工具的畏惧。