自学教程

Claude Agent SDK 提示词管理

Claude Code 教程

简介

提示词（Prompt）是控制 Claude Agent 行为的核心，SDK 中将提示词分为两大块：system 系统提示词 + messages 用户对话历史。
提示词管理不是简单写一段文字，而是模板化、版本化、可动态渲染、可安全校验的工程能力，适合 SaaS、多租户、子代理场景。

核心概念

  • System：全局角色、规则、约束、输出格式，在整个会话生效，不会随对话被覆盖
  • Messages：用户/助手历史对话，包含 tool_use / tool_result，保存会话上下文
  • Prompt Template：提示词模板，预留变量占位符，运行时注入参数

区分：Claude Code 使用 CLAUDE.md 固定项目规则；SDK 提示词由代码动态传入，支持按租户/任务/子代理动态切换。

前置准备

  1. Python3.10+ / Node.js18+
  2. SDK：anthropic / @anthropic-ai/sdk
  3. 模板工具可选：Python jinja2；TS handlebars

提示词分层设计（推荐规范）

分层编写 system 提示词，结构清晰，方便维护，按顺序编排：

  1. 角色定义：Agent 身份、职责
  2. 行为规则：能做什么、禁止做什么
  3. 工具约束：工具调用规范、错误处理规则
  4. 输出格式：Markdown / JSON，固定返回结构
  5. 边界限制：最大工具调用轮次、拒绝回答的场景

示例 system 分层模板

【角色】你是代码审查智能体。
【职责】对源码进行安全漏洞检查，输出漏洞等级与修复建议。
【规则】
1. 只分析提供的代码，不要编造不存在文件。
2. 发现漏洞必须标记等级：高危/中危/低危。
【工具】你可以调用 get_file 读取源码文件。
【输出】使用JSON格式返回，字段：level, desc, suggest。
【限制】最多连续调用工具3次。

模板渲染实战

Python Jinja2 模板示例

from jinja2 import Template

# 模板字符串，支持变量
system_template = Template("""
【角色】{{agent_role}}
【任务】对{{language}}代码做安全审计
【约束】最多调用工具 {{max_tool_round}} 次
【输出格式】{{output_format}}
""")

# 运行时渲染变量
system_prompt = system_template.render(
    agent_role="代码安全审计助手",
    language="Python",
    max_tool_round=3,
    output_format="JSON"
)

# 传入SDK
from anthropic import Anthropic
client = Anthropic()
resp = client.messages.create(
    model="claude-3-5-sonnet-latest",
    max_tokens=1024,
    system=system_prompt,
    messages=[{"role":"user","content":"审计下面代码..."}]
)

TypeScript Handlebars 模板示例

import Handlebars from "handlebars";
import Anthropic from "@anthropic-ai/sdk";

const systemSource = `
【角色】{{agent_role}}
【任务】对{{language}}代码做安全审计
【约束】最多调用工具 {{max_tool_round}} 次
【输出格式】{{output_format}}
`;
const template = Handlebars.compile(systemSource);
const systemPrompt = template({
  agent_role: "代码安全审计助手",
  language: "TypeScript",
  max_tool_round: 3,
  output_format: "JSON"
});

const anthropic = new Anthropic();
const res = await anthropic.messages.create({
  model: "claude-3-5-sonnet-latest",
  max_tokens: 1024,
  system: systemPrompt,
  messages: [{ role: "user", content: "审计代码..." }],
});

提示词版本管理

多租户、迭代场景下，提示词需要版本控制，方便灰度、回滚、A/B测试。

数据库表设计 prompt_template

CREATE TABLE prompt_template (
  id BIGINT PRIMARY KEY AUTO_INCREMENT,
  template_key VARCHAR(64) NOT NULL COMMENT '模板唯一标识，如 code_review',
  version VARCHAR(32) NOT NULL COMMENT '版本号 v1.0',
  tenant_id VARCHAR(64) NULL COMMENT '租户ID，NULL代表全局模板',
  template_content TEXT NOT NULL,
  variables JSON COMMENT '模板支持的变量列表',
  status TINYINT DEFAULT 1 COMMENT '1启用，0禁用',
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  UNIQUE KEY uk_key_version_tenant (template_key, version, tenant_id)
);

使用逻辑：

  1. 按 template_key + version + tenant_id 读取模板
  2. 全局模板：tenant_id 为 NULL；租户自定义模板会覆盖全局模板
  3. 上线新版本，保留旧版本；出现问题可快速回滚至上一版本

子代理提示词隔离

主代理、不同子代理使用独立 system 提示词，互不干扰：

  • 主代理：任务拆分、汇总结果
  • 子代理A：代码静态扫描
  • 子代理B：文档摘要

每个子代理调用SDK时传入自己独立的 system，不要共用一套提示词。

提示词安全防护（重点：防提示注入）

提示注入：用户输入包含恶意指令，覆盖原有 system 规则，劫持Agent行为。
防护手段：

  1. 用户输入隔离：把用户传入内容放在单独的用户消息块，不要直接拼接进 system 提示词。

❌ 错误：system = system_template + user_input
✅ 正确：system 固定模板；用户内容放在 messages user 块

  1. 输入内容转义：模板渲染时，对用户输入做转义，防止用户伪造模板标记
  2. 指令边界标记：使用分隔符包裹用户原始内容
==== 用户原始输入开始 ====
{{user_content}}
==== 用户原始输入结束 ====
  1. 输出校验：Agent返回结果做格式校验，不符合预期结构直接丢弃

Token 开销控制

System 提示词会持续占用输入token，每次请求都会计费。优化策略：

  1. 精简 system：删除冗余描述，保留必要规则
  2. 复用短模板：子代理任务简单时，使用简短system，降低成本
  3. 缓存渲染后的提示词：静态模板渲染结果缓存，避免重复渲染
  4. 长规则拆分：超长规则不要全部放入system，可以摘要放入system，完整文档通过工具读取

提示词A/B测试

同一个任务，多套提示词版本对比效果：

  1. 随机分配用户/会话使用不同版本模板
  2. 记录指标：任务成功率、工具调用次数、token消耗、用户满意度
  3. 根据指标，选择效果最好的模板作为正式版本

示例：会话绑定模板版本

session_id: s001, prompt_version: v1.0
session_id: s002, prompt_version: v1.1

提示词缓存策略

  • 静态模板（无动态变量）：渲染一次后存入Redis缓存，减少数据库读取
  • 租户自定义模板：缓存增加tenant_id隔离，不同租户模板分开缓存
  • 缓存过期时间：5~30分钟，模板更新后主动清理对应缓存key

常见问题

Q：system提示词可以在会话中途修改吗？

A：SDK每次调用 messages.create 可以传入不同 system。修改后仅对本次请求生效，不会改变历史消息。如果中途切换system，后续Agent行为会变化，谨慎使用。

Q：system 和 user 消息，哪个优先级更高？

A：用户消息优先级更高，存在提示注入风险，所以必须做好输入隔离。

Q：多租户场景，租户可以自定义提示词吗？

A：可以。在数据库存储租户自定义模板，渲染后传入system；建议增加长度上限和内容安全审核，防止租户编写高危提示词。

Q：工具调用场景，提示词需要额外增加什么规则？

A：在system增加工具调用约束：最大工具调用轮次、工具参数校验规则、工具返回错误如何处理。

最佳实践

  1. 提示词模板和业务代码分离，存在数据库/文件，不要硬编码在代码内。
  2. 分层编写system提示词，职责清晰，便于维护。
  3. 用户输入永远不要直接拼接进system，防范提示注入攻击。
  4. 模板增加版本号，支持回滚和A/B测试。
  5. 子代理使用独立system提示词，区分各自任务目标。
  6. 监控：记录模板版本对应的失败率、token消耗，持续优化提示词。

小结

提示词管理核心：模板化渲染、版本控制、租户隔离、防提示注入。将system提示词抽离成可配置模板，支持动态变量注入；严格隔离用户输入，防止注入劫持Agent。子代理使用独立提示词，配合A/B测试持续优化提示词效果。

标签：

0 条笔记