ADK 的 Perseus Context 集成¶

Supported in ADKPython

adk-perseus-context 集成将确定性编译的上下文注入你 ADK 智能体的系统指令中。它由 Perseus 驱动，这是一个开源的上下文编译器：Perseus 在推理时解析 @file、@search 和 @memory 等指令为一个字节稳定的上下文字符串，无需检索索引、无需嵌入、也无需额外的 LLM 往返。一切都在本地运行。

Perseus 是一个上下文编译器，而非记忆或 RAG 后端。如需持久化的跨会话记忆，请搭配其伴侣 Perseus Vault 使用。

使用场景¶

确定性上下文组装：相同的输入始终编译为相同的上下文，构建结果字节级一致，无逐次查询的检索偏差
工作区感知智能体：解析 @file、@include、@search 和 @memory 指令，使智能体能看到当前项目的文件和状态
无索引、本地上下文：无需向量存储、无需嵌入、无需云端。上下文在运行智能体的机器上编译
固定大小的完整覆盖：精确拉取你声明的上下文，而非 top-k 切片

前提条件¶

Python 3.10+
google-adk>=1.14.0
perseus-ctx>=1.0.10（随 adk-perseus-context 自动安装）

安装¶

pip install adk-perseus-context

与智能体一起使用¶

有两种方式注入编译后的 Perseus 上下文。使用插件可在 Runner 中的所有智能体间共享上下文，使用回调则针对单个智能体。source 是指向 .perseus 文件的路径，或以 @perseus 开头的内联字符串。

Runner 全局（插件）¶

from adk_perseus_context import PerseusContextPlugin
from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.runners import Runner
from google.adk.sessions import InMemorySessionService

agent = Agent(
    name="assistant",
    model="gemini-flash-latest",
    instruction="帮助用户。",
)

app = App(
    name="perseus_app",
    root_agent=agent,
    plugins=[PerseusContextPlugin("context.perseus")],
)

runner = Runner(
    app=app,
    session_service=InMemorySessionService(),
)

单个智能体（回调）¶

from adk_perseus_context import perseus_before_model_callback
from google.adk.agents import Agent

agent = Agent(
    name="assistant",
    model="gemini-flash-latest",
    instruction="帮助用户。",
    before_model_callback=perseus_before_model_callback("context.perseus"),
)

无论采用哪种方式，编译后的上下文都会在每次模型调用时通过 ADK 的 LlmRequest.append_instructions 追加到请求的系统指令中。如果 Perseus 不可用或编译失败，请求会继续执行而不注入上下文，并记录一条警告日志（默认 fail_open=True）。

按会话上下文¶

通过会话状态按会话覆盖源文件。当每个用户或任务针对不同的工作区或指令集时，这很有用。在异步函数中创建会话：

session = await runner.session_service.create_session(
    app_name="perseus_app",
    user_id="user",
    state={
        "_perseus_source": "@perseus\n@file AGENTS.md\n@memory deployment",
        "_perseus_workspace": "/path/to/project",
    },
)

作为 MCP 服务器使用（可选）¶

Perseus 还附带了一个 MCP 服务器，将其指令暴露为工具，因此你可以通过 ADK 的 McpToolset 来使用它，替代（或配合）插件：

from google.adk.agents import Agent
from google.adk.tools.mcp_tool import McpToolset, StdioConnectionParams
from mcp import StdioServerParameters

perseus_tools = McpToolset(
    connection_params=StdioConnectionParams(
        server_params=StdioServerParameters(
            command="perseus",
            args=["mcp", "serve", "--workspace", "."],
        )
    )
)

agent = Agent(
    name="assistant",
    model="gemini-flash-latest",
    instruction="使用 Perseus 工具读取工作区上下文。",
    tools=[perseus_tools],
)

插件参考¶

入口	范围	说明
`PerseusContextPlugin(source)`	Runner 全局	将编译后的上下文注入每个智能体的模型请求
`perseus_before_model_callback(source)`	单个智能体	一个注入编译后上下文的 `before_model_callback`
`_perseus_source` / `_perseus_workspace`	会话状态	按会话覆盖源文件和工作区

对比¶

方式	索引 / 嵌入	额外模型调用	输出稳定性	覆盖范围
简单上下文转储	无	否	稳定	提示中的所有内容
RAG / 向量检索	需要	查询嵌入	随查询变化	Top-k 结果
Perseus 编译	无	否	字节级一致	完整、已声明