加载项目指令#

如果项目有一些约定需要智能体在每个请求中都遵循（例如测试命令、编码规范或审查要求），可以使用AgentsMdExtension。请把这些约定写进AGENTS.md，而不是在每个用户提示词里重复。

创建项目文件#

workspace/AGENTS.md#

# Project guidance

- Keep public functions typed.
- Run the relevant tests before proposing a change.
- Explain compatibility risks in reviews.
- Ask before changing persistent data.

显式加载该目录：

from zett_agent.client import create_agent
from zett_agent.extensions.agents_md import AgentsMdExtension
from zett_agent.extensions.memory import InMemoryMessageAccumulator
from zett_agent.extensions.tool_guidelines import ToolGuidelinesExtension

instructions = AgentsMdExtension(directory="workspace", include_parents=False)
client = await create_agent(
    model,
    extensions=[
        InMemoryMessageAccumulator(),
        ToolGuidelinesExtension(),
        instructions,
    ],
)
reply = await client.run("Review the proposed change.")

这里的model是来自连接模型提供商的已配置适配器。该扩展只添加指令，不会添加文件系统、编辑或 shell 工具。如果要保留默认的历史记录和工具 guidelines，就需要把它们也写进显式的扩展列表；参见配置你的智能体。

选择发现范围#

当include_parents=True（默认值）时，发现过程会检查配置的目录以及直到文件系统根目录的每一级父目录。文件按最外层在前、最内层在后的顺序包含：

workspace/AGENTS.md               broader project guidance
workspace/services/AGENTS.md      service guidance
workspace/services/api/AGENTS.md  more specific guidance

设置directory="workspace/services/api"可以包含这三个文件，或者用include_parents=False只加载该目录下的文件。扩展不会递归扫描子目录，也不会针对工具打开的每个路径自动加载不同的文件。如果省略directory，它会在每个请求开始时解析进程的当前工作目录。目录参数只用于选择指令；它不会改变文件系统工具的运行位置。

警告

父目录发现可能会包含仓库之外的文件。对于要处理非受信任工作区的应用，请使用显式目录和include_parents=False，而不是依赖进程全局的chdir。

检查并更新指令#

print(instructions.sources())       # Ordered paths that exist.
print(instructions.instructions())  # Rendered readable guidance.

当渲染后的指令包含敏感信息时，请避免记录日志。扩展会在每个请求之前重新读取文件，因此修改会在下一个轮次生效，无需重新创建客户端。缺失、为空、无法读取或不是 UTF-8 的文件会被跳过。每个文件默认限制为max_chars=32_000；更长的文件会被包含，但带有截断标记。只有在考虑模型的上下文预算之后，才应该提高这个限制。

如果你的应用遵循其他约定，可以使用file_name="PROJECT.md"。sources()返回的路径并不保证内容可读且非空；instructions()展示的是实际可以被包含的内容。

试运行一个离线请求#

下面的示例会创建一个隔离的项目、检查模型收到的内容、修改它的指令，并验证下一个请求能看到这次修改。所有文件都是临时的。

async def main() -> None:
    with TemporaryDirectory(prefix="zett-instructions-") as directory:
        workspace = Path(directory).resolve()
        path = workspace / "AGENTS.md"
        path.write_text("Use careful reviews.\n", encoding="utf-8")
        instructions = AgentsMdExtension(directory=workspace, include_parents=False)
        assert instructions.sources() == (path,)
        client = await create_agent(GuidanceModel(), extensions=[InMemoryMessageAccumulator(), instructions])
        first = await client.run("Review the change.")
        assert first.content == "Project guidance: careful reviews"
        print(first.content)
        path.write_text("Use concise reviews.\n", encoding="utf-8")
        second = await client.run("Review again.")
        assert second.content == "Project guidance: concise reviews"
        print(second.content)

在源码检出目录中运行：

uv run python docs/_examples/project_instructions.py

预期输出：

Project guidance: careful reviews
Project guidance: concise reviews

下载完整示例。

指令、技能与权限#

AGENTS.md是所选目录中始终加载的指令。技能是通过read_skill加载的可选任务指令。你的应用系统提示词决定整体行为。这些都不是安全边界：非受信任的指令不能授权某个工具，也不能覆盖你应用的访问策略。请在工具处理函数、中间件或进程隔离中实施权限控制。