Capa de Tooling

Estado

Implemented. El lab tiene docenas de herramientas en cuatro categorías: media, research, web y code. La capa de tooling es la base del trabajo determinista del lab.

Propósito

La capa de tooling convierte tareas repetibles en capacidades invocables. Algunas son herramientas locales CLI-first; otras son adaptadores de servicios externos expuestos a través de MCP. En ambos casos, el objetivo es evitar que el agente dependa solo de razonamiento generativo para tareas que tienen una solución determinista.

Esta página es la referencia canónica de la capa de tooling. La estructura estándar de una herramienta está en Tool Structure; la plantilla de especificación está en Tool Spec; el tool registry está en Tool Registry; las herramientas específicas de media están en Media Tools; el Media Lab Server está en Media Lab Server.

Por qué una capa de tooling

Los agentes que dependen solo de razonamiento generativo para tareas deterministas son:

• Lentos. Una llamada HTTP de 5 segundos tarda 30 segundos cuando se hace a través del modelo.
• Inconsistentes. La misma tarea produce resultados distintos en runs diferentes.
• Caros. Cada llamada consume tokens.
• No verificables. La salida no se valida contra un esquema.
• Frágiles. El modelo puede alucinar, saltarse pasos o elegir la herramienta equivocada.

Una capa de tooling aborda los cinco problemas. La tarea determinista la hace una herramienta, no el modelo. El rol del modelo se reduce a:

• Elegir qué herramienta llamar.
• Pasar los argumentos correctos.
• Interpretar el resultado.

Esta división del trabajo es el principio fundamental del lab.

Categorías de herramientas

Las herramientas del lab se dividen en cuatro categorías:

Cada categoría tiene su propia página con las herramientas concretas y sus contratos.

Inventario de herramientas

Herramientas de media

Herramientas de research

Herramientas web

Herramientas de code

El inventario completo está en el Diccionario de datos.

Invocación de herramientas

Las herramientas se invocan a través de su interfaz declarada. Una herramienta se puede invocar:

• Por un comando CLI. El main.py de la herramienta (o equivalente) es el entry point.
• Por una request HTTP. Para herramientas expuestas vía HTTP (p. ej., el Media Lab Server).
• Por una llamada a función Python. Para herramientas in-process (p. ej., los adaptadores de research).

El contrato de la herramienta está documentado en su TOOL.md y en el Tool Spec.

Tool registry

El tool registry es el mecanismo del framework para exponer herramientas a los agentes. El registry se configura por agente: cada agente tiene una lista de herramientas que tiene permitido invocar.

El registry está en el tools.json del proyecto. Un ejemplo real está en {workspace-root}/movie-scraper-tools/tools.json. El esquema está documentado en Tool Registry.

Las entradas del registry referencian la ubicación de la herramienta (la ruta al entry point de la herramienta) y sus tags (para la activación del skill loader). El registry es la lista autoritativa de herramientas disponibles para un agente.

Skills

Un skill es un fichero markdown que describe una capacidad. El Coordinator usa el skill loader para activar skills relevantes. El skill loader está en {workspace-root}/.agents/skills/.

Un skill tiene la siguiente estructura:

---
name: skill-name
description: Descripción de un párrafo.
---
 
# Skill Name
 
## When to Use This Skill
[Frases disparadoras y condiciones.]
 
## Workflow
1. Paso 1
2. Paso 2
3. ...
 
## Inputs
[Lo que el skill necesita.]
 
## Outputs
[Lo que el skill produce.]
 
## Failure modes
[Lo que puede fallar.]

El skill se carga en el contexto de la sesión cuando la request del Coordinator coincide con las frases disparadoras del skill. Las instrucciones del skill se siguen al pie de la letra; el Coordinator no las modifica.

Adaptadores MCP

Algunas herramientas se exponen a través del Model Context Protocol (MCP). Un adaptador MCP es un servidor que expone las capacidades de una herramienta a través de un protocolo estandarizado. El lab usa MCP para:

• El adaptador Perplexity (el motor de síntesis para P3).
• El servidor perplexity-mcp (documentado en External Providers).

El contrato del adaptador MCP está documentado en su README.md y en el código fuente del adaptador.

Sandbox y trust

Las herramientas que puede invocar el Coordinator corren con los permisos del Coordinator. Las herramientas que puede invocar el Coding Assistant corren en un sandbox con los permisos declarados en el nivel de sandbox (read-only, workspace-write o full).

Las herramientas del research framework corren con los permisos del gateway de Scout. Las herramientas del Media Agent corren con los permisos del gateway de Scout (el Media Agent comparte el gateway de Scout).

Las herramientas web corren con los permisos del Coordinator.

Los niveles de sandbox y trust están documentados en Coding Assistant → Sandbox y trust.

Desarrollo de herramientas

Para añadir una herramienta nueva:

1. Escoge una categoría. Media, research, web o code.
2. Escoge una estructura. Herramienta CLI, adaptador MCP o servidor HTTP.
3. Implementa la herramienta. Sigue el patrón de Tool Structure.
4. Escribe la documentación. README.md, TOOL.md, SKILL.md, AGENTS.md.
5. Escribe los tests. Tests unitarios para la lógica principal.
6. Registra la herramienta. Añade una entrada a tools.json.
7. Verifica. Ejecuta los tests; ejecuta el smoke test.

La plantilla completa está en Project Templates → CLI Python tool template.

Observabilidad de las herramientas

Las herramientas son observables a través de:

• Logs. Cada invocación de herramienta se loguea con los inputs, los outputs, la duración y cualquier error.
• Métricas. El count de invocaciones, el count de errores y la duración de la herramienta se registran en las métricas.
• Audit trail. Las invocaciones de la herramienta se registran en el audit trail.

La observabilidad está documentada en Telemetry.

Patrones

El lab reutiliza un pequeño conjunto de patrones en la capa de tooling:

Patrón adapter

El patrón adapter traduce entre una interfaz genérica y un formato específico del proveedor. El patrón está documentado en External Providers → Adapter contract.

Patrón skill

El patrón skill describe una capacidad en un fichero markdown. El patrón está documentado en Tool Spec.

Patrón CLI tool

El patrón CLI tool envuelve una capacidad determinista en un script Python. El patrón está documentado en Tool Structure.

Patrón HTTP server

El patrón HTTP server expone una herramienta a través de una API HTTP. El patrón está documentado en Media Lab Server.

Ver también

• Tool Structure
• Tool Spec
• Tool Registry
• Media Tools
• Media Lab Server
• Project Templates
• External Providers
• Telemetry