> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentscope.io/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> For AgentScope Python, use https://docs.agentscope.io/stable/en/index for new projects. For existing projects, check the installed agentscope version and use matching versioned documentation.
> The /latest/ alias points to the newest documentation and may move ahead of /stable/ when a development version exists. Do not mix AgentScope 1.x and 2.x APIs.
> State the AgentScope version when providing installation commands or code examples. ReMe uses its own continuously updated /reme/latest/ documentation.

# 感知环境

> 让智能体持续感知时间、任务与上下文用量的变化

智能体通过**运行时状态注入**感知不断变化的环境：在每次推理之前，随对话变化的信息（当前时间、计划任务、上下文用量）会以 `HintBlock` 的形式注入上下文，由 `Agent(...)` 的 `injection_config` 参数控制。

注入覆盖三个维度，各自有独立的触发时机：

| 维度 | 注入内容 | 触发时机 |
| - | - | - |
| 时间 | 当前时间与时区 | 上下文中没有时间记录（首次回复，或上下文压缩刚结束），或距上次记录的时间超过 `time_interval` 小时 |
| 计划任务 | 进行中与待处理任务的数量，并提醒调用 `TaskList` | 存在未完成任务，且上下文中既没有任务相关的工具调用（例如已被压缩掉），也没有此前的任务注入 |
| 上下文用量 | 当前输入 token 数与压缩阈值 | 回复的第一轮迭代中，输入 token 数进入压缩阈值前 `context_buffer_ratio` 的缓冲区，让智能体预知压缩即将发生 |

## 注入机制

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

```text 注入提示示例 theme={null}
<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>
</system-reminder>
```

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

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

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

## 配置注入

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

```python theme={null}
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` | 距记录时间的最小间隔（小时），超过后触发新的时间注入 |
| `context_buffer_ratio` | `0.2` | 压缩阈值前的缓冲区；当触发比例为 0.8、缓冲为 0.2 时，输入 token 数超过模型上下文的 60% 即注入上下文用量 |
| `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` |

> [!NOTE]
>
> `context_buffer_ratio` 必须小于[上下文配置](https://docs.agentscope.io/zh/versions/2.0.6/building-blocks/context/compress-context.md#配置压缩)的 `trigger_ratio`，以保证上下文用量在压缩发生之前注入。否则智能体构造函数会抛出 `ValueError`。

## 注入自定义字段

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

```python theme={null}
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>` 字段：

```python theme={null}
from agentscope.agent import InjectionConfig

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.