---
title: Agentes como arquivos
description: Defina agentes do Lampson com um arquivo JSON — prompt, ferramentas exatas, caminhos limitados, permissões por ferramenta, modelo próprio — por projeto ou globais.
---
# Agentes como arquivos

Além dos agentes que vêm com o Lampson (`build`, `plan`, `review`, `explore`), você pode definir os seus com um arquivo. Um agente é **dados, não código**: o prompt, as ferramentas que ele pode usar, suas permissões e seu modelo.

```json
{
  "id": "tienda",
  "description": "Atende os clientes da padaria pelo chat",
  "base": "none",
  "system": "Você é o assistente da Padaria Sol. Leia o catálogo antes de responder sobre preços ou estoque. Nunca invente produtos nem descontos.",
  "tools": [{"name": "read", "paths": [".lampson/tienda/*"]}],
  "permission": "strict",
  "steps": 6,
  "budget_tokens": 40000,
  "model": {"provider": "", "model": ""}
}
```

Salve como `.lampson/agents/tienda.agent.json` no seu projeto: o nome do arquivo tem que ser `<id>.agent.json`. A partir daí ele aparece em `/agent`, no seletor da web, em `lampson run --agent tienda`, na API, nos canais e no SDK.

## Onde ficam

- **Do projeto**: `<projeto>/.lampson/agents/<id>.agent.json`. Versione no git e sua equipe também terá.
- **Globais**: `~/lampson/agents/<id>.agent.json` — na pasta do Lampson, disponíveis em **todos** os seus projetos. Um `revisor` com as suas regras, um `traductor`: você escreve uma vez.
- Se um projeto tem um agente com o mesmo `id` de um global (ou de um integrado), **vale o do projeto**.

Um arquivo quebrado não derruba os outros: ele é ignorado e o motivo fica visível.

## Os campos

| campo | | padrão |
|---|---|---|
| `id` | minúsculas, números e `-` (máx. 40) | obrigatório |
| `description` | para que serve; aparece em `/agent`, na API e para as IAs que o usam por MCP | `""` |
| `base` | `"none"`: o prompt é só `system`. `"lampson"`: coloca antes o prompt do agente de programação (ferramentas, regras do projeto, `AGENTS.md`) | `"none"` |
| `system` | o prompt do agente (obrigatório com `base: "none"`). Somam-se a ele as [instruções](/pt/docs/plugins#instrucoes-o-plugin-traz-o-seu-processo) dos plugins cujas ferramentas ele tem | |
| `tools` | as ferramentas que ele pode usar — veja abaixo | `[]` |
| `permission` | `ask`, `strict` ou `yolo` — veja [Permissões](/pt/docs/permissions) | o da porta |
| `steps` | limite de passos por turno | o do Lampson |
| `budget_tokens` | limite de tokens por turno | o do Lampson |
| `model` | `{"provider", "model"}` para este agente usar o próprio modelo (um barato para atendimento, um potente para código) | o configurado |
| `buffer` | a espera por silêncio da [caixa de entrada](/pt/docs/api#a-caixa-de-entrada): `{"quiet_s": 3, "max_s": 15}` ou `false` | a da porta |

O `model` próprio é respeitado em todo lugar: na API, nos canais, no SDK e também no terminal — `lampson --agent tienda` inicia com o modelo de `tienda`, e `/agent` troca de modelo junto com o agente (`/model` continua trocando para a sessão).

## Ferramentas e permissões

`tools` é uma **lista exata**: o modelo não vê nada fora dela.

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

- **Por nome**: as ferramentas integradas (`read`, `write`, `edit`, `ls`, `find`, `grep`, `bash`, `fetch`…), as de plugins (`plugin_<plugin>_<tool>`) e as de MCP (`mcp_<server>_<tool>`). Um `*` no final pega um prefixo: `plugin_pedidos_*`.
- **`paths` — caminhos limitados** (opcional). Só para `read`, `write`, `edit`, `ls`, `find` e `grep`. Com `"read"` sozinho o agente vê o projeto inteiro (o de sempre, ideal para código ou uso pessoal); com `paths`, só esses caminhos: `"pasta/*"` é a pasta e tudo o que está dentro, `"arquivo.json"` um arquivo exato, `"*"` tudo. O Lampson compara o caminho **real** que a ferramenta usaria, não o texto do modelo: `../`, barras invertidas e caminhos absolutos não passam.
  Um agente com caminhos limitados **não pode** ter também `bash`, `process`, `delegate`, `lsp` nem `computer_use`, que leriam qualquer arquivo por outro caminho: o Lampson rejeita o arquivo e diz por quê.
- **`approve` — permissão por ferramenta** (opcional). `"auto"`: essa ferramenta, e só ela, roda sem pedir aprovação mesmo que o agente seja `strict` (o que é proibido em todos os modos, como `rm -rf /`, continua proibido). `"ask"`: pede aprovação sempre, mesmo que o agente seja `yolo`. Assim você não precisa dar `yolo` a um agente inteiro para ele usar uma única ferramenta.

**Sem ninguém por perto** (a API, um canal, `lampson run`), um agente que não define `permission` roda em `strict`: o que pediria aprovação é negado, o modelo vê e explica. Pela API, um agente em `ask` pode sim esperar uma aprovação: ela chega ao painel **Aprovações** da web e, se você configurou a URL pública e o webhook, ao seu celular. → [Tarefas agendadas](/pt/docs/schedules)

## Um agente voltado ao público

Para um bot que conversa com desconhecidos, o seguro é dar só o necessário:

- `base: "none"` e um `system` que diga o que ele faz e o que não faz.
- Só as ferramentas de que precisa — melhor um plugin com uma ação concreta (`catalogo_buscar`) do que `read`; e, se usar `read`, com `paths`.
- `permission: "strict"`.

Um exemplo completo, com uma conversa real: [Receita: receber pedidos pelo chat](/pt/docs/orders).

Mesmo que alguém o convença a «ler o `.env`», o agente não consegue: o Lampson rejeita a chamada antes de executá-la. O que o Lampson garante e o que não garante, com um exemplo real de prompt injection, está em [Segurança](/pt/docs/security); e um agente de suporte com ferramentas próprias, em [Receita: um agente de suporte](/pt/docs/support).