---
title: Agentes como archivos
description: Define agentes de Lampson con un archivo JSON — su prompt, las herramientas exactas que pueden usar, rutas limitadas, permisos por herramienta, modelo propio — por proyecto o globales.
---
# Agentes como archivos

Además de los agentes que trae Lampson (`build`, `plan`, `review`, `explore`), puedes definir los tuyos con un archivo. Un agente es **datos, no código**: su prompt, las herramientas que puede usar, sus permisos y su modelo.

```json
{
  "id": "tienda",
  "description": "Atiende a los clientes de la panadería por chat",
  "base": "none",
  "system": "Eres el asistente de Panadería Sol. Lee el catálogo antes de responder sobre precios o stock. Nunca inventes productos ni descuentos.",
  "tools": [{"name": "read", "paths": [".lampson/tienda/*"]}],
  "permission": "strict",
  "steps": 6,
  "budget_tokens": 40000,
  "model": {"provider": "", "model": ""}
}
```

Guárdalo como `.lampson/agents/tienda.agent.json` en tu proyecto: el nombre del archivo tiene que ser `<id>.agent.json`. Desde ese momento lo ves en `/agent`, en el selector de la web, en `lampson run --agent tienda`, en la API, en los canales y en el SDK.

## Dónde viven

- **Del proyecto**: `<proyecto>/.lampson/agents/<id>.agent.json`. Súbelo a git y tu equipo lo tiene.
- **Globales**: `~/lampson/agents/<id>.agent.json` — en la carpeta de Lampson, disponibles en **todos** tus proyectos. Un `revisor` con tus reglas, un `traductor`: los escribes una vez.
- Si un proyecto tiene un agente con el mismo `id` que uno global (o que uno integrado), **gana el del proyecto**.

Un archivo roto no tumba a los demás: se ignora y el motivo queda a la vista.

## Los campos

| campo | | por defecto |
|---|---|---|
| `id` | minúsculas, números y `-` (máx. 40) | obligatorio |
| `description` | para qué sirve; la ven `/agent`, la API y las IAs que lo usan por MCP | `""` |
| `base` | `"none"`: el prompt es solo `system`. `"lampson"`: antepone el prompt del agente de programación (herramientas, reglas del proyecto, `AGENTS.md`) | `"none"` |
| `system` | el prompt del agente (obligatorio con `base: "none"`). Se le suman las [instrucciones](/es/docs/plugins#instrucciones-el-plugin-trae-su-proceso) de los plugins cuyas herramientas tiene | |
| `tools` | las herramientas que puede usar — ver abajo | `[]` |
| `permission` | `ask`, `strict` o `yolo` — ver [Permisos](/es/docs/permissions) | el de la puerta |
| `steps` | tope de pasos por turno | el de Lampson |
| `budget_tokens` | tope de tokens por turno | el de Lampson |
| `model` | `{"provider", "model"}` para que este agente use su propio modelo (uno barato para atención, uno potente para código) | el configurado |
| `buffer` | la espera de silencio del [buzón](/es/docs/api#el-buzon): `{"quiet_s": 3, "max_s": 15}` o `false` | la de la puerta |

El `model` propio se respeta en todas partes: la API, los canales, el SDK y también la terminal — `lampson --agent tienda` arranca con el modelo de `tienda`, y `/agent` cambia de modelo junto con el agente (`/model` lo sigue cambiando para la sesión).

## Herramientas y permisos

`tools` es una **lista exacta**: el modelo no ve nada fuera de ella.

```json
"tools": [
  "read",
  "plugin_pedidos_*",
  {"name": "read", "paths": [".lampson/tienda/*", "README.md"]},
  {"name": "mcp_proveedor_ask", "approve": "auto"},
  {"name": "bash", "approve": "ask"}
]
```

- **Por nombre**: las herramientas integradas (`read`, `write`, `edit`, `ls`, `find`, `grep`, `bash`, `fetch`…), las de plugins (`plugin_<plugin>_<tool>`) y las de MCP (`mcp_<server>_<tool>`). Un `*` al final toma un prefijo: `plugin_pedidos_*`.
- **`paths` — rutas limitadas** (opcional). Solo para `read`, `write`, `edit`, `ls`, `find` y `grep`. Con `"read"` a secas el agente ve todo el proyecto (lo de siempre, ideal para código o uso personal); con `paths`, solo esas rutas: `"carpeta/*"` es la carpeta y todo lo de adentro, `"archivo.json"` un archivo exacto, `"*"` todo. Lampson compara la ruta **real** que usaría la herramienta, no el texto del modelo: `../`, barras invertidas y rutas absolutas no se cuelan.
  Un agente con rutas limitadas **no puede** tener además `bash`, `process`, `delegate`, `lsp` ni `computer_use`, que leerían cualquier archivo por otro camino: Lampson rechaza el archivo y te dice por qué.
- **`approve` — permiso por herramienta** (opcional). `"auto"`: esa herramienta, y solo esa, corre sin pedir aprobación aunque el agente sea `strict` (lo prohibido en todos los modos, como `rm -rf /`, sigue prohibido). `"ask"`: pide aprobación siempre, aunque el agente sea `yolo`. Así no tienes que darle `yolo` a un agente entero para que use una sola herramienta.

**Sin nadie delante** (la API, un canal, `lampson run`), un agente que no dice `permission` corre en `strict`: lo que pediría aprobación se deniega, el modelo lo ve y lo explica. Por la API, un agente en `ask` sí puede esperar una aprobación: llega al panel **Aprobaciones** de la web y, si configuraste la URL pública y el webhook, a tu celular. → [Tareas programadas](/es/docs/schedules)

## Un agente de cara al público

Para un bot que habla con desconocidos, lo seguro es darle lo justo:

- `base: "none"` y un `system` que diga qué hace y qué no.
- Solo las herramientas que necesita — mejor un plugin con una acción concreta (`catalogo_buscar`) que `read`; y si usa `read`, con `paths`.
- `permission: "strict"`.

Ejemplo completo, con una conversación real: [Receta: tomar pedidos por chat](/es/docs/orders).

Aunque alguien lo convenza de «leer el `.env`», el agente no puede: Lampson rechaza la llamada antes de ejecutarla. Qué garantiza Lampson y qué no, con un ejemplo real de prompt injection, está en [Seguridad](/es/docs/security); y un agente de soporte con herramientas propias, en [Receta: un agente de soporte](/es/docs/support).