Lampson como motor

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.

{
  "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§

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.

"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

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.

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; e um agente de suporte com ferramentas próprias, em Receita: um agente de suporte.