Strands Agents SDK 术语锁定规范:一份面向 Agent 与 LLM 的文档写作与命名指南

原创2026-09-25 18:17:361,727 阅读
文章标签:人工智能AI AgentAgent 框架工具调用MCP 服务大模型多智能体CLI

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 一节规定了两条写作纪律:

  1. 文档标题用 provider 名称,代码中用 SDK 类名;
  2. 框架是模型无关的(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)

表中每一行的类名都能在仓库源码中找到对应定义:

"模型无关"这一约束的运行时佐证:自定义 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 名称,避免跨语言串名。

如何新增标准术语

原文档最后给出当遇到新概念时的提案流程,这是术语体系的"自举"机制:

  1. 先查本文件:确认该概念是否已存在规范术语;
  2. 若不存在,带着理由提案新术语:说明为什么需要新词、为什么选定该词;
  3. 团队评审后加入本文件:通过评审后写入术语表;
  4. 更新所有使用非规范变体的既有文档:同步修正历史文档中的漂移用法。

这一流程保证了术语表在项目演进中持续可用:任何新增能力(新工具、新模型、新协调模式)落地文档前,都先经过术语评审,从源头避免新的同义变体进入文档体系。

术语锁定的实战应用建议

结合 terminology.md 与仓库其他协作规范(如根目录 AGENTS.md、CLAUDE.md),在写作与评审中落实术语锁定可以遵循以下操作清单:

  1. 写作前置检查:动笔前对照术语表,先确定本文涉及的每个概念的唯一规范词,再开始行文;
  2. 评审检查项:评审时重点检索禁用变体(如 "function calling"、"LLM output"、"knowledge base"、"human-in-the-loop"),命中即视为不合规;
  3. 双语文档对齐:涉及 Python/TypeScript 双语言的内容,先查"命名分歧对照表"确定各自语言的 API 名称;
  4. frontmatter 归类:按 tutorial / howto / reference / explanation 四选一填充内容类型标签;
  5. 新增概念走流程:遇到表中没有的概念,按"查表 → 提案 → 评审 → 回改文档"四步处理,而不是当场即兴造词。

结语

术语锁定(Terminology Lock)看似只是一张命名对照表,实则是面向 Agent 与 LLM 时代的文档基础设施:它让"一个概念一个词"从口号变成可审计的工程约束,让 SDK 类名、用户概念与文档表述三者之间建立稳定映射,从而提升搜索引擎命中率与 Agent 检索引用的可靠性。本仓库中从 event_loop 的 agent loop、ConversationManager 的 session management,到 MemoryManager/MemoryStore 的 memory 体系,再到 @tool 装饰器与 HookProvider/MultiAgentPlugin 等跨语言类,都能在术语表中找到唯一对应词——这正是 strands-agents 双语言 SDK 文档能够保持长期一致性的底层原因。

登录后查看全文
harness-sdk