Herramientas del agente: un estándar de carpeta para habilidades y referencias

Un arnés de agente es una forma de estructurar la forma en que un sistema de IA actúa y piensa, de modo que un modelo subyacente pueda utilizarse para numerosas tareas diferentes. La idea se basa en algunos conceptos anteriores, por lo que estos se presentan primero: qué es un LLM, qué es un agente, cómo se combinan el razonamiento y el uso de herramientas, y qué habilidades se añaden. Una vez establecidos estos conceptos, el propio arnés representa un paso sencillo, y un diseño básico de carpetas es suficiente para describirlo.

Los fundamentos

Modelos de lenguaje como funciones

Con este propósito, un LLM puede considerarse una función: se ingresa texto y se obtiene texto como salida. Su única función es responder al texto con otro texto, sin embargo, la mayoría de los productos de IA recientes se construyen sobre este único comportamiento.

Qué se considera un agente

“Agente” sigue siendo un término amplio. Los trabajos académicos describen varios tipos que operan de maneras fundamentalmente diferentes. Sin embargo, en la conversación cotidiana, casi todos se refieren a lo mismo: un sistema de chat que recibe un mensaje, realiza alguna acción y responde. Ese patrón se denomina comúnmente ReAct, una capa sencilla de código que conecta un modelo con funcionalidades para que pueda razonar, actuar y observar. ReAct permite al modelo pensar en lo que va a hacer, elegir una acción que afecte el entorno y luego leer una observación sobre el resultado. Todo lo que sigue utiliza “agente” en este sentido similar a ReAct.

Razonamiento y acción

Bajo ese ciclo se encuentran dos ideas. El razonamiento suele gestionarse mediante una cadena de pensamientos, lo que implica guiar al modelo para que analice su solución antes de decidirse por una respuesta. El artículo que lo introdujo lo hizo incluyendo un ejemplo resuelto dentro de la instrucción, y una pregunta que fallaba con las instrucciones habituales funcionó correctamente con el mismo modelo una vez se añadió el ejemplo.

Dicha técnica se ha vuelto tan fundamental que ahora muchos modelos se entrenan para generar por sí mismos una cadena de pensamientos. Los modelos convencionales tienden a analizar un problema antes de responder, mientras que los modelos de razonamiento popularizados por DeepSeek cuentan con una etapa específica en la que el modelo aborda el problema mediante una cadena de pensamientos muy extensa.

El uso de herramientas tiene una historia similar: existe desde hace tiempo, sigue demostrando ser útil y se está convirtiendo en un estándar. En su forma más simple, indica al modelo que si emite un texto específico, se ejecutará algún código y se obtendrá un resultado. Luego el modelo decide cuándo buscar en la web, leer archivos o, en el peor de los casos, enviar dinero a un lugar donde no debería. Las preguntas complejas suelen requerir una combinación de razonamiento y acción, y las comparaciones entre estrategias de instrucción muestran que esa combinación supera a cualquiera de ellas por separado.

Habilidades

A medida que los agentes, el uso de herramientas y las instrucciones se vuelven más avanzados, surgen prácticas establecidas. Supongamos que un agente debe agregar filas a una base de datos. Necesita herramientas que permitan al modelo ver y acceder a la base de datos, así como instrucciones que describan su estructura y las herramientas disponibles.

Una habilidad es una forma estándar de estructurar ese conjunto. La información y la funcionalidad se agrupan en una sola unidad, de modo que el agente las recibe como un paquete completo. Una habilidad es una carpeta:

my-skill/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
├── assets/           # Optional: templates, resources
└── ...               # Any additional files or directories

La mayoría de las habilidades son, en realidad, simplemente archivos de texto. Aun así, permiten que un agente comprenda y opere sistemas complejos, y brindan a los desarrolladores de agentes una capa reutilizable y portátil para planes y procedimientos.

Qué es un harness

Un harness debe considerarse como una extensión de las habilidades. Una habilidad encapsula una capacidad amplia, como editar un sitio web, administrar una base de datos o interpretar los comentarios de los clientes. Trabajos serios, como actuar como asistente de los desarrolladores de un producto, pueden requerir el uso conjunto de muchas habilidades. Un harness agrupa varias habilidades junto con el material de referencia que el agente necesita para comprender su rol y el entorno en el que trabaja.

El formato de Agent Harnesses

Bajo esta norma propuesta, un arnés consta de tres partes: un archivo Markdown que lo describe, un conjunto de habilidades para interactuar con el entorno y un conjunto de referencias que ayudan al agente a comprender dónde está trabajando. La norma es un proyecto de código abierto mantenido públicamente.

my-harness/
├── HARNESS.md        # Required: metadata + instructions
├── skills/           # Optional: a set of skills
└── references/       # Optional: a set of reference documents

El archivo de nivel superior, HARNESS.md, debe ser breve. Proporciona al agente una visión rápida y general del problema e indica dónde encontrar detalles dentro de las habilidades y referencias.

El diseño sigue el principio de divulgación progresiva, un patrón popularizado recientemente por la norma Agent Skills. Se desarrolla en tres fases:

1. Descubrimiento. Al iniciar, el agente carga únicamente HARNESS.md, que describe la estructura del sistema. Cuando llega una solicitud, el agente la compara con esas descripciones y examina gradualmente los nombres y descripciones de las habilidades y referencias hasta encontrar lo que necesita.
2. Activación. Una vez encontrado el material relevante, se carga y se lee toda la documentación correspondiente a esas habilidades y referencias.
3. Ejecución. El agente sigue las indicaciones del sistema y puede ejecutar las habilidades correspondientes.

El archivo HARNESS.md

Al igual que con las habilidades, el arnés utiliza frontmatter, datos clave colocados en la parte superior de un archivo markdown para que el agente pueda analizar los recursos de manera eficiente.

---
name: <name of the harness>
description: <description of what the harness is for>
---

<body>

Un nombre y una descripción son obligatorios para que el agente pueda saber de inmediato qué tipo de arnés es. El cuerpo del texto contiene una breve explicación de los elementos principales, orientando al agente sobre las habilidades y referencias que debe utilizar.

El directorio de habilidades

Este directorio alberga habilidades que siguen la norma Agent Skills, la cual las define de la siguiente manera:

my-skill/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
├── assets/           # Optional: templates, resources
└── ...               # Any additional files or directories

Un arnés se basa en eso, por lo que el directorio de habilidades se ve así:

my-harness/
├── HARNESS.md
├── skills/
|  ├── my-skill-1/
|  |  ├── SKILL.md
|  |  ├── scripts/
|  |  ├── references/
|  |  ├── assets/
|  |  └── ...
|  └── my-skill-2/
|     ├── SKILL.md
|     ├── scripts/
|     ├── references/
|     ├── assets/
|     └── ...
└── references/

El directorio de referencias

El directorio de referencias contiene documentos arbitrarios que ayudan al agente a comprender su entorno, su rol u otro contexto de alto nivel.

Las habilidades también tienen referencias, y estos dos niveles difieren en alcance. Las referencias dentro de una habilidad explican cómo utilizar esa habilidad específica. Las referencias a nivel de harness deben contener aquello que varias habilidades necesitan en común, a un nivel de abstracción más alto.

Tomemos un agente diseñado para ayudar a crear contenido de marketing. Puede tener una habilidad para escribir artículos de blog, otra para generar imágenes y otra para escanear redes sociales:

my-mraketing-harness/
├── HARNESS.md
├── skills/
|  ├── create-blog-post/
|  |  ├── SKILL.md
|  |  └── ...
|  ├── generate-images/
|  |  ├── SKILL.md
|  |  └── ...
|  └── scan-social/
|     ├── SKILL.md
|     └── ...
└── references/

Cada habilidad puede tener sus propias referencias. La habilidad de escaneo social podría enumerar las cuentas de la empresa, la habilidad relacionada con imágenes podría indicar dónde se almacenan las imágenes terminadas, y la habilidad de blog podría describir el proceso de publicación. Las referencias a nivel de framework son el lugar natural para elementos utilizados en las tres habilidades, como las guías de estilo y las prioridades de la marca:

my-mraketing-harness/
├── HARNESS.md
├── skills/
|  ├── create-blog-post/
|  |  ├── SKILL.md
|  |  └── ...
|  ├── generate-images/
|  |  ├── SKILL.md
|  |  └── ...
|  └── scan-social/
|     ├── SKILL.md
|     └── ...
└── references/
   ├── style-guide.md
   └── brand-priorities.md

Cualquier contenido puede colocarse en el directorio de referencias a nivel de arnés, pero se recomienda encarecidamente usar Markdown, con una breve descripción en la parte superior de cada archivo para que un agente pueda evaluar rápidamente su relevancia. Una guía de estilo en este ejemplo podría comenzar de la siguiente manera:

---
description: a style guide for the marketing website, which covers the creation
of all visual assets and standard typography rules
---

<body>

Organizar un arnés grande

Un arnés puede contener una gran cantidad de habilidades y referencias. Cuando los conjuntos se vuelven lo suficientemente grandes, el mantenimiento se vuelve confuso y proporcionar información al agente resulta ineficiente.

my-harness/
├── HARNESS.md
├── skills/
|  ├── skill1/
|  ├── skill2/
|  ├── skill3/
|  └── ...
└── references/
   ├── reference1
   ├── reference2
   ├── reference3
   └── ...

La respuesta son los subdirectorios. Dentro tanto de las habilidades como de las referencias, las carpetas pueden agrupar elementos en subconjuntos:

my-harness/
├── HARNESS.md
├── skills/
│   ├── software-development/
│   │   ├── SKILLS.md
│   │   ├── skill1/
│   │   │   └── SKILL.md
│   │   └── skill2/
│   │       └── SKILL.md
│   ├── market-analysis/
│   │   ├── SKILLS.md
│   │   └── skill3/
│   │       └── SKILL.md
│   └── social-media/
│       ├── SKILLS.md
│       ├── skill4/
│       │   └── SKILL.md
│       └── skill5/
│           └── SKILL.md
└── references/
    ├── brand-assets/
    │   ├── REFERENCES.md
    │   ├── reference1.md
    │   └── reference2.md
    ├── software-infrastructure/
    │   ├── REFERENCES.md
    │   ├── reference3.md
    │   └── reference4.md
    └── product-information/
        ├── REFERENCES.md
        └── reference5.md

Para que el agente comprenda plenamente esta estructura de manera eficiente, HARNESS.md debe describirla. Cada subdirectorio también cuenta con un archivo descriptivo: SKILLS.md aborda las habilidades del subdirectorio y REFERENCES.md se ocupa de sus referencias.

Aquí es donde la divulgación progresiva resulta útil. El agente lee el archivo de nivel superior para conocer la estructura general y luego abre los archivos SKILLS.md y REFERENCES.md específicos solo cuando es necesario, lo cual constituye la forma más eficiente de acceder al material relevante.

La anidación puede ser tan profunda como lo exijan los contenidos, por lo que una gran colección puede organizarse a un nivel alto. Cada subdirectorio debe contener su propio SKILLS.md o REFERENCES.md para que el agente comprenda cada capa a medida que avanza hacia adentro:

...
└── references/
  └── data-sources/
      ├── REFERENCES.md
      ├── relational/
      │   ├── REFERENCES.md
      │   └── schema-overview.md
      └── warehouse/
          ├── REFERENCES.md
          └── dataset-catalog.md

Por qué funciona este diseño

El formato exige muy poco al autor. Todo consiste en un archivo de texto dentro de una carpeta, lo que significa que un conjunto de recursos puede versionarse, revisarse y compartirse como cualquier otro proyecto. El agente nunca necesita cargar toda la colección, ya que cada archivo descriptivo funciona como una pequeña indicación que decide si seguir avanzando. Un conjunto de recursos para un equipo de marketing y otro para un administrador de bases de datos difieren únicamente en su contenido, mientras que el flujo de descubrimiento, activación y ejecución permanece idéntico.

Dos hábitos mantienen saludable un conjunto de recursos. Primero, escriba cada descripción de manera que indique cuándo es relevante el material y no solo qué contiene, ya que el agente decide qué abrir únicamente a partir de esa frase. Segundo, asegúrese de que las referencias a nivel de conjunto de recursos estén realmente compartidas. Si un documento se aplica a una sola habilidad, debe encontrarse dentro de esa habilidad, y promoverlo hacia niveles superiores solo añade ruido a todas las búsquedas restantes.