Strands Agents SDK 术语锁定规范:一份面向 Agent 与 LLM 的文档写作与命名指南
Strands Agents SDK 术语锁定规范:一份面向 Agent 与 LLM 的文档写作与命名指南
本指南以 .agents/references/terminology.md 为骨架,讲解 Strands Agents(harness-sdk 仓库内 Python/TypeScript 双语言 SDK)在用户文档与代码评审中强制执行的"一词一义"术语体系:从 agent loop、tool calling 到 memory、hooks、graph、swarm、interrupt 等核心概念的唯一标准命名,以及跨语言类名映射、frontmatter 内容类型标签的选用规则。读完本文,你将能写出术语统一、便于搜索引擎与 LLM 检索引用的 Strands 技术文档,并在遇到新概念时按既定流程提案新增标准术语。
为什么需要"术语锁定":One concept, one term
terminology.md 开篇即给出该文件的定位:"One concept, one term. Never vary for stylistic reasons. This file is the canonical source. Reference it during writing and review." —— 一个概念只允许一个规范术语,不得因文风喜好而变体;该文件是权威来源(canonical source),写作与评审时必须随时对照。
在面向开发者、搜索引擎与 LLM 的文档体系中,术语漂移(terminology drift)会带来三重代价:
- 检索失败:读者用规范词搜索,文档却用了同义变体,导致命中率下降;
- Agent/LLM 理解偏差:同一概念在代码中出现
ConversationManager、文档中出现 "session handler"、示例中出现 "context manager",会让模型难以建立稳定的语义映射; - 代码与文档脱节:SDK 类名是事实上的规范,文档如果另造名词,就会在"API 名称 ↔ 用户概念"之间产生断裂。
该文件正是为了在写作与评审环节消除这些代价,把"术语"变成一种可审计的工程约束。下文按该文件的小节结构逐一展开,并补充仓库源码中的对应实现作为佐证。
核心 SDK 概念的标准术语表
下表完整继承原文档的 Core SDK Concepts 部分,并标注了每条术语在仓库源码中的对应实现位置,便于写作时交叉验证:
| 概念 | 规范术语 | 禁用变体 | 源码佐证 |
|---|---|---|---|
| SDK 的推理循环 | agent loop | reasoning cycle, inference loop, think-act cycle | event_loop_cycle 定义于 strands-py/src/strands/event_loop/event_loop.py,Agent 通过 _run_loop 驱动(见 strands-py/src/strands/agent/agent.py) |
| Agent 调用工具 | tool calling | function calling, tool invocation, tool execution, function invocation | 工具调用发生在 agent loop 的 cycle 中,与 AgentTool 类型(strands-py/src/strands/types/tools.py)对应 |
| 模型生成文本 | model response | LLM output, AI response, generation, completion | Model 协议的 generate 类方法返回响应(如 strands-py/src/strands/models/bedrock.py) |
| 开发者定义、Agent 可调用的函数 | tools | functions, actions, capabilities, skills(SDK 语境下) | Python 端由 @tool 装饰器声明(strands-py/src/strands/tools/decorator.py) |
| strands-agents-tools 预置工具 | community tools | built-in tools, standard tools, default tools | 与 strands-agents-tools 包对应,pip install strands-agents strands-agents-tools 后可直接使用 |
| MCP 协议集成工具 | MCP tools | MCP functions, MCP integrations, protocol tools | MCP 客户端位于 strands-py/src/strands/tools/mcp/ |
| 配置使用哪个模型 | model provider | model backend, LLM provider, inference provider | 各类 provider 类实现见 strands-py/src/strands/models/ 与 strands-ts/src/models/ |
| 跨轮次维持对话(面向用户的概念) | session management | context persistence, memory, conversation history | 用户侧概念,文档中应使用"session management" |
| 实现会话管理的 SDK 类 | conversation manager | session handler, context manager | Python:ConversationManager(strands-py/src/strands/agent/conversation_manager/conversation_manager.py);TypeScript:strands-ts/src/conversation-manager/conversation-manager.ts |
| 跨会话可被 Agent 回忆的持久知识 | memory(或 long-term memory) | knowledge store, recall, persistent memory | MemoryEntry 等类型定义于 strands-py/src/strands/memory/types.py |
| 实现记忆管理的 SDK 类 | memory manager | knowledge store, recall, memory store, knowledge base | Python:strands-py/src/strands/memory/memory_manager.py;TypeScript:strands-ts/src/memory/memory-manager.ts |
| 承载记忆内容的 SDK 类 | memory store | knowledge store, recall | MemoryStore 协议定义于 strands-py/src/strands/memory/types.py |
| 运行时控制 Agent 行为 | hooks | middleware, interceptors, callbacks(hooks 为 Strands 特有术语) | Python 事件与注册器:strands-py/src/strands/hooks/events.py、strands-py/src/strands/hooks/registry.py |
| 多 Agent 协作 | multi-agent | multi-agent system, agent orchestration, agent coordination | 多 Agent 编排代码位于 strands-py/src/strands/multiagent/ 与 strands-ts/src/multiagent/ |
| Agent 间通信模式 | agents as tools | agent chaining, agent delegation, nested agents | TypeScript 侧 agent-delegation 相关实现见 strands-ts/src/agent/agent-delegation.ts |
| 基于图的 Agent 协调 | graph | workflow graph, DAG, directed graph | strands-ts/src/multiagent/graph.ts |
| 动态 Agent 交接模式 | swarm | swarm intelligence, dynamic routing | Python:strands-py/src/strands/multiagent/swarm.py;TypeScript:strands-ts/src/multiagent/swarm.ts |
| 为等待人类输入而暂停 Agent 执行 | interrupts | human-in-the-loop, breakpoints, pause points | Python:strands-py/src/strands/interrupt.py;TypeScript:strands-ts/src/interrupt.ts |
| 带强制 schema 的 Agent 输出 | structured output | typed output, schema-validated output, Pydantic output | 与 models 子系统的结构化输出能力相关 |
| 观察 Agent 执行 | observability | monitoring, telemetry, instrumentation | Python 遥测实现见 strands-py/src/strands/telemetry/、TypeScript 见 strands-ts/src/telemetry/ |
| 卸载上下文内容的持久存储 | stash | L1 stash, L1, stash layer, context cache | 与 context offloader 相关(Python:strands-py/src/strands/vended_plugins/context_offloader/plugin.py) |
| 检查 Agent 质量 | evaluation | testing, benchmarking, assessment | 仓库 tests_integ 目录中大量集成测试即为评估 Agent 行为的实证 |
| 在生产环境运行 Agent | deployment | hosting, serving, shipping | 参考仓库 site/docs/examples/deploy_to_eks/ 等部署示例 |
| 将 Python 函数变为工具的装饰器 | @tool decorator | tool annotation, tool wrapper | 实现位于 strands-py/src/strands/tools/decorator.py |
关于 "skills" 的重要边界说明
原文档特别以引用块强调:SDK 语境下严禁把 tools 称为 skills,但 skills 一词在指代 agentskills.io 下就存放着 docs-audit、docs-writer、docs-reviewer、pr-writer、strands-review 等面向"在本仓库上工作的 Agent"的编写流程文件——它们是作者流程(authoring procedures),不是 SDK 构造。这一点在写作用词时需要区分语境:
- SDK 文档中:工具一律叫
tools,绝不叫skills; - 仓库协作文档中:
.agents/skills/里的内容可以叫skills。
从源码看,该边界同样存在于运行时:Python 侧存在 vended_plugins/skills/agent_skills.py(strands-py/src/strands/vended_plugins/skills/agent_skills.py),它实现的是"技能文件"这一作者流程构造的加载插件,而非 SDK 工具本身。
基础设施与云服务命名
原文档的 Infrastructure and Cloud 部分规范了第三方服务与部署形态的命名,写作时同样不得随意改写:
| 概念 | 规范术语 | 禁用变体 |
|---|---|---|
| AWS 模型服务 | Amazon Bedrock | AWS Bedrock, Bedrock |
| Anthropic 模型家族 | Claude(带版本,如 Claude Sonnet 4) | Anthropic model, the model |
| OpenAI 模型 API | OpenAI | GPT(当指 provider 时) |
| Ollama 本地推理 | Ollama | local LLM, self-hosted model |
| LiteLLM 代理 | LiteLLM | lite-llm, LiteLLM proxy |
| 容器化部署 | Docker | containerization |
| AWS 无服务器部署 | AWS Lambda | Lambda functions, serverless functions |
| AWS 托管 Agent 平台 | Amazon Bedrock AgentCore | AgentCore, Bedrock Agents (legacy) |
这组术语在仓库中的命名一致性可以在模型实现层得到印证:Python 侧 strands-py/src/strands/models/ 目录按 provider 划分文件(bedrock.py、anthropic.py、openai.py、ollama.py、litellm.py),TypeScript 侧 strands-ts/src/models/ 同样如此。类名与术语表完全对齐,写作时以 provider 名称作为标题、代码中以 SDK 类名出现即可与源码无缝衔接。
模型 Provider 命名与模型无关性约束
原文档在 Model Provider Naming 一节规定了两条写作纪律:
- 文档标题用 provider 名称,代码中用 SDK 类名;
- 框架是模型无关的(model-agnostic)——概念文档中绝不暗示默认 provider。
| Provider | SDK 类(Python) | SDK 类(TypeScript) |
|---|---|---|
| Amazon Bedrock | BedrockModel |
BedrockModel |
| Anthropic(直连) | AnthropicModel |
AnthropicModel |
| OpenAI | OpenAIModel |
OpenAIModel |
| Ollama | OllamaModel |
OllamaModel |
| LiteLLM | LiteLLMModel |
LiteLLMModel |
| 自定义 | Model(protocol/interface) |
Model(interface) |
表中每一行的类名都能在仓库源码中找到对应定义:
- Python:
BedrockModel(strands-py/src/strands/models/bedrock.py)、AnthropicModel(strands-py/src/strands/models/anthropic.py)、OpenAIModel(strands-py/src/strands/models/openai.py)、OllamaModel(strands-py/src/strands/models/ollama.py)、LiteLLMModel(strands-py/src/strands/models/litellm.py); - TypeScript:
BedrockModel(strands-ts/src/models/bedrock.ts)、AnthropicModel(strands-ts/src/models/anthropic.ts)、OpenAIModel(strands-ts/src/models/openai/model.ts); - 自定义 provider:Python 侧通过实现
Model协议/接口接入,TypeScript 侧实现Modelinterface 接入。
"模型无关"这一约束的运行时佐证:自定义 provider 只需实现统一的 Model 协议/接口即可被 agent loop 使用,因此概念文档中若把 Amazon Bedrock 写成默认,就会与源码的模型无关设计相矛盾。
Frontmatter 内容类型标签(Content Type Labels)
针对文档站(仓库 site/ 目录使用 Astro 构建)写作时,每篇文档需要在 frontmatter 中选择一个内容类型标签,用于决定其在站点中的呈现与导航方式。原文档给出四类:
| 类型 | Frontmatter 值 | 描述 |
|---|---|---|
| 学习导向、叙述性 | tutorial |
逐步构建某物的走查式指南 |
| 问题导向、实操性 | howto |
完成某个具体任务的操作步骤 |
| 信息导向、精确性 | reference |
API 文档、参数表、规格说明 |
| 理解导向、概念性 | explanation |
解释事物为何以当前方式运作 |
从仓库 site/src/content/docs/ 的 434 个文档文件(281 个 .mdx)可以看出,该站点对文档有着严格的 frontmatter 元数据要求,正确选用这四类标签直接影响文档在导航与搜索中的归类。写作时判断逻辑可以简化为:教人入门用 tutorial,给人查参数用 reference,教人做具体任务用 howto,解释设计取舍用 explanation。
Python / TypeScript 命名分歧对照
SDK 同一概念在两种语言中的 API 名称并不总是一一对应,写双语对照文档时必须按语言分栏使用正确的名字:
| 概念 | Python | TypeScript |
|---|---|---|
| Agent 初始化事件 | AgentInitializedEvent |
InitializedEvent |
| 多 Agent 插件基类 | HookProvider(protocol) |
MultiAgentPlugin(抽象类,用 extends) |
| 插件基类 | Plugin(class) |
Plugin(interface,用 implements) |
| 工具使用属性 | event.tool_use["name"](dict) |
event.toolUse.name(object) |
| 取消工具 | event.cancel_tool |
event.cancel |
这些差异不是拼写失误,而是两种语言惯用法差异的自然结果:Python 端倾向于 snake_case 的 dict 访问(tool_use["name"]),TypeScript 端则使用 camelCase 的对象属性(toolUse.name)。源码佐证:Python 的 hooks 事件定义于 strands-py/src/strands/hooks/events.py,TypeScript 的 MultiAgentPlugin 抽象类与 Plugin interface 分别位于 strands-ts/src/plugins/ 相关文件。写作时若使用 "Python 标签页 / TypeScript 标签页" 的双栏代码展示,务必按上表在各自标签内使用正确的 API 名称,避免跨语言串名。
如何新增标准术语
原文档最后给出当遇到新概念时的提案流程,这是术语体系的"自举"机制:
- 先查本文件:确认该概念是否已存在规范术语;
- 若不存在,带着理由提案新术语:说明为什么需要新词、为什么选定该词;
- 团队评审后加入本文件:通过评审后写入术语表;
- 更新所有使用非规范变体的既有文档:同步修正历史文档中的漂移用法。
这一流程保证了术语表在项目演进中持续可用:任何新增能力(新工具、新模型、新协调模式)落地文档前,都先经过术语评审,从源头避免新的同义变体进入文档体系。
术语锁定的实战应用建议
结合 terminology.md 与仓库其他协作规范(如根目录 AGENTS.md、CLAUDE.md),在写作与评审中落实术语锁定可以遵循以下操作清单:
- 写作前置检查:动笔前对照术语表,先确定本文涉及的每个概念的唯一规范词,再开始行文;
- 评审检查项:评审时重点检索禁用变体(如 "function calling"、"LLM output"、"knowledge base"、"human-in-the-loop"),命中即视为不合规;
- 双语文档对齐:涉及 Python/TypeScript 双语言的内容,先查"命名分歧对照表"确定各自语言的 API 名称;
- frontmatter 归类:按 tutorial / howto / reference / explanation 四选一填充内容类型标签;
- 新增概念走流程:遇到表中没有的概念,按"查表 → 提案 → 评审 → 回改文档"四步处理,而不是当场即兴造词。
结语
术语锁定(Terminology Lock)看似只是一张命名对照表,实则是面向 Agent 与 LLM 时代的文档基础设施:它让"一个概念一个词"从口号变成可审计的工程约束,让 SDK 类名、用户概念与文档表述三者之间建立稳定映射,从而提升搜索引擎命中率与 Agent 检索引用的可靠性。本仓库中从 event_loop 的 agent loop、ConversationManager 的 session management,到 MemoryManager/MemoryStore 的 memory 体系,再到 @tool 装饰器与 HookProvider/MultiAgentPlugin 等跨语言类,都能在术语表中找到唯一对应词——这正是 strands-agents 双语言 SDK 文档能够保持长期一致性的底层原因。