MODULE_11 · УРОК 11.2

Custom tools

Загляните в main.py: список инструментов там до сих пор набран вручную - read, grep, bash, task, ask_user, todo, load_skill. Пока вы единственный автор своего harness, это самая честная схема, и трогать её было бы незачем. Ломается она в момент, когда появляется чужой сценарий: коллеге нужен свой deploy, а вам - bash, который в этом проекте всегда добавляет пару флагов. Форкать ядро ради такого глупо.

Значит, нужен шов. Заведём реестр: новые инструменты в него регистрируются, существующие можно обернуть, а ядро остаётся нетронутым. Заодно исчезнет ручное перечисление имён в двух местах - реестр сам знает, кто в нём лежит.

ЧТО ПОЛУЧИТСЯ Файл registry.py с register, get и list, функция-обёртка wrap_tool и сборка штатного набора в register_builtins. Agent берёт инструменты из реестра, а один крошечный кастомный tool докажет, что шов действительно работает.

Слова, которые встретятся

  • Реестр (registry) - словарь, где по имени инструмента лежит его функция и флаг takes_ctx. Скучная структура данных, из которой берётся вся гибкость.
  • wrap_tool - обёртка: новая функция вокруг старой, которая может подправить аргументы до вызова и результат после. Исходный инструмент при этом не переписывается ни на строку.

Быстрый путь

  1. Создать registry.py.
  2. Перенести сборку builtins в register_builtins.
  3. В main.py собирать Agent из реестра.
  4. Зарегистрировать крошечный now и проверить.

Какие файлы трогаем

Файл Что делать
registry.py Создать. Реестр + wrap + builtins.
main.py Править. Убрать ручной список Tool(...); брать из реестра.

Шаг 1. Реестр

Сначала сама коробка. Ничего умного внутри: словарь, четыре метода и один способ отдать всё это Pydantic AI.

registry.py - основа

from __future__ import annotations

from collections.abc import Awaitable, Callable
from dataclasses import dataclass
from typing import Any

from pydantic_ai import Tool

from approval import create_approval
from sandbox import Sandbox
from skills import Skill, create_load_skill_tool
# импорты ваших create_*_tool - как в проекте


@dataclass
class RegisteredTool:
    fn: Callable[..., Any]
    takes_ctx: bool = False


class ToolRegistry:
    def __init__(self) -> None:
        self._tools: dict[str, RegisteredTool] = {}

    def register(
        self, name: str, fn: Callable[..., Any], *, takes_ctx: bool = False
    ) -> None:
        self._tools[name] = RegisteredTool(fn=fn, takes_ctx=takes_ctx)

    def get(self, name: str) -> RegisteredTool | None:
        return self._tools.get(name)

    def list(self) -> list[str]:
        return list(self._tools.keys())

    def as_pydantic_tools(self) -> list[Tool]:
        return [
            Tool(t.fn, takes_ctx=t.takes_ctx) for t in self._tools.values()
        ]


def create_registry() -> ToolRegistry:
    return ToolRegistry()

Шаг 2. wrap_tool

Дальше самая интересная функция урока. Она позволяет вклиниться до вызова инструмента и после него, ничего не зная о том, что внутри:

async def _maybe_await(value: Any) -> Any:
    if isinstance(value, Awaitable):
        return await value
    return value


def wrap_tool(
    base: Callable[..., Any],
    *,
    before_execute: Callable[[dict[str, Any]], Any] | None = None,
    after_execute: Callable[[Any], Any] | None = None,
) -> Callable[..., Any]:
    """Обернуть async-tool: before может править kwargs, after - результат."""

    async def wrapped(**kwargs: Any) -> Any:
        data = dict(kwargs)
        if before_execute is not None:
            data = await _maybe_await(before_execute(data))
            if not isinstance(data, dict):
                raise TypeError("before_execute must return dict of kwargs")
        result = await base(**data)
        if after_execute is not None:
            result = await _maybe_await(after_execute(result))
        return result

    wrapped.__name__ = getattr(base, "__name__", "wrapped_tool")
    wrapped.__doc__ = base.__doc__
    return wrapped

Исходная функция никуда не делась и продолжает жить в памяти - просто в реестре теперь лежит обёртка, и агент видит только её. Отсюда и практическая польза: политику проекта можно навесить снаружи, а когда она надоест, снять одной строкой, не разбирая инструмент по частям.

Шаг 3. register_builtins

Теперь переносим в одну функцию то, что сейчас размазано по main.py. Про порядок регистрации: task логично ставить после read и grep, если субагент получает их снаружи. У нас они обычно создаются внутри фабрики, так что жёсткого требования нет, но привычка полезная.

def register_builtins(
    registry: ToolRegistry,
    sandbox: Sandbox,
    skills: list[Skill],
) -> None:
    from tools_bash import create_bash_tool
    from tools_ask import create_ask_user_tool
    from tools_todo import create_todo_tool
    from tools_task import create_task_tool
    # read/grep - как у вас заведены (отдельные модули или @agent.tool)

    needs_approval = create_approval({"mode": "interactive"})
    registry.register("bash", create_bash_tool(sandbox, needs_approval))
    registry.register("task", create_task_tool(sandbox), takes_ctx=True)
    registry.register("ask_user", create_ask_user_tool())
    registry.register("todo", create_todo_tool())
    registry.register("load_skill", create_load_skill_tool(skills))
    # read/grep - register так же, если они у вас фабрики

Имена фабрик подставьте свои: у вас за десять модулей сложился собственный набор, и он может отличаться от листинга выше. Смысл шага не в точном совпадении строк, а в том, чтобы появилась ровно одна функция с ответом на вопрос «что у нас идёт из коробки».

Шаг 4. main.py из реестра

Осталось собрать всё вместе. Заодно добавим демонстративно бесполезный tool now: он нужен не сам по себе, а чтобы своими глазами увидеть, что новый инструмент подключается снаружи и без правок ядра.

from registry import create_registry, register_builtins, wrap_tool

registry = create_registry()
register_builtins(registry, sandbox, skills)

# демо шва: крошечный кастомный tool
async def now() -> str:
    """Вернуть текущее время в ISO.

    WHEN TO USE: нужна метка времени сейчас.
    WHEN NOT TO USE: любые другие задачи.
    """
    from datetime import datetime, timezone
    return datetime.now(timezone.utc).isoformat()

registry.register("now", now)

# пример обёртки bash (необязательно):
# base = registry.get("bash")
# if base:
#     registry.register(
#         "bash",
#         wrap_tool(
#             base.fn,
#             before_execute=lambda kw: {
#                 **kw,
#                 "command": kw["command"] + "  # via wrap",
#             }
#             if kw.get("command", "").startswith("pytest")
#             else kw,
#         ),
#     )

tool_names = registry.list()
instructions = build_system_prompt({..., "tool_names": tool_names, ...})

agent = Agent(
    args.model,
    deps_type=Sandbox,
    tools=registry.as_pydantic_tools(),
    instructions=instructions,
)
ПОВЕРХНОСТИ РАСШИРЕНИЯ (карта) Полезно один раз увидеть все места, куда в harness можно вмешаться, не трогая его внутренности. Реестр - только одно из них.
Поверхность Что крутить Как
Tools добавить / убрать / обернуть реестр + wrap_tool
Skills знания skills/ + load_skill
Sandbox бэкенд sandbox_from_flag
Approval политики конфиг + события (11.3)
Промпт секции PromptContext + build_system_prompt

Проверьте

Сначала убедимся, что кастомный инструмент вообще доехал до агента:

uv run python main.py . "Какое сейчас время? Используй tool now."

В логе должен появиться вызов now. А теперь самое показательное: закомментируйте строку registry.register("now", ...) и повторите тот же запрос. Модель ответит, что такого инструмента у неё нет. Ничего больше вы не меняли - ни промпт, ни список имён, ни сборку Agent. Это и означает, что шов держит.

Готово, если:

  • Есть create_registry с register/get/list
  • register_builtins вешает штатные tools
  • wrap_tool умеет before/after
  • Agent собирается из registry.as_pydantic_tools()
  • Кастомный tool после builtins вызывается агентом
ДАЛЬШЕ Реестр знает, какие инструменты есть. Но он ничего не знает про то, что происходит вокруг каждого вызова: кто это залогирует, кто успеет запретить, кто подправит аргументы для всей сессии сразу. Этим займётся шина событий - последний урок курса.