En los últimos meses, el desarrollo de agentes impulsados por modelos de lenguaje (LLM) ha acelerado la creación de sistemas capaces de razonar, ejecutar tareas complejas y coordinar múltiples herramientas de software. Sin embargo, esta expansión ha traído también fragmentación: cada framework describe sus agentes de manera distinta, lo que dificulta la interoperabilidad y la comprensión entre equipos.
Aquí es donde surge AGENTS.md, una propuesta que comienza a posicionarse —incluso dentro de tendencias como el Technology Radar de Thoughtworks— como una forma clara, legible y estandarizada para documentar y definir agentes LLM, sin depender del framework donde serán implementados.
¿Qué es AGENTS.md?
AGENTS.md es un formato inspirado en el estilo README.md, diseñado para describir un agente de IA de forma clara, portable y entendible tanto por humanos como por sistemas automáticos. Su objetivo es unificar cómo se define:
- El propósito del agente
- Sus capacidades
- Sus restricciones
- Las herramientas que puede usar
- Su flujo de trabajo o políticas de acción
- Ejemplos de interacción
Al final, AGENTS.md funciona como un contrato entre desarrolladores, stakeholders y el propio agente.
¿Por qué importa este enfoque?
El auge de los agentes comenzó con tareas simples —automatizar un flujo, llamar una API, procesar un documento—, pero ha escalado hacia:
- Orquestación multipaso
- Toma de decisiones condicionada
- Integración con servicios externos
- Acciones y validaciones basadas en herramientas
En este contexto, disponer de una documentación legible y estandarizada se vuelve indispensable. AGENTS.md elimina ambigüedades y permite:
1. Interoperabilidad entre frameworks
Ya sea que uses LangChain, Semantic Kernel, Autogen, ReAct o un framework propietario, AGENTS.md evita el bloqueo tecnológico: la definición vive fuera del código.
2. Claridad para equipos multidisciplinarios
Producto, ingeniería, diseño y negocio pueden entender el comportamiento del agente sin leer código.
3. Portabilidad entre plataformas
Un mismo archivo puede servir como blueprint en distintos entornos: web, backend, asistentes, automatizaciones, etc.
4. Mejora en el versionamiento y gobernanza de agentes
Permite comparar versiones, auditar cambios y mantener track del porqué de cada ajuste.
5. Facilita pruebas y simulaciones
Como el archivo puede incluir casos de uso y ejemplos, se convierte en una base perfecta para pruebas automatizadas.
Ejemplo de uso en un proyecto React
Supongamos que tienes un frontend en React donde puedes almacenar y versionar un archivo AGENTS.md como:
## Development Guidelines
### Component Development Standards
1. **Function Components First**: Use function components and Hooks
2. **TypeScript Types**: Define interfaces for all props
3. **Component Naming**: Use PascalCase, file name matches component name
4. **Single Responsibility**: Each component handles only one functionality
```tsx
// Example: Button Component
interface ButtonProps {
variant: 'primary' | 'secondary' | 'danger';
size?: 'small' | 'medium' | 'large';
disabled?: boolean;
onClick?: () => void;
children: React.ReactNode;
}
export const Button: React.FC<ButtonProps> = ({
variant,
size = 'medium',
disabled = false,
onClick,
children
}) => {
return (
<button
className={`btn btn-${variant} btn-${size}`}
disabled={disabled}
onClick={onClick}
>
{children}
</button>
);
};
```### State Management Standards
Using Zustand for state management:
```tsx
// store/userStore.ts
import { create } from 'zustand';
interface User {
id: string;
name: string;
email: string;
}
interface UserState {
user: User | null;
isLoading: boolean;
setUser: (user: User) => void;
clearUser: () => void;
setLoading: (loading: boolean) => void;
}
export const useUserStore = create<UserState>((set) => ({
user: null,
isLoading: false,
setUser: (user) => set({ user }),
clearUser: () => set({ user: null }),
setLoading: (isLoading) => set({ isLoading }),
}));
```### API Service Standards
```tsx
// services/api.ts
import axios from 'axios';
const api = axios.create({
baseURL: import.meta.env.VITE_API_URL,
timeout: 10000,
});
// Request interceptor
api.interceptors.request.use((config) => {
const token = localStorage.getItem('token');
if (token) {
config.headers.Authorization = `Bearer ${token}`;
}
return config;
});
// Response interceptor
api.interceptors.response.use(
(response) => response.data,
(error) => {
console.error('API Error:', error);
return Promise.reject(error);
}
);
export default api;
```## Environment Setup
### Development Requirements
- Node.js >= 18.0.0
- npm >= 8.0.0 or yarn >= 1.22.0
### Installation Steps
```bash
# 1. Create project
npm create vite@latest my-react-app -- --template react-ts
# 2. Navigate to project directory
cd my-react-app
# 3. Install dependencies
npm install
# 4. Install additional dependencies
npm install zustand react-router-dom axios
npm install -D @types/node
# 5. Start development server
npm run dev
```
### Environment Variables Configuration
```env
# .env.local
VITE_API_URL=http://localhost:3001/api
VITE_APP_TITLE=My React App
VITE_ENABLE_MOCK=false
```Hacia un futuro con agentes auditables y estandarizados
AGENTS.md es un paso natural hacia un ecosistema donde los agentes son:
- Declarativos
- Auditables
- Portables
- Versionables
En un mundo donde los LLM evolucionan semana a semana, adoptar un estándar abierto para describir agentes es una ventaja estratégica.
Para saber más
Consulta el sitio AGENTS.md y descarga algunos ejemplos.