使用动态变量

通过动态变量,你可以在智能体的系统消息和话术中引用用户名、公司名称等业务信息,也可以注入当前日期或时间,让同一套提示词和话术适用于不同用户和业务场景。

动态变量有两类,值的来源和更新方式不同:

类型值的来源引用示例
自定义变量由你在创建智能体时通过 properties.llm.template_variables 提供。{{user_name}}
系统变量由引擎提供,无需在 template_variables 中声明。目前支持获取当前日期或时间。{{now(timezone="Asia/Shanghai")}}
表格内容超出当前宽度,可横向滚动查看更多列。

前提条件

开始前,请参考使用 RESTful API 实现对话式 AI 引擎,完成与智能体对话的基本逻辑。

本文示例为创建智能体请求中的配置片段。

实现方式

配置自定义变量

在创建智能体请求的 properties.llm.template_variables 中定义变量,再在目标文本中使用 {{变量名}} 引用。变量值必须是字符串。

例如,为不同用户生成个性化开场白:

JSON
{
  "properties": {
    "llm": {
      "template_variables": {
        "user_name": "张三",
        "company_name": "声网科技"
      },
      "greeting_message": "您好,{{user_name}},欢迎联系{{company_name}}。有什么可以帮您?"
    }
  }
}

替换后的开场白为:

Text
您好,张三,欢迎联系声网科技。有什么可以帮您?

使用系统变量

在系统消息或话术中直接使用 {{now(...)}},即可在渲染时注入当前时间。建议显式指定业务所需的时区,并根据需要选择格式:

需求推荐写法
上海当前日期{{now(format='yyyy-MM-dd', timezone='Asia/Shanghai')}}
上海当前时分{{now(format='HH:mm', timezone='Asia/Shanghai')}}
上海当前日期和时间{{now(timezone='Asia/Shanghai')}}
表格内容超出当前宽度,可横向滚动查看更多列。

在系统消息中引用当前时间时,应根据业务需要选择时间精度。精确到秒的时间值变化较频繁,可能降低 LLM 对该位置及后续提示词的缓存复用率。

如果业务只需要知道当天日期,建议使用 {{now(format='yyyy-MM-dd', timezone='Asia/Shanghai')}}。仅在需要判断具体时刻时使用时分或秒级格式。时区应按业务所在地显式指定。

例如,在上面的客服场景中,将用户姓名、公司名称和上海当前日期组合到系统消息中,并在开场白、失败话术和静默话术中引用当前时间:

JSON
{
  "properties": {
    "llm": {
      "template_variables": {
        "user_name": "张三",
        "company_name": "声网科技"
      },
      "system_messages": [
        {
          "role": "system",
          "content": "你是{{company_name}}的客服,正在为{{user_name}}提供服务。上海今天的日期是{{now(format='yyyy-MM-dd', timezone='Asia/Shanghai')}}。"
        }
      ],
      "greeting_message": "您好,{{user_name}},欢迎联系{{company_name}}。当前北京时间为{{now(format='HH:mm', timezone='Asia/Shanghai')}},有什么可以帮您?",
      "failure_message": "抱歉,{{user_name}},暂时无法处理您的请求。当前北京时间为{{now(format='HH:mm', timezone='Asia/Shanghai')}},请稍后重试。"
    },
    "parameters": {
      "silence_config": {
        "action": "speak",
        "timeout_ms": 10000,
        "content": "{{user_name}},当前北京时间为{{now(format='HH:mm', timezone='Asia/Shanghai')}},还需要帮助吗?"
      }
    }
  }
}

假设系统消息在上海时间 2026-11-04 14:35:08 渲染,发送给 LLM 的文本为:

Text
你是声网科技的客服,正在为张三提供服务。上海今天的日期是2026-11-04。

如果静默话术在上海时间 14:36:10 触发,播报文本为:

Text
张三,当前北京时间为14:36,还需要帮助吗?

时间何时刷新

系统时间在每次求值时获取,具体规则如下:

  • 系统消息:每次向 LLM 发起请求前重新求值,包括同一会话的后续轮次。
  • 开场白、失败和静默话术:每次渲染话术时取当前时间,静默或失败再次触发时重新取时。
  • 更新、重启或重连:更新生效、重启或重连后再次求值时,使用最新时间。

一次系统消息列表或一次话术渲染中的时间表达式共用同一时刻,再分别换算时区和格式化。例如,同次渲染中的上海时间和纽约时间表示同一时刻。

只输出日期时,也会在目标时区跨日后的下一次求值更新。

变量支持的文本位置

同一个变量可以在多个文本位置引用。当前支持的自定义变量和系统变量均可用于以下位置:

位置字段用途
系统消息properties.llm.system_messages[].content(字符串)为 LLM 提供角色设定、提示词或回答样例
开场白properties.llm.greeting_message配置智能体的问候语文本
失败话术properties.llm.failure_message配置 LLM 调用失败时的提示语
静默话术properties.parameters.silence_config.content在静默超时后,通过 speak 播报文本,或通过 think 将文本交给 LLM
表格内容超出当前宽度,可横向滚动查看更多列。

渲染只替换文本,保留消息角色、文本段顺序和非文本内容。字段的完整定义见 POST 创建对话式智能体。

参考信息

时间函数参数

时间函数支持 format 和 timezone 两个参数。建议写明参数名,分别指定时间格式和业务时区:

参数类型作用默认值
formatString时间的输出格式yyyy-MM-dd HH:mm:ss
timezoneStringIANA 时区名称或别名,如 Asia/Shanghai、America/New_York、UTC引擎运行环境的本地时区
表格内容超出当前宽度,可横向滚动查看更多列。

参数名区分大小写,两个命名参数的顺序不限。常用写法如下:

写法格式与时区
{{now()}}默认格式,引擎运行环境的本地时区
{{now('yyyy-MM-dd')}}只输出日期,引擎运行环境的本地时区
{{now('yyyy-MM-dd', 'Asia/Shanghai')}}第一个参数指定格式,第二个指定时区
{{now(timezone='Asia/Shanghai')}}只指定时区,使用默认格式
{{now(format='yyyy-MM-dd', timezone='Asia/Shanghai')}}通过参数名指定格式和时区
{{now('HH:mm', timezone='Asia/Shanghai')}}第一个参数指定格式,通过 timezone 指定时区
表格内容超出当前宽度,可横向滚动查看更多列。

字符串支持英文单引号或双引号;在 JSON 字符串中使用内层双引号时,需写成 \"。例如:

JSON
{
  "properties": {
    "llm": {
      "greeting_message": "当前北京时间为{{now(timezone=\"Asia/Shanghai\")}}。"
    }
  }
}

仅在省略参数时使用默认值。格式、时区或调用语法不合法时,完整占位符会原样保留,其他变量仍正常替换,也不会阻断智能体启动。例如,{{now(format='HH:mm', timezone='Invalid/Zone')}} 中的时区无效,因此不会替换为本地时间。

常用时间格式

以下示例以 Asia/Shanghai 时区的 2026-11-04 14:35:08.123 为基准:

格式输出示例
yyyy-MM-dd HH:mm:ss(默认)2026-11-04 14:35:08
yyyy-MM-dd2026-11-04
HH:mm14:35
yyyy-MM-dd'T'HH:mm:ss.SSSXXX2026-11-04T14:35:08.123+08:00
表格内容超出当前宽度,可横向滚动查看更多列。

格式标记区分大小写:MM 表示月份,mm 表示分钟;XXX 输出带冒号的时区偏移,零偏移时输出 Z。'T' 为字面量,输出时不带单引号。

替换规则

  • {{now}} 优先使用 template_variables.now;未提供时,使用运行环境本地当前时间和默认格式。{{now()}} 或带参数的 {{now(...)}} 始终调用系统时间函数,不读取 template_variables.now。
  • 变量值只替换一次,不会继续解析其中的其他变量或时间函数。

时间函数仅支持上述四类文本位置,不适用于用户消息或工具请求参数。

相关文档