企业官网建设流程全解析

用 Rust 写 Agent 服务 — adk-rust 上手记

最近几个月我一直在折腾 Agent 相关的工程化落地，前后试过 Python 系的 LangGraph、Semantic Kernel，也用过几套偏重型的编排框架。说实话，框架虽多，但真正想塞进现有 Rust 服务里、又不想引入一大坨 Python 运行时依赖的时候，选择面一下就窄了。后来看到 adk-rust 这个项目，才算是找到一条比较顺手的路子。这篇文章就按我自己的上手过程来写，从为什么选它、环境怎么搭，到核心概念怎么理解、实际跑一个 Agent 服务要过哪些坎，最后把踩过的坑和一些排查经验一并整理出来。标题说是“上手记”，内容也确实就是一篇实战记录，希望对正在调研 Rust Agent 方案的读者有点参考价值。

我最早注意到 adk-rust，是因为团队内部有个需求：要把现有的用户意图识别、知识库检索和工单生成这几个模块串成一个可复用的 Agent 服务，同时要求服务能以常驻进程的方式部署，而不是每次请求临时拉起一个脚本。这个场景下 Python 方案虽然快，但生产环境要额外维护解释器、依赖锁和进程管理；用 Rust 的话，单二进制部署、内存占用可控、并发能力又强，天生适合做这种常驻型服务。adk-rust 的名字里带 adk，全称是 Agent Development Kit，和 Google 的 ADK 思路同源，但实现上完全走 Rust 生态，核心靠 tokio 驱动异步运行时，模型调用层则抽象成统一的 trait，底层可以接 OpenAI 兼容接口、Gemini 等。它把我最关心的几个点——工具调用、多轮上下文、结构化输出、服务化封装——都做成了相对独立却又可以组合的模块，这一点很关键。

先说明一下，这篇不是官方文档的翻译，也不是教程的复读。我会按我实际踩通的路来写，网络上能查到的 API 细节我这里不会全盘照抄，更多是讲清楚“为什么要这么用”和“实际用起来会遇到什么”。

1. 为什么在 Rust 生态里选 adk-rust 而不是自己拼轮子

1.1 先想清楚：你需要的到底是“Agent 框架”还是“Agent 服务”

上手之前，我建议你先做一道判断题：你的目标是一个能处理多步推理、会调用外部工具的Agent 应用，还是一个能对外提供 HTTP 接口、内部跑 Agent 逻辑的Agent 服务。这两个目标对框架的要求差异非常大。

如果你只是想在脚本里跑一个带工具调用的对话循环，那用 async-openai 自己写循环也就二三百行代码的事。但如果你要让多个模型实例共享上下文、要支持并发请求、要对接可观测性系统、要优雅处理超时和重试，这就不是拼一个循环能解决的，而是需要一个服务骨架。adk-rust 的定位正好偏后者：它内部把 Runner、Session、Tool 这些概念做成了可独立使用的模块，你可以只取其中一部分，也可以整套端上来跑成一个 axum 服务。

我自己比较看重的一点是，adk-rust 没有把“模型调用”和“业务逻辑”强行绑在一起。它的模型层抽象成LlmClienttrait，工具层抽象成Tooltrait，会话状态由Session管理，而整个执行流程由Runner来驱动。每一层都可以替换，这种设计在真实项目里非常实用。比如我们内部用的模型网关是兼容 OpenAI 协议的，那我只需要实现一个LlmClient，或者直接复用项目里自带的 OpenAI 兼容实现，改一下 base_url 和 model 名就能跑，不需要动其他代码。

1.2 和其他方案比，adk-rust 的优势到底在哪里

抛开“用 Rust 写 Agent”这个自带光环的选项，横向对比一下市面上常见的几类方案，会更清楚它的定位。

第一类是 Python 系框架，比如 LangGraph、AutoGen、Google ADK 的 Python 版。它们生态最丰富，社区案例多，插件体系完善，有些还带可视化编排界面。但缺点也很明显：部署依赖重，Python 版本、虚拟环境、pip 依赖锁、进程守护都要管，如果要嵌进现有 Rust 服务里，跨语言调用的开销和复杂度都不小。

第二类是纯 API 调用型 SDK，比如 OpenAI 官方 SDK、anthropic SDK。它们提供了请求封装和流式接口，但本身不含“工具调用循环”和“多步推理”的运行时逻辑。你想实现一个会查数据库、再根据查询结果决定下一步调用哪个工具的 Agent，得自己维护循环、记录中间步骤、管理 token 消耗。工作量不大，但重构和维护成本是持续的。

第三类就是 adk-rust 这种偏框架性质的 Rust 实现。它把 Agent 执行循环内置好了，同时把可替换的部分留成 trait，你只需要关注业务工具和提示词，服务骨架和并发模型都由框架承担。比起纯 SDK，它的抽象层级更高；比起 Python 框架，它没有运行时拖累；比起自己拼轮子，它省下了最烦人的上下文管理和重试机制。

当然它也有不足。最直观的一点是生态还处在早期，第三方集成和文档都还在积累中，遇到问题往往需要直接读源码。所以我的建议是：如果你团队里有 Rust 基础，并且服务本身就要常驻运行，adk-rust 值得优先考虑；如果只是快速验证想法，那 Python 生态依然更省事。

1.3 场景判断：什么样的项目适合直接采用 adk-rust

结合我自己的实践，至少在下面几类场景里，adk-rust 是“用起来舒服”的：

• 已有 Rust 后端服务，想在内置一个具备工具调用能力的智能体模块，而不是再开一个 Python 微服务。
• 对资源占用和启动速度敏感，希望 Agent 服务能作为单二进制部署，快速扩容。
• 需要把 Agent 执行过程封装成内部 API，供其他服务调用，而不是只做交互式命令行演示。
• 希望工具调用、模型调用、会话存储这几个部分能被分别测试和替换。

反过来，如果你的场景主要是快速原型验证、大量依赖现成插件、或者团队没有 Rust 经验，那 adk-rust 现阶段不一定是最优解。这个判断一定得做在前面，否则后面越写越别扭。

2. 环境准备与项目初始化：从零跑通第一个 Agent

2.1 Rust 工具链与镜像源配置

不管你是第一次装 Rust 还是已经在用，先确认两件事：rustc和cargo的版本够新，以及依赖下载源访问是否顺畅。adk-rust 对 Rust 版本要求不算激进，但太老的编译器会导致一些依赖包无法解析，我建议直接用官方推荐的 rustup 安装稳定版，然后确认一下版本：

rustc --version cargo --version

如果你在国内网络环境下用默认 crates.io 源，大概率会遇到依赖下载超时或慢到怀疑人生的情况。这里可以用镜像源来缓解，常见做法是在~/.cargo/config.toml里配置一个可用的镜像源。我个人用的是字节跳动的镜像，配好之后依赖下载速度提升非常明显。需要注意的是，不同镜像的同步频率略有差异，如果你在cargo add时发现某个新版本拉不到，可以先检查是不是镜像同步延迟，而不是急着改代码。

提示：修改config.toml后，如果之前已经拉过部分依赖，建议执行cargo clean或删除Cargo.lock重新生成，避免半缓存状态导致的奇怪编译错误。我实际遇到过 lock 文件里的 checksum 和镜像源不一致导致的报错，虽然概率低，但清理重来最省心。

2.2 创建一个新的 Rust 项目并引入 adk-rust

初始化项目这一步比较常规，但有几个细节值得说。首先建议直接用cargo new建一个二进制项目，名字就叫agent-demo之类就行：

cargo new agent-demo cd agent-demo

然后添加必要依赖。adk-rust 本身在 crates.io 上发布，但不同版本的 API 变动比较大，强烈建议你打开项目的 README 或 docs.rs 确认你锁定的版本号。我写这版上手记录时用的是 0.1.x 系列的 API，但等你看到这篇文章时可能已经有了新版本，所以下面代码里的模块路径和函数名，要以你拉到的版本为准。

cargo add adk-rust cargo add tokio --features full cargo add serde --features derive cargo add serde_json cargo add anyhow

这里有个小经验：adk-rust 的依赖树里本身会带 tokio、reqwest 等常用库，但你还是应该显式声明自己直接用的依赖。Rust 不做依赖提升（dependency hoisting），你直接调用的 crate 如果没有写进Cargo.toml，编译会直接报错，即使它已经被传递依赖引入了也没用。这个问题新手容易忽略，实际写代码时经常遇到。

2.3 配置模型访问参数

adk-rust 本身不内置任何模型的 API key 管理，它更倾向于把外部配置交给你自己掌控。我实际操作时是用环境变量来管理MODEL_NAME、BASE_URL、API_KEY这几个值的。这样做的好处是，代码里不出现敏感信息，部署到不同环境也只需要改环境变量，不用重新编译。

export MODEL_NAME="gpt-4o-mini" export BASE_URL="https://your-gateway.example.com/v1" export API_KEY="your-api-key"

如果你的模型网关是在本地起的一个兼容 OpenAI 协议的服务（比如 vLLM、Ollama 的 OpenAI 兼容端点），那BASE_URL指向本地端口就行。我第一次跑通就是用本地的一个推理服务，这样既省 key，又方便调试。

2.4 第一个可运行的最小 Agent

接下来写一个最简可运行的例子。目标只有一个：跑通“用户输入 → 模型返回 → 打印结果”这条链路。先把流程跑通，再逐步加工具调用和会话管理。

use adk_rust::agent::{Agent, AgentConfig}; use adk_rust::llm::{OpenAIClient, OpenAIConfig}; use adk_rust::runner::{Runner, RunnerConfig}; use adk_rust::session::InMemorySession; #[tokio::main] async fn main() -> anyhow::Result<()> { let model_config = OpenAIConfig::new() .with_base_url(std::env::var("BASE_URL")?) .with_api_key(std::env::var("API_KEY")?); let llm_client = OpenAIClient::new(model_config); let agent = Agent::new( "demo_agent", "你是一个乐于助人的助手", llm_client, AgentConfig::default(), ); let session = InMemorySession::new(); let runner = Runner::new( agent, RunnerConfig::default(), session, ); let input = "请用一句话介绍你自己"; let response = runner.run(input).await?; println!("{}", response.as_text()); Ok(()) }

如果你跑完发现输出是一段正常的模型回复，那说明链路已经通了。这个最小示例看着简单，但拆开看其实已经包含了四个关键概念：模型客户端、Agent 定义、会话存储、执行器。后面所有复杂的编排都是在这四块基础上扩展。

3. 核心概念拆解：Agent、Runner、Session、Tool 是四根柱子

3.1 Agent 不只是“提示词 + 模型”，它是一份完整配置

在 adk-rust 里，Agent是一个承载所有智能体配置的聚合体。名字、系统提示词、模型客户端、生成参数、可用工具列表，这些都挂在 Agent 上。它解决的问题是“这个智能体是谁、它能做什么、它该用哪个模型来驱动”。

实际项目中，我建议把 Agent 的定义收敛到工厂函数里，这样不同的业务场景可以各自构造不同的 Agent 实例。比如我们的工单助手和知识库问答助手，虽然底层模型同一个，但系统提示词和工具列表完全不一样。如果所有 Agent 都散落在业务代码里，后期维护会非常难受。

pub fn build_ticket_agent() -> Agent { Agent::new( "ticket_agent", "你是工单处理助手，负责根据用户描述创建工单、查询工单状态、转接人工。", llm_client(), AgentConfig { temperature: 0.2, max_tool_calls: 10, ..Default::default() }, ) .with_tool(CreateTicketTool) .with_tool(QueryTicketTool) }

这里有个重要参数：max_tool_calls。它限制单轮用户请求中，Agent 最多可以连续调用几次工具。默认值一般够用，但如果你的任务链路特别长，比如“查订单 → 查库存 → 生成退款单 → 通知用户”，那模型可能需要多步工具调用才能收集足够信息。max_tool_calls就是你的安全阀，防止模型在复杂场景里无限循环。我一般设置 8 到 12，既给足空间，又不至于失控。

3.2 Runner 是大脑，负责驱动多步推理循环

如果只看 API 名字，你可能会把 Runner 当成“一个跑任务的执行器”。实际上，它的核心职责是驱动整个 Agent 循环：把用户输入传进 Agent，Agent 决定是要直接回复还是调用工具；如果要调用工具，Runner 会去执行工具，把结果塞回上下文，再交给 Agent 继续推理；直到 Agent 觉得信息足够了，输出最终回复。

这个循环在 adk-rust 里是内置好的，你不需要自己写 while 循环，也不需要管理中间每一步的消息格式。但你必须理解它，否则遇到奇怪行为时无从排查。比如模型在工具调用后突然答非所问，那多半是上下文组装问题，而不是模型本身的问题。

从工程角度看，Runner 还负责透传执行过程中的一些元信息，比如每次工具调用的耗时、token 消耗、调用顺序。这些信息对生产环境做日志和指标采集非常有用。我在跑真实服务时，会在 Runner 执行完后把整个执行轨迹打到结构化日志里，后续做链路追踪和成本分析都靠它。

3.3 Session 是记忆体的抽象，别把所有东西都塞内存

Session 管理的是“一组连续的对话状态”。同样是多轮对话，你是想让 Agent 记住所有历史细节，还是只看最近几轮，这决定了 Session 实现的选择。

adk-rust 自带InMemorySession，用起来简单，重启即失忆，适合开发和单机场景。但生产环境如果要让 Agent 跨请求保持记忆，那必须换用持久化实现。比如把 Session 状态序列化后存到 Redis 或 PostgreSQL，然后按 session_id 恢复上下文。

我自己实现过一个基于 Redis 的 Session 存储，原理不复杂：以 session_id 为 key，把消息列表序列化存进去，每次 Runner 跑完再把最新消息列表整体写回。要注意的是序列化格式要和 adk-rust 内部的消息结构兼容，否则下一次 Runner 读出来解析不了。这里建议先跑一遍InMemorySession的代码，看它是怎么序列化和恢复状态的，再照着写持久化版本，能省很多排查时间。

3.4 Tool 是 Agent 的手脚，设计好坏决定体验上限

Tool 是 Agent 与外部世界交互的唯一通道。凡是 Agent 需要获取“模型本身不知道”的信息或执行“模型本身无法完成”的操作，都需要通过 Tool 暴露出去。

adk-rust 的 Tool trait 设计得比较干净，核心是实现一个描述方法和一个执行方法。描述方法负责向模型说明“这个工具是干什么的、参数是什么”，执行方法负责实际干活。我第一次写工具时踩过一个坑：把工具描述写得太简略，模型经常不调用，或者调用时参数格式不对。后来我把描述改成带参数说明和示例的形式，调用准确率明显提升。

#[derive(serde::Deserialize)] struct QueryTicketParams { ticket_id: String, } struct QueryTicketTool; #[async_trait::async_trait] impl Tool for QueryTicketTool { async fn invoke(&self, params: serde_json::Value) -> Result<String, ToolError> { let params: QueryTicketParams = serde_json::from_value(params)?; let ticket = query_ticket_from_db(&params.ticket_id).await?; Ok(ticket.into_summary_text()) } }

工具的输出会作为新消息追加到上下文中，再交给模型继续推理。所以工具返回的字符串质量也很关键。理想情况下，工具返回的文本应该简洁、结构清晰，最好把结论和关键数字放在最前面，减少模型二次推理的负担。不要返回一坨原始 JSON，除非你真的需要模型来解析它——那样既费 token 又容易出错。

4. 实操一个完整的 Agent 服务：从命令行 Demo 到 HTTP API

4.1 场景设计：工单助手的完整功能拆解

为了展示 adk-rust 的能力边界，我设计了一个偏业务向的场景：一个工单助手服务。它要能做三件事：

1. 根据用户描述创建一张工单，自动填充标题、描述、优先级。
2. 查询某个工单的状态和当前处理阶段。
3. 如果问题需要人工介入，转接人工并记录转接原因。

这个场景覆盖了 Agent 服务最常见的几个能力点：结构化参数抽取、多工具配合、决策分支。更重要的是，它能很好地测试 Runner 在多轮工具调用之间的状态管理能力。

假设用户输入是：“我上周四提了个网络问题的工单，现在还没人处理，帮我查一下状态，如果超过两天没动，就转给人工，并告诉我结果。”这句话里，模型需要先理解“网络问题”是工单标题的一部分，然后调用“查工单”工具，接着基于查询结果判断是否要调用“转人工”工具。这个多步链路如果 Runner 状态管理不好，很容易在中途丢失上下文。

4.2 定义三个工具并组装成 Agent

第一步是把三个工具都定义出来。每个工具都要注意两点：参数结构要简单，描述要清晰。下面是三个工具的类型骨架，具体业务逻辑我这里简化处理。

struct CreateTicketTool; #[async_trait::async_trait] impl Tool for CreateTicketTool { async fn invoke(&self, params: serde_json::Value) -> Result<String, ToolError> { #[derive(serde::Deserialize)] struct Params { title: String, description: String, priority: Option<String>, } let p: Params = serde_json::from_value(params)?; let ticket_id = create_ticket(&p.title, &p.description, p.priority).await?; Ok(format!("工单创建成功，工单号：{}", ticket_id)) } }

另外两个工具的写法类似，一个查工单，一个转人工。为了节省代码篇幅，我这里不完整贴出，但你在封装自己的工具时，尽量保证返回消息里包含“操作结果 + 必要数据 + 下一步建议”。

工具定义完后，组装成 Agent：

let agent = Agent::new( "ticket_assistant", "你是工单助手，帮助用户完成工单相关操作。你可以创建工单、查询工单状态、转接人工。", llm_client, AgentConfig { temperature: 0.2, max_tool_calls: 8, ..Default::default() }, ) .with_tool(CreateTicketTool) .with_tool(QueryTicketTool) .with_tool(TransferTicketTool);

这一步做完，Agent 的“能力圈”就完整了。我在真实项目中还加过一个“获取当前用户信息”的工具，这样 Agent 在创建工单时能自动带上用户身份，不需要用户在对话里重复提供。

4.3 用 axum 把 Runner 封装成 HTTP 接口

Agent 本身是库，要变成服务还需要一层 HTTP 封装。这里我选 axum，因为它是 tokio 生态里最成熟的 Web 框架，adk-rust 也是基于 tokio 的，放一起没有额外的异步运行时冲突。

接口设计上，我做了两个端点：

• POST /api/chat：接收用户消息，返回 Agent 的最终回复。
• POST /api/chat/stream：以 SSE 方式返回增量输出，方便前端做打字机效果。

第二个端点在演示 Agent 能力时特别有用，因为多步工具调用会让用户等好几秒，如果没有任何中间反馈，体验很差。SSE 至少能让前端逐步展示“正在查工单...”“正在转接人工...”这类状态。

axum 集成代码大致是这样：

async fn chat_handler( State(state): State<Arc<AppState>>, Json(req): Json<ChatRequest>, ) -> Result<Json<ChatResponse>, ApiError> { let session = state.sessions.get_or_create(&req.session_id).await?; let response = state.runner.run_with_session( session, &req.message, ).await?; Ok(Json(ChatResponse { reply: response.as_text(), })) }

这里有个细节：run_with_session要求你先拿到 Session，而不是像前面最小示例那样内部临时创建 Session。这样同一个 session_id 的多次请求才能共享上下文。我在实际生产里是用一个DashMap<String, Arc<Mutex<SessionState>>>来做 session 注册表的，简单直接，也不引入额外存储依赖。等量级大了再换 Redis 不迟。

4.4 完整服务配置：超时、并发与优雅关闭

写成服务之后，要考虑生产运行参数。我常用的配置有三块：

第一是每请求超时。Agent 的多步调用可能涉及多个模型的顺序请求，总耗时会明显高于单次 LLM 调用。我给每个请求设置了 30 秒的超时上限，超过就返回 504。这个值你可以根据实际链路调整，但不建议设太短，否则长链路任务容易被误杀。

第二是并发控制。axum 本身就是异步并发模型，每个请求不会被阻塞线程。但如果你在工具里访问外部 API 或数据库，要注意控制连接池大小。adk-rust 内部的模型调用走的是 reqwest，默认连接池足够用，但如果你的服务 QPS 很高，最好统一配置一个共享的 reqwest Client，避免频繁建连。

第三是优雅关闭。在axum::serve外面加上with_graceful_shutdown，监听 Ctrl-C 或系统信号，确保正在执行的 Runner 任务跑完后再退出。否则正在处理中的请求会直接被中断，客户端收到一段残缺的响应。

5. 常见问题与排查技巧实录

5.1 模型一直不调用工具，问题出在哪

这是我最常被问到的问题，也是第一次用框架的人最容易困惑的：明明工具都挂上去了，模型就是不理，直接输出一句“我无法完成这个操作”。

这里要分几种情况排查。首先是工具描述。描述里如果只写“查询工单”，模型根本不知道什么时候该用、参数是什么。我建议描述写成完整的命令语句形式，比如“当用户询问工单状态或进度时，调用此工具查询工单详情。参数 ticket_id 为工单号”。其次是系统提示词。如果你在系统提示词里没有提到“你可以使用工具来获取信息”，有些模型会倾向于不调用工具。再就是模型本身的能力差异。小参数模型在工具调用上的成功率就是比大模型差，这不是框架能解决的。如果业务允许，优先选工具调用能力强的模型。

还有一个排查技巧：把 Runner 执行过程的中间消息序列打印出来。看模型在决定调用工具前到底收到了哪些消息。很多时候你会发现，模型其实尝试过调用工具，但参数格式不对导致工具执行报错，之后模型为了避免出错就直接放弃调用，改为文字回复。这种情况通过查看日志里的工具错误能很快定位。

5.2 多轮对话上下文越来越长，token 消耗控制不住

Session 会把所有历史消息都累积到上下文里，对话轮次一多，token 消耗呈线性增长，最后要么超限，要么成本失控。

解决办法是在 Runner 之外维护一个滑动窗口。目前 adk-rust 的 Session 本身不做裁剪，所以这个逻辑需要你自己实现。我的做法是在把 Session 传给 Runner 之前，先对历史消息做一次截断：保留最近 10 轮的消息，更早的压缩成摘要。这个方案实现起来不复杂，但能显著降低成本。

另外，工具返回结果也会留在上下文里。如果你的工具返回了一个特别长的列表，而 Agent 只需要其中几个数字，建议在工具内部先做过滤，只返回必要字段。否则每轮对话都重复携带一长串历史工具输出，既浪费 token，又容易让模型抓不住重点。

5.3 并发请求互相串上下文，会话存储必须谨慎

最早我图省事，把 Session 放在一个全局变量里，结果两个用户同时提问，回复互相串了。后来才意识到，Session 的作用域是“一个会话”，不是“全局单例”。每次请求都应该通过 session_id 找到或创建独立的 Session 实例。

如果你用内存存储，建议用DashMap<String, Arc<Mutex<Session>>>这样按 id 隔离的结构。如果你用 Redis，建议把 session_id 当作 key 的一部分，每次请求都从 Redis 读取最新状态，执行完再写回。无论如何，不要在业务代码里手动维护一个裸的 Session 变量。

5.4 编译报错怎么办：先读源码，再看 issue

adk-rust 还在快速迭代期，编译报错很常见。我第一次升级版本后，好几个 trait 方法签名变了，文档还没同步更新。遇到这种情况，我的习惯是直接进~/.cargo/registry/src/对应目录里看源码。比如报错说“某个 trait 没有实现某个方法”，你打开 trait 定义看一眼，加上缺失的方法签名就行。

如果源码也看不懂，再去看 GitHub issue 或 discussions。但提问之前，务必把你用的版本号、Cargo.toml 依赖列表、完整报错信息贴全，这样别人才能帮你定位。我自己在 issue 里帮别人排查时，最怕看到只有一句“运行报错”的描述，连版本都不写，根本无从下手。

5.5 请求耗时长、超时频繁，怎么定位瓶颈

Agent 服务耗时长的原因通常有三个：模型响应慢、工具执行慢、上下文太大导致模型处理变慢。

我的排查思路是分阶段打日志。Runner 执行过程中，每一步会经历模型调用和工具调用，分别记下耗时。如果瓶颈在模型调用，那可能是模型本身负载高或参数量大，考虑换更快的模型或降低温度参数；如果瓶颈在工具调用，那就是业务代码的问题，比如数据库查询慢、外部 API 慢，需要单独优化工具实现；如果是上下文太大，就按前面说的窗口策略裁剪。

这里有个实用小技巧：adk-rust 的模型调用层实际上是异步函数，如果你发现并发场景下响应变慢，可以看一下是不是 tokio 的 work-stealing 被阻塞了。尽管工具调用写成了 async，但如果你在工具内部同步调用了一个阻塞操作（比如std::thread::sleep或同步的 HTTP 客户端），它会占住 tokio 的 worker 线程，影响整个服务的吞吐。工具内部尽量使用异步版本，或者把阻塞操作放进spawn_blocking里。

6. 从 Demo 到生产：我在实际项目里的几点经验

6.1 工具的输入参数要结构化，不要依赖模型自由发挥

我见过很多 Agent 项目，工具参数用一大段自然语言描述，让模型自己“领悟”出 JSON。这种做法的成功率很低，尤其是遇到开源模型或小参数模型时，经常会出现参数名拼错、类型不对、漏传字段等问题。

正确的做法是：每个工具都定义严格的 JSON Schema 或 Rust 结构体，参数名尽量简短且贴合常识，类型尽量用字符串和数字，避免嵌套对象。模型在生成工具调用时会严格遵循你给的结构，你通过serde_json::from_value做反序列化，解析失败就返回带提示的错误信息。这样可以提前拦截大部分参数错误，避免错误信息污染上下文。

6.2 监控和日志是 Agent 服务的生命线

传统 Web 服务出错了，看 HTTP status 和堆栈就能定位。Agent 服务不一样：用户看到一句“抱歉我无法完成”，可能是模型误判，可能是工具出错，也可能是上下文里混进了脏数据。没有日志，排查成本会非常高。

我的做法是给每次 Runner 执行分配一个 trace_id，从 HTTP 请求进入时注入，然后贯穿到模型调用日志和工具调用日志里。日志中记录：用户输入原文、最终回复、工具调用序列（哪个工具、入参是什么、出参是什么、耗时多少）、token 消耗、模型生成耗时。这套日志体系在线上排查时帮了大忙。有一次用户反馈某个按钮点击后返回内容不对，我看 trace 日志发现模型根本就没调用工具，直接根据上下文猜了个答案。从这个现象就能倒推出提示词引导不够明确，工具描述需要加强。

6.3 越复杂的 Agent，越需要“走一步看一步”的调试方式

写工具调用逻辑时，尽量不要一上来就堆五六个工具。工具越多，模型的选择负担越重，调用失误率也越高。我的做法是先只挂一个工具，跑通最简单的调用链路，再逐步增加。每增加一个工具，都要重新验证一遍：模型在什么描述下会调用它、参数解析是否稳定、返回内容是否会被模型正确利用。

这个习惯在项目初期看起来慢，但能避免后期陷入“模型总是选错工具”的泥潭。因为一旦工具数量多了，出问题时很难判断是某个工具的内部逻辑有问题，还是模型对工具描述的理解有偏差。

6.4 和 Python 生态互操作的场景：别硬融，走服务间调用

有些团队的现状是 Agent 逻辑已经在 Python 里写好了一套，现在想换 Rust 重写。我不建议你把 Python 的框架逻辑直接“翻译”成 adk-rust 的代码，因为两个生态的抽象方式和消息结构不一样，强行对齐只会让两边都别扭。

更稳妥的方式是：让 adk-rust 服务作为独立入口，负责会话管理、工具编排和模型调用；如果某些模型或工具还是 Python 生态更成熟，那就通过内部 HTTP 接口或消息队列调用那边的能力。这样 Rust 服务保持了性能和部署优势，Python 侧业务也不用推翻重来。

6.5 版本升级要谨慎，先锁版本，再平滑迁移

我踩过最深的坑，是在项目进行到一半的时候顺手执行了cargo update，结果 adk-rust 的 API 发生了变化，导致项目编译不过，又花了一下午去适配。

如果你的项目已经稳定运行，建议在Cargo.toml里锁定精确版本号，不要用^0.1.0这种宽松范围。升级前先看 changelog 和 diff，了解哪些 API 发生了变化，再决定是否升级。对于还在快速迭代的框架来说，稳定版锁版本比追新更重要。

7. 上手总结与资源清单

如果你已经顺着前面的步骤跑通了最小示例和工单助手服务，那说明你已经迈过了最难的“陌生感”阶段。接下来要做的无非是两件事：一是深度理解 Runner 的执行流程，把工具调用链路吃透；二是根据业务需要替换 Session 存储、模型客户端和工具集合。

关于学习资源，我建议优先看官方仓库的 README 和 examples 目录。市面上关于 adk-rust 的教程还不多，遇到问题直接看源码是最快的方式。其次关注 GitHub discussions，不少使用中的问题在那里已经有讨论，搜关键词能省很多时间。

另外提一句：adk-rust 和 Google ADK 在设计理念上有相似之处，如果你了解 ADK 里的 Agent、Session、Tool 这些抽象，上手 adk-rust 会更快。两者的概念一一对应，但实现语言和 API 完全不同，不要试图拿 Python 的用法直接套。

最后分享一点个人心得：框架只是骨架，真正让 Agent 服务好用的是工具设计和提示词打磨。adk-rust 帮你解决的是“执行过程可靠、并发安全、部署简单”这些工程问题，但“Agent 能不能准确理解用户需求、能不能高效调用工具”，还是取决于你如何设计和描述每一个工具。把这个想明白，你手里的 adk-rust 就不只是一个能跑的 Demo，而是一个可以支撑真实业务的 Agent 底座。