Adicionar ferramentas

Antes de escrever uma ferramenta, pergunte: isso não deveria ser uma skill?

Só para ferramentas do núcleo

Esta página é sobre acrescentar uma ferramenta embutida ao repositório do Hermes. Se você quer uma ferramenta pessoal, específica de um projeto ou personalizada, sem mexer no núcleo, use o caminho dos plugins:

• Plugins
• Criar um Plugin

Para a maioria das ferramentas personalizadas, o padrão é plugin. Siga esta página só quando você quiser mesmo publicar uma ferramenta embutida em tools/ e no toolsets.py.

Faça uma skill quando a capacidade puder ser expressa como instruções, comandos de shell e ferramentas existentes (busca no arXiv, fluxos de git, gerenciamento de Docker, processamento de PDF).

Faça uma ferramenta quando ela exigir integração de ponta a ponta, com chave de API, lógica de processamento própria, dados binários ou transmissão contínua (automação de navegador, síntese de voz, análise de imagem).

Visão geral

Acrescentar uma ferramenta toca 2 arquivos:

1. tools/sua_ferramenta.py — o manipulador, o esquema, a função de checagem e a chamada de registry.register()
2. toolsets.py — acrescente o nome da ferramenta em _HERMES_CORE_TOOLS (ou num conjunto específico)

Qualquer arquivo tools/*.py com uma chamada de registry.register() no nível de módulo é descoberto sozinho na inicialização — não é preciso manter lista de imports.

Passo 1: crie o arquivo da ferramenta

Todo arquivo de ferramenta segue a mesma estrutura:

# tools/weather_tool.py
"""Weather Tool -- look up current weather for a location."""

import json
import os
import logging

logger = logging.getLogger(__name__)


# --- Checagem de disponibilidade ---

def check_weather_requirements() -> bool:
    """Devolve True se as dependências existem."""
    return bool(os.getenv("WEATHER_API_KEY"))


# --- Manipulador ---

def weather_tool(location: str, units: str = "metric") -> str:
    """Busca o clima de um lugar. Devolve uma string JSON."""
    api_key = os.getenv("WEATHER_API_KEY")
    if not api_key:
        return json.dumps({"error": "WEATHER_API_KEY not configured"})
    try:
        # ... chama a API de clima ...
        return json.dumps({"location": location, "temp": 22, "units": units})
    except Exception as e:
        return json.dumps({"error": str(e)})


# --- Esquema ---

WEATHER_SCHEMA = {
    "name": "weather",
    "description": "Get current weather for a location.",
    "parameters": {
        "type": "object",
        "properties": {
            "location": {
                "type": "string",
                "description": "City name or coordinates (e.g. 'London' or '51.5,-0.1')"
            },
            "units": {
                "type": "string",
                "enum": ["metric", "imperial"],
                "description": "Temperature units (default: metric)",
                "default": "metric"
            }
        },
        "required": ["location"]
    }
}


# --- Registro ---

from tools.registry import registry

registry.register(
    name="weather",
    toolset="weather",
    schema=WEATHER_SCHEMA,
    handler=lambda args, **kw: weather_tool(
        location=args.get("location", ""),
        units=args.get("units", "metric")),
    check_fn=check_weather_requirements,
    requires_env=["WEATHER_API_KEY"],
)

Regras principais

Importante

• Os manipuladores precisam devolver uma string JSON (via json.dumps()), nunca um dicionário cru
• Erros precisam voltar como {"error": "mensagem"}, nunca levantados como exceção
• A check_fn é chamada ao montar as definições de ferramenta — se devolver False, a ferramenta é excluída em silêncio
• O handler recebe (args: dict, **kwargs), em que args são os argumentos da chamada do modelo

Passo 2: acrescente a ferramenta a um conjunto

No toolsets.py, acrescente o nome:

# Se deve existir em todas as plataformas (CLI e mensagens):
_HERMES_CORE_TOOLS = [
    ...
    "weather",  # <-- aqui
]

# Ou crie um conjunto próprio:
"weather": {
    "description": "Weather lookup tools",
    "tools": ["weather"],
    "includes": []
},

Passo 3: acrescentar o import de descoberta (não é mais preciso)

Módulos de ferramenta com uma chamada de registry.register() no nível de módulo são descobertos pelo discover_builtin_tools(), em tools/registry.py. Não há lista de imports para manter — crie o arquivo em tools/ e ele é encontrado na inicialização.

Manipuladores assíncronos

Se o seu manipulador precisa de código assíncrono, marque com is_async=True:

async def weather_tool_async(location: str) -> str:
    async with aiohttp.ClientSession() as session:
        ...
    return json.dumps(result)

registry.register(
    name="weather",
    toolset="weather",
    schema=WEATHER_SCHEMA,
    handler=lambda args, **kw: weather_tool_async(args.get("location", "")),
    check_fn=check_weather_requirements,
    is_async=True,  # o registro chama _run_async() sozinho
)

O registro cuida da ponte assíncrona de forma transparente — você nunca chama asyncio.run().

Manipuladores que precisam do task_id

Ferramentas que mantêm estado por sessão recebem o task_id pelo **kwargs:

def _handle_weather(args, **kw):
    task_id = kw.get("task_id")
    return weather_tool(args.get("location", ""), task_id=task_id)

registry.register(
    name="weather",
    ...
    handler=_handle_weather,
)

Ferramentas interceptadas pelo laço do agente

Algumas ferramentas (todo, memory, session_search, delegate_task) precisam de acesso ao estado do agente naquela sessão. Elas são interceptadas pelo run_agent.py antes de chegar ao registro. O registro ainda guarda os esquemas delas, mas o dispatch() devolve um erro de reserva se a interceptação for contornada.

Opcional: integrar ao assistente de configuração

Se a sua ferramenta precisa de chave de API, acrescente em hermes_cli/config.py:

OPTIONAL_ENV_VARS = {
    ...
    "WEATHER_API_KEY": {
        "description": "Weather API key for weather lookup",
        "prompt": "Weather API key",
        "url": "https://weatherapi.com/",
        "tools": ["weather"],
        "password": True,
    },
}

Lista de conferência

• Arquivo da ferramenta criado, com manipulador, esquema, função de checagem e registro
• Acrescentada ao conjunto certo, no toolsets.py
• Confirmado que isso deve mesmo ser uma ferramenta do núcleo, e não um plugin
• O manipulador devolve strings JSON, e os erros voltam como {"error": "..."}
• Opcional: chave de API acrescentada em OPTIONAL_ENV_VARS, em hermes_cli/config.py
• Opcional: acrescentada ao toolset_distributions.py, para processamento em lote
• Testada com hermes chat -q "Use the weather tool for London"