go-adk

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

go-adk

Expert guidance for developing agents with

google.golang.org/adk

(Go ADK).

为使用

google.golang.org/adk

（Go ADK）开发Agent提供专业指导。

When to trigger

触发场景

The user mentions Go ADK,
```
google.golang.org/adk
```
,
```
adk-go
```
, or asks how to build agents in Go.
The task involves ADK concepts like
```
llmagent
```
, tools, callbacks, sessions/state/memory, workflow agents, streaming, MCP, A2A, ADK web/API runtime, launchers, deployment, evaluation, or safety controls.

用户提及Go ADK、
```
google.golang.org/adk
```
、
```
adk-go
```
，或询问如何用Go构建Agent。
任务涉及ADK相关概念，如
```
llmagent
```
、工具、回调、会话/状态/内存、工作流Agent、流式传输、MCP、A2A、ADK Web/API运行时、启动器、部署、评估或安全控制。

Core rules

核心规则

Treat references/llms-index.md as the required ADK coverage map.
Prefer official ADK Go APIs and examples over ad-hoc wrappers.
Follow existing repository patterns first (imports, launcher style, layout, env handling).
For version-sensitive behavior, check release notes and API reference before giving definitive guidance.
Prioritize Go-specific ADK docs first; if a feature is documented only in another SDK doc, call that out explicitly.
Keep agent names unique and never use
```
user
```
as an agent name.
Use concise
```
Description
```
fields so delegation and tool selection remain reliable.
Treat ADK Web as development-only unless the user explicitly asks for production runtime choices.

将references/llms-index.md视为必须遵循的ADK覆盖范围映射表。
优先使用官方ADK Go API和示例，而非临时封装的代码。
首先遵循现有仓库的模式（导入方式、启动器风格、目录结构、环境变量处理）。
对于与版本相关的行为，在给出明确指导前先查阅发布说明和API参考文档。
优先参考Go专属的ADK文档；若某功能仅在其他SDK文档中有说明，需明确指出这一点。
保持Agent名称唯一，切勿使用
```
user
```
作为Agent名称。
使用简洁的
```
Description
```
字段，确保任务委托和工具选择的可靠性。
除非用户明确要求生产环境运行时方案，否则将ADK Web视为仅用于开发环境的工具。

Workflow

工作流程

Map task to ADK domain:
- Build, run, deploy, evaluate, safety, components, protocols, or reference.
- Load only the relevant sections from references/llms-index.md.
Confirm execution style:
- Launcher-first app (
```
cmd/launcher
```
  ,
```
cmd/launcher/full
```
  ) or embedded runtime (
```
runner.Run
```
  loop).
- Local dev UI, CLI-only, or REST/API server flow.
Build the first working agent:
- ```
llmagent.New(llmagent.Config{...})
```
  with a concrete model (commonly
```
gemini.NewModel(...)
```
  ).
- Add minimum viable
```
Instruction
```
  ,
```
Description
```
  , and
```
Tools
```
  .
Add tools safely:
- Use
```
functiontool.New(...)
```
  for typed custom tools.
- Use
```
geminitool.GoogleSearch{}
```
  or other ADK/native integrations only when needed.
- For sensitive tools, apply confirmations, auth, and policy callbacks.
Wire stateful execution:
- Sessions via
```
session.Service
```
  (often
```
session.NewInMemoryService()
```
  for local dev).
- Add
```
memory.Service
```
  only when cross-session retrieval is required.
- Add state/context/artifacts management only when required by the workflow.
Apply control points:
- Use callbacks (
```
Before/After Model
```
  ,
```
Before/After Tool
```
  , agent callbacks) for logging, caching, guardrails, and overrides.
- Prefer plugins for reusable security policy enforcement.
Scale composition:
- Use workflow agents for deterministic orchestration (
```
sequentialagent
```
  ,
```
parallelagent
```
  ,
```
loopagent
```
  ).
- Use multi-agent delegation (descriptions + transfer behavior) only when specialization is clear.
Select runtime/deployment posture:
- Local dev: CLI/Web/API.
- Production: deployment target + observability + safety posture.
Verify behavior end-to-end:
- Validate happy-path conversation, tool errors, callbacks, session resume/rewind behavior, and evaluation criteria.

将任务映射到ADK领域:
- 构建、运行、部署、评估、安全、组件、协议或参考文档。
- 仅从references/llms-index.md加载相关章节。
确认执行风格:
- 以启动器为主的应用（
```
cmd/launcher
```
  、
```
cmd/launcher/full
```
  ）或嵌入式运行时（
```
runner.Run
```
  循环）。
- 本地开发UI、纯CLI或REST/API服务器流程。
构建首个可运行的Agent:
- 使用具体模型（通常为
```
gemini.NewModel(...)
```
  ）调用
```
llmagent.New(llmagent.Config{...})
```
  。
- 添加最基础的
```
Instruction
```
  、
```
Description
```
  和
```
Tools
```
  。
安全添加工具:
- 使用
```
functiontool.New(...)
```
  创建类型化自定义工具。
- 仅在需要时使用
```
geminitool.GoogleSearch{}
```
  或其他ADK/原生集成工具。
- 对于敏感工具，添加确认、认证和策略回调。
配置有状态执行:
- 通过
```
session.Service
```
  实现会话（本地开发通常使用
```
session.NewInMemoryService()
```
  ）。
- 仅当需要跨会话检索时才添加
```
memory.Service
```
  。
- 仅当工作流需要时才添加状态/上下文/工件管理。
应用控制节点:
- 使用回调（模型执行前后、工具调用前后、Agent回调）实现日志记录、缓存、安全防护和逻辑覆盖。
- 优先使用插件实现可复用的安全策略 enforcement。
扩展组合能力:
- 使用工作流Agent实现确定性编排（
```
sequentialagent
```
  、
```
parallelagent
```
  、
```
loopagent
```
  ）。
- 仅当职责划分明确时，才使用多Agent委托（描述+转移行为）。
选择运行时/部署方式:
- 本地开发：CLI/Web/API。
- 生产环境：部署目标+可观测性+安全策略。
端到端验证行为:
- 验证正常对话流程、工具错误、回调、会话恢复/回退行为以及评估标准。

Output expectations

输出要求

Provide exact Go imports, runnable snippets, and command lines that match the chosen runtime mode.
Call out version-sensitive behavior if the user targets older ADK tags.
Mention the relevant ADK doc section when guidance comes from
```
llms-index
```
categories beyond core Go quickstart pages.
Prefer small, testable incremental changes over large rewrites.

提供与所选运行时模式完全匹配的Go导入语句、可运行代码片段和命令行指令。
若用户针对旧版ADK标签，需指出与版本相关的行为差异。
当指导内容来自
```
llms-index
```
中核心Go快速入门页面以外的分类时，需提及对应的ADK文档章节。
优先推荐小型、可测试的增量变更，而非大规模重写。

References

参考文档

Quickstart and launcher baseline: references/quickstart.md
Core APIs and agent config: references/core-primitives.md
Tools, callbacks, and guardrails: references/tools-and-guardrails.md
Runtime modes, examples, and A2A: references/runtime-and-examples.md
Required ADK source map (
```
llms.txt
```
mirror): references/llms-index.md

快速入门与启动器基准：references/quickstart.md
核心API与Agent配置：references/core-primitives.md
工具、回调与安全防护：references/tools-and-guardrails.md
运行时模式、示例与A2A：references/runtime-and-examples.md
必选ADK源映射（
```
llms.txt
```
镜像）：references/llms-index.md