Sira AI

主题

模板变量 ​

模板变量允许您在系统提示词中动态插入上下文信息，实现个性化的 AI 交互。

什么是模板变量 ​

模板变量使用 {{variable_name}} 格式，在 Agent 执行时会被实际值替换。

示例：

系统提示词配置：

你是客服助手，当前用户是 {{user_name}}，来自 {{user_department}}。

实际执行时：

你是客服助手，当前用户是张三，来自研发部。

可用变量列表 ​

用户信息 ​

变量说明示例值可用平台
{{user_id}}用户唯一标识zhangsan企业微信、Web（如果已登录）
{{user_name}}用户姓名张三企业微信
{{user_department}}所属部门研发部企业微信
{{user_email}}用户邮箱zhangsan@company.com企业微信、Web（如果已登录）

注意：企业微信需要配置 corp_secret 才能获取完整用户信息。

会话信息 ​

变量说明示例值
{{session_id}}会话IDsess_abc123
{{message_count}}本次会话消息数5
{{message_content}}当前用户消息内容帮我查询订单状态
{{message_type}}消息类型text / image / mixed
{{message_id}}消息IDmsg_123456

应用信息 ​

变量说明示例值
{{application_id}}应用IDapp_uuid
{{application_name}}应用名称技术支持 Bot
{{application_type}}应用类型wework_aibot / webclient / api_service
{{platform}}平台标识wework / web / api

编排器信息 ​

变量说明示例值
{{orchestrator_id}}编排器IDorch_uuid
{{orchestrator_name}}编排器名称技术支持编排器
{{orchestrator_type}}编排类型single / supervisor / collaboration
{{agent_count}}参与的 Agent 数量3
{{current_agent}}当前执行的 Agent 名称技术专家

Agent 信息 ​

变量说明示例值
{{agent_id}}Agent IDagent_uuid
{{agent_name}}Agent 名称tech_expert
{{agent_display_name}}Agent 显示名称技术专家
{{agent_description}}Agent 描述负责解答技术问题
{{model_name}}使用的 AI 模型GPT-4o
{{temperature}}温度参数0.7
{{tools_available}}可用工具列表Context7, Weather
{{knowledge_bases}}关联知识库技术文档, 产品手册

多模态信息 ​

变量说明示例值
{{has_images}}是否包含图片true / false
{{images_count}}图片数量2

时间信息 ​

变量说明示例值
{{current_time}}当前时间2025-10-14 14:30:00
{{timezone}}时区Asia/Shanghai

企业微信特定 ​

变量说明示例值
{{corp_id}}企业IDww1234567890abcdef
{{corp_name}}企业名称XX科技有限公司
{{chat_type}}聊天类型single / group

Web 客户端特定 ​

变量说明示例值
{{browser}}浏览器信息Chrome 120
{{ip_address}}用户IP192.168.1.100
{{device_type}}设备类型desktop / mobile / tablet

使用场景 ​

场景 1：个性化问候 ​

系统提示词：

你是智能客服助手。

当前用户信息：
- 姓名：{{user_name}}
- 部门：{{user_department}}
- 邮箱：{{user_email}}

请用友好的语气回答 {{user_name}} 的问题。

效果：

用户："你好"
AI："你好，张三！我是智能客服助手，很高兴为研发部的您服务。有什么可以帮助您的吗？"

场景 2：VIP 用户特殊服务 ​

系统提示词：

你是高级客服。当前用户：{{user_name}} ({{user_email}})

注意事项：
- 提供专业、详细的解答
- 优先响应速度
- 必要时提供专属联系方式

效果：AI 会以更专业的态度服务 VIP 用户。

场景 3：部门特定知识 ​

系统提示词：

你是企业助手。

当前用户部门：{{user_department}}

针对不同部门提供定制化服务：
- 研发部：技术问题、开发工具、API 文档
- 销售部：产品资料、客户案例、报价方案
- 人事部：员工福利、考勤制度、培训课程

可用知识库：{{knowledge_bases}}
可用工具：{{tools_available}}

效果：根据用户部门自动调整回答内容和使用的知识库。

场景 4：时间敏感提醒 ​

系统提示词：

你是日程助手。

当前时间：{{current_time}}
时区：{{timezone}}

任务：
- 提醒用户今天的会议安排
- 根据当前时间判断是"早上好"、"下午好"还是"晚上好"
- 工作时间（9:00-18:00）提供工作相关帮助
- 非工作时间建议明天处理

效果：

用户："今天有什么安排？"
AI："早上好！现在是 2025-10-14 09:30，您今天有以下安排：..."

场景 5：协作状态提示 ​

系统提示词：

你是{{agent_display_name}}，在{{orchestrator_type}}编排中工作。

当前状态：
- 编排器：{{orchestrator_name}}
- 协作 Agent 数量：{{agent_count}}
- 当前执行者：{{current_agent}}

你的职责：{{agent_description}}

效果：在多 Agent 协作时，每个 Agent 知道自己的角色和其他 Agent 的存在。

场景 6：多模态内容处理 ​

系统提示词：

你是图片分析专家。

用户消息：{{message_content}}
是否包含图片：{{has_images}}
图片数量：{{images_count}}

处理策略：
- 如果有图片，先分析图片内容
- 结合用户的文字问题给出答案
- 如果图片模糊，提示用户重新发送

效果：AI 根据是否有图片调整回答策略。

场景 7：平台差异化服务 ​

系统提示词：

你是客服助手。

当前平台：{{platform}}
应用类型：{{application_type}}

平台差异化：
- 企业微信 (wework)：使用正式、专业的语气
- Web 聊天 (web)：使用友好、轻松的语气
- API 调用 (api)：返回结构化、简洁的数据

会话ID：{{session_id}}（用于追踪）

效果：根据不同平台调整 AI 的回复风格。

条件判断 ​

虽然模板变量本身不支持条件语句，但您可以在系统提示词中引导 AI 根据变量值做出判断：

示例：

你是智能助手。

用户部门：{{user_department}}
用户邮箱：{{user_email}}

服务策略：
- 如果用户部门是"管理层"，提供高级别的数据分析和决策支持
- 如果用户部门是"技术部"，专注于技术细节和代码示例
- 如果用户部门是"销售部"，提供客户案例和市场数据
- 如果用户邮箱包含"@vip"，提供优先级服务

AI 会智能理解这些规则并相应调整服务。

最佳实践 ​

1. 只使用必要的变量 ​

❌ 不好的做法：

用户ID: {{user_id}}
用户名: {{user_name}}
部门: {{user_department}}
邮箱: {{user_email}}
会话ID: {{session_id}}
消息数: {{message_count}}
编排器: {{orchestrator_name}}
Agent: {{agent_name}}
模型: {{model_name}}
...（罗列所有变量）

✅ 好的做法：

你是客服助手，当前用户：{{user_name}} ({{user_department}})

请提供专业、友好的服务。

2. 提供默认值说明 ​

✅ 好的做法：

你是助手。

用户信息：
- 姓名：{{user_name}}（如果为空，使用"朋友"称呼）
- 部门：{{user_department}}（如果为空，使用通用服务）

这样 AI 知道当变量为空时如何处理。

3. 变量验证 ​

某些变量在特定平台可能不可用：

变量企业微信 AI BotWeb 聊天API Service
{{user_name}}✅⚠️ 需登录⚠️ 需认证
{{user_department}}✅❌❌
{{browser}}❌✅❌
{{corp_name}}✅❌❌

建议在系统提示词中考虑变量可能为空的情况。

4. 敏感信息处理 ​

避免在提示词中直接暴露敏感信息：

❌ 不好的做法：

用户邮箱：{{user_email}}
用户IP：{{ip_address}}

请将用户信息记录到日志...

✅ 好的做法：

当前用户：{{user_name}}

注意：
- 不要在回复中包含用户的邮箱或IP
- 敏感信息仅用于内部识别，不要展示给用户

5. 测试变量替换 ​

创建 Agent 后，使用 Orchestrator 的测试功能验证变量是否正确替换：

  1. 在系统提示词中使用变量
  2. 点击 Orchestrator 的"测试"按钮
  3. 发送测试消息
  4. 检查 AI 回复是否包含正确的上下文信息

常见问题 ​

Q1: 变量没有被替换怎么办？ ​

检查清单：

  1. ✅ 变量名拼写是否正确（区分大小写）
  2. ✅ 变量格式是否正确（必须是 {{variable}}，不是 {variable} 或 $variable）
  3. ✅ 该变量在当前平台是否可用（参考上面的可用性表格）
  4. ✅ 如果是企业微信特定变量，是否配置了 corp_secret

调试方法： 在系统提示词中临时添加：

[DEBUG] 用户名={{user_name}}, 部门={{user_department}}

查看 AI 回复中是否有替换后的值。

Q2: 可以自定义变量吗？ ​

目前不支持自定义模板变量。可用变量由系统预定义。

替代方案： 通过 platform_context 在 API 调用时传递额外数据，这些数据会保存在 metadata 中，虽然无法直接在提示词中使用变量语法，但 AI 可以通过上下文访问。

Q3: 变量值为空时会显示什么？ ​

  • 如果变量值为 None 或空字符串，会显示空白
  • 不会显示 {{variable_name}}（已替换为空）

建议：在系统提示词中说明如何处理空值：

用户姓名：{{user_name}}（如为空，称呼"您"）

Q4: 可以在变量中使用条件吗？ ​

不可以。模板变量只支持简单的值替换，不支持 {{if user_name}}...{{endif}} 这样的条件语法。

替代方案： 在系统提示词中用自然语言描述条件逻辑，让 AI 自己判断：

如果 {{user_department}} 是"技术部"，专注技术细节；
如果是"销售部"，提供业务案例。

Q5: 变量值会实时更新吗？ ​

是的，每次 AI 执行时都会重新计算所有变量值：

  • {{current_time}} - 总是当前时间
  • {{message_count}} - 当前会话的实时消息数
  • {{user_name}} - 如果用户信息变更（如改名），会获取最新值

Q6: 可以在哪些地方使用模板变量？ ​

目前只支持在 Agent 的系统提示词 中使用模板变量。

不支持的地方：

  • ❌ Agent 名称、描述
  • ❌ Orchestrator 配置
  • ❌ Application 配置

Q7: 图片 URL 可以作为变量吗？ ​

图片 URL 不作为模板变量提供，但会通过 multimodal_content 直接传递给支持 Vision 的 AI 模型。

您可以使用 {{has_images}} 和 {{images_count}} 来检测是否有图片。

下一步 ​

Apache-2.0 Licensed

Copyright © 2024 Sira AI Inc.