El Patrón AGENT.md: Enseñando a los Agentes de IA a Usar Tus Herramientas

Agent: I'll use the dataspoc CLI to ingest data.
Agent: Running: dataspoc ingest --from postgres --to s3://bucket
Error: No such command 'ingest'

Agent: Let me try: dataspoc pipe create --source postgres
Error: No such command 'pipe'

Agent: Maybe: dataspoc-pipe --help
[reads 50 lines of help text, burns 2000 tokens]

Agent: OK, I think it's: dataspoc-pipe run my-pipeline
Error: Pipeline 'my-pipeline' not found. Run 'dataspoc-pipe add' first.

# AGENT.md — DataSpoc Platform

## Capabilities

| Action | Tool | Command |
|--------|------|---------|
| Ingest data | Pipe | `dataspoc-pipe run <pipeline>` |
| Add new source | Pipe | `dataspoc-pipe add <name> --source <type>` |
| Query data | Lens | `dataspoc-lens shell` then SQL |
| Ask questions | Lens | `dataspoc-lens ask "<question>"` |
| Train model | Lens | `dataspoc-lens ml train --table <t> --target <col>` |
| Predict | Lens | `dataspoc-lens ml predict --model <name> --input <table>` |

## Python SDK

```python
from dataspoc_pipe import PipeClient
from dataspoc_lens import LensClient

pipe = PipeClient(project_path="./my-project")
lens = LensClient(bucket_alias="company")

# Ingest
pipe.run("my-pipeline")

# Query
result = lens.sql("SELECT * FROM raw__postgres__orders LIMIT 10")

# AI Ask
answer = lens.ask("What is the total revenue this month?")

# Train
lens.ml_train(table="curated__sales__customers", target="churned", model_name="churn-v1")

## Por Qué Funciona

Los agentes de IA (Claude, GPT-4, Gemini, modelos locales) comparten un comportamiento: leen contexto y siguen instrucciones. Cuando encuentran AGENT.md:

1. **Escanean la tabla de capacidades** — saben exactamente qué acciones son posibles
2. **Copian los ejemplos del SDK de Python** — usan la sintaxis correcta en el primer intento
3. **Siguen los patrónes** — ejecutan flujos de trabajo de múltiples pasos correctamente
4. **Respetan las restricciones** — evitan errores comunes
5. **Usan la recuperación de errores** — se autocorrigen sin ensayo y error

El resultado: una llamada de herramienta en lugar de ocho. Correcto en el primer intento.

## Comparación: Tres Enfoques

### Sin Documentación

### README.md (Diseñado para Humanos)

### AGENT.md (Diseñado para Máquinas)

## Cómo Escribir AGENT.md para Tus Propias Herramientas

### Paso 1: Tabla de Capacidades

Lista cada acción que tu herramienta puede hacer. Una fila por acción. Incluye el comando exacto o la llamada a función.

```markdown
## Capabilities

| Action | Command/Function |
|--------|-----------------|
| Create user | `api.create_user(email, name)` |
| List users | `api.list_users(filters={})` |
| Delete user | `api.delete_user(user_id)` |

## SDK

```python
from myservice import Client

client = Client(api_key=os.environ["MY_API_KEY"])

# Create
user = client.create_user(email="test@example.com", name="Test")

# Read
users = client.list_users(filters={"active": True})

# Update
client.update_user(user.id, name="New Name")

### Paso 3: Patrones (Flujos de Trabajo de Múltiples Pasos)

Los agentes necesitan saber el orden de las operaciónes. Muestra flujos de trabajo comunes cómo pasos numerados:

```markdown
## Patterns

### Onboard a New Customer
1. `client.create_org(name="Acme")`
2. `client.create_user(email="admin@acme.com", org_id=org.id, role="admin")`
3. `client.send_invite(user.id)`

### Generate Monthly Report
1. `data = client.get_metrics(period="last_month")`
2. `report = client.generate_report(data, format="pdf")`
3. `client.email_report(report, recipients=["cfo@company.com"])`

## Constraints

- Never delete production data without confirmation
- Always use pagination for list endpoints (max 100 per page)
- Rate limit: 60 requests per minute
- IDs are UUIDs, never integers
- Dates are always ISO 8601 with timezone

## Error Recovery

| Error | Fix |
|-------|-----|
| 401 Unauthorized | Re-check API_KEY env var |
| 404 Not Found | Verify resource ID with list endpoint |
| 429 Rate Limited | Wait 60 seconds, retry |
| 500 Server Error | Retry up to 3 times with backoff |

# AGENT.md — [Your Tool Name]

## Capabilities

| Action | Command/Function | Returns |
|--------|-----------------|---------|
| ... | ... | ... |

## Setup

```python
from your_tool import Client
client = Client()  # or however initialization works

# Operation 1
result = client.do_thing(param1, param2)

# Operation 2
items = client.list_things(filter="active")

## Dónde Colocar AGENT.md

Colócalo donde los agentes de IA lo encontrarán:

- **Raíz del repositorio** — los agentes explorando tu código base lo encontrarán inmediatamente
- **Directorio del paquete** — los agentes usando tu paquete instalado pueden localizarlo
- **Sitio de documentación** — los agentes con acceso web pueden descargarlo
- **System prompt** — si controlas el agente, inyéctalo directamente

DataSpoc incluye AGENT.md en el paquete instalado:

```python
import importlib.resources
agent_instructions = importlib.resources.read_text("dataspoc_lens", "AGENT.md")

@server.resource("dataspoc://agent-instructions")
def get_agent_instructions():
    return read_file("AGENT.md")