感知环境

智能体通过运行时状态注入感知不断变化的环境：在每次推理之前，随对话变化的信息（当前时间、计划任务、上下文用量、重复的工具报错）会以 HintBlock 的形式注入上下文，由 Agent(...) 的 injection_config 参数控制。注入覆盖四个维度，各自有独立的触发时机：

维度	注入内容	触发时机
时间	当前时间与时区	上下文中没有时间记录（首次回复，或上下文压缩刚结束），或距上次记录的时间超过 `time_interval` 小时
计划任务	进行中与待处理任务的数量，并提醒调用 `TaskList`	存在未完成任务，且上下文中既没有任务相关的工具调用（例如已被压缩掉），也没有此前的任务注入
上下文用量	当前输入 token 数与压缩阈值；开启自主压缩且没有进行中的任务时，还会告知可以立即压缩	回复的第一轮迭代中，输入 token 数进入压缩阈值前 `context_buffer_ratio` 的缓冲区，让智能体预知压缩即将发生
工具报错	提醒停止重试，改换思路	最近连续 `tool_retries_limit` 次工具结果都失败，且来自同一个工具、同一份参数（参数规范化后比较，键顺序不同不影响判定）；中间出现一次成功即重新计数

其中上下文用量的缓冲区 context_buffer_ratio 定义在上下文配置中，其余三个维度由 InjectionConfig 控制。

注入机制

每个注入字段包装为 <key>value</key>，拼接后填入 template（默认是一个 <system-reminder> 包裹模板）。一条典型的注入提示如下：

注入提示示例

<system-reminder>Treat the following as the ground truth at this point of the conversation. Anything stated earlier is outdated, and a later reminder, if any, supersedes this one:
<current-time>2026-07-22T10:30:00</current-time>
<timezone>Asia/Shanghai</timezone>
<tasks>You have 1 in-progress tasks and 2 pending tasks. Use `TaskList` to view them if you don't know.</tasks>
<tool-error>The last 3 calls to 'Bash' with the same arguments all failed. Stop retrying the same call as-is, check the error message and try a different approach.</tool-error>
</system-reminder>

有三个设计要点值得了解：

注入不是临时的：它会追加到持久化上下文中，让智能体感知时间的流逝和每一步做了什么，建立时间感。
提示以 HintBlock 形式附加，而不是修改系统提示，因此提示词缓存依然有效，同时智能体持续感知变化的状态。
只有会话中会变化的信息才会被注入。固定信息（智能体身份、长期指令）应写入系统提示。

当注入发生且 emit_hint_event 开启时，reply_stream 会额外产出一个 HintBlockEvent，方便前端渲染注入的提示。

配置注入

向智能体构造函数传入 InjectionConfig 即可调整注入行为：

from agentscope.agent import Agent, InjectionConfig
from agentscope.model import DashScopeChatModel
from agentscope.credential import DashScopeCredential

agent = Agent(
    name="my_agent",
    system_prompt="你是一个有帮助的助手。",
    model=DashScopeChatModel(
        credential=DashScopeCredential(api_key="YOUR_API_KEY"),
        model="qwen-max",
    ),
    injection_config=InjectionConfig(
        timezone="Asia/Shanghai",  # 注入该时区的时间
        time_interval=1.0,         # 每小时至多刷新一次时间
    ),
)

InjectionConfig 的字段如下：

字段	默认值	说明
`inject_runtime_state`	`True`	总开关；设为 `False` 完全关闭运行时状态注入
`timezone`	`"UTC"`	注入时间的时区，遵循标准时区数据库格式（如 `"Asia/Shanghai"`）
`time_format`	`"%Y-%m-%dT%H:%M:%S"`	注入时间的格式；必须包含日期部分，以便记录的时间能还原为完整时间戳
`time_interval`	`0.5`	距记录时间的最小间隔（小时），超过后触发新的时间注入
`tool_retries_limit`	`3`	同一个工具调用连续失败多少次后注入工具报错提示，最小值为 `3`
`tool_retries_hint`	上方示例中的文案	工具报错提示的模板，支持 `{tool_name}`（失败的工具名）与 `{count}`（连续失败次数）两个占位符
`template`	`<system-reminder>` 包裹模板	包裹注入字段的模板，必须包含 `{runtime_state}` 占位符
`injection_source`	`{"label": "System", "sublabel": "Runtime State"}`	注入的 `HintBlock` 的 `source`，用于在扫描上下文时识别智能体此前的注入
`task_tool_names`	`TaskCreate`、`TaskGet`、`TaskList`、`TaskUpdate`	任务相关的工具名；它们的调用出现在上下文中，说明智能体已知晓任务，从而抑制任务注入
`extra_fields`	`{}`	附加到每次注入的自定义字段（参见注入自定义字段）
`emit_hint_event`	`True`	注入发生时是否产出 `HintBlockEvent`

InjectionConfig 上的 context_buffer_ratio 已废弃，请改用上下文配置中的同名字段。此处仍然可以传入，会覆盖上下文配置中的取值，同时发出 DeprecationWarning。

注入自定义字段

除内置维度外，extra_fields 可以注入开发者自定义的信息，例如传感器读数、部署元数据：

from agentscope.agent import InjectionConfig

injection_config = InjectionConfig(
    extra_fields={
        "battery-level": "78%",       # 注入为 <battery-level>78%</battery-level>
        "location": "杭州办公室",
    },
)

自定义字段会附加到每一次注入中，但自身不会触发注入：只有当时间、任务、上下文用量或工具报错维度触发时才会一并注入。

自定义模板

template 字段控制注入内容呈现给大模型的方式。它必须包含 {runtime_state} 占位符，占位符会被替换为拼接后的 <key>value</key> 字段：

from agentscope.agent import InjectionConfig

injection_config = InjectionConfig(
    template=(
        "[运行时更新] 以下内容反映当前环境：\n"
        "{runtime_state}"
    ),
)

快速开始

核心模块

智能体即服务

其他

注入机制

配置注入

注入自定义字段

自定义模板

​注入机制

​配置注入

​注入自定义字段

​自定义模板

注入机制

配置注入

注入自定义字段

自定义模板