02 工具可见性与描述覆盖

它是什么

Harness profile 可以用 tool_description_overrides 改工具描述，用 excluded_tools 把工具从模型可见工具集中移除。它解决的问题是：同一套 Agent 在不同模型下可能需要不同的工具说明，或者某些模型不该看到某些工具。工具隐藏是按工具名匹配。

最小代码

文件：deepagent_src/profiles_teach/02_tool_visibility.py

register_harness_profile(
    "openai:gpt-5.5",
    HarnessProfile(
        tool_description_overrides={
            "visible_profile_tool": "Use this tool when the user asks for the visible profile marker."
        },
        excluded_tools=frozenset({"hidden_profile_tool"}),
    ),
)

运行

uv run python deepagent_src/profiles_teach/02_tool_visibility.py

预期输出末尾：

tool visibility profile real agent ok

验证方式

脚本真实调用 Agent，要求它调用 visible_profile_tool；断言工具消息中出现可见工具结果，并且没有出现隐藏工具结果。

常见误区

excluded_tools 不是删除工具函数，也不是改 Python 代码；它是在模型请求前过滤工具，让模型看不见这个工具。

相关资源

查看示例代码：deepagent_src/profiles_teach/02_tool_visibility.py

from __future__ import annotations

from deepagents import HarnessProfile, create_deep_agent, register_harness_profile
from langchain.tools import tool

from _model import MODEL_PROFILE_KEY, get_real_model
from deepagent_src.agent_output import invoke_and_pretty_print


@tool
def visible_profile_tool() -> str:
    """Return the visible profile marker."""
    return "visible-profile-tool-called"


@tool
def hidden_profile_tool() -> str:
    """Return the hidden profile marker."""
    return "hidden-profile-tool-called"


def main() -> None:
    register_harness_profile(
        MODEL_PROFILE_KEY,
        HarnessProfile(
            tool_description_overrides={
                "visible_profile_tool": (
                    "Use this tool when the user asks for the visible profile marker."
                )
            },
            excluded_tools=frozenset({"hidden_profile_tool"}),
        ),
    )

    agent = create_deep_agent(
        model=get_real_model(),
        tools=[visible_profile_tool, hidden_profile_tool],
    )
    result = invoke_and_pretty_print(
        agent,
        {
            "messages": [
                {
                    "role": "user",
                    "content": (
                        "必须调用 visible_profile_tool，并只复述工具返回值。"
                    ),
                }
            ]
        },
    )

    tool_outputs = [
        getattr(message, "content", "")
        for message in result["messages"]
        if message.__class__.__name__ == "ToolMessage"
    ]

    assert any("visible-profile-tool-called" in output for output in tool_outputs)
    assert not any("hidden-profile-tool-called" in output for output in tool_outputs)
    print("tool visibility profile real agent ok")


if __name__ == "__main__":
    main()