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 - обёртка: новая функция вокруг старой, которая может подправить аргументы до вызова и результат после. Исходный инструмент при этом не переписывается ни на строку.
Быстрый путь
- Создать
registry.py. - Перенести сборку builtins в
register_builtins. - В
main.pyсобирать Agent из реестра. - Зарегистрировать крошечный
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,
)
| Поверхность | Что крутить | Как |
|---|---|---|
| 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вешает штатные toolswrap_toolумеет before/after- Agent собирается из
registry.as_pydantic_tools() - Кастомный tool после builtins вызывается агентом