O Padrão AGENT.md: Ensinando Agentes de IA a Usar Suas Ferramentas

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 Que Isso Funciona

Agentes de IA (Claude, GPT-4, Gemini, modelos locais) todos compartilham um comportamento: eles leem contexto e seguem instruções. Quando encontram o AGENT.md, eles:

1. **Escaneiam a tabela de capacidades** — sabem exatamente quais ações são possíveis
2. **Copiam os exemplos do SDK Python** — usam a sintaxe correta na primeira tentativa
3. **Seguem os padrões** — executam fluxos de trabalho multi-etapa corretamente
4. **Respeitam as restrições** — evitam erros comuns
5. **Usam a recuperação de erros** — se autocorrigem sem tentativa e erro

O resultado: uma chamada de ferramenta em vez de oito. Correto na primeira tentativa.

## Comparação: Três Abordagens

### Sem Documentação

### README.md (Projetado para Humanos)

### AGENT.md (Projetado para Máquinas)

## Como Escrever AGENT.md para Suas Próprias Ferramentas

### Passo 1: Tabela de Capacidades

Liste cada ação que sua ferramenta pode fazer. Uma linha por ação. Inclua o comando exato ou chamada de função.

```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")

### Passo 3: Padrões (Fluxos de Trabalho Multi-Etapa)

Agentes precisam saber a ordem das operações. Mostre fluxos de trabalho comuns como passos 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")

## Onde Colocar o AGENT.md

Coloque-o onde agentes de IA irão encontrá-lo:

- **Raiz do repositório** — agentes explorando seu codebase irão encontrá-lo imediatamente
- **Diretório do pacote** — agentes usando seu pacote instalado podem localizá-lo
- **Site de documentação** — agentes com acesso web podem buscá-lo
- **System prompt** — se você controla o agente, injete-o diretamente

O DataSpoc inclui o AGENT.md no pacote 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")