---
title: Sem interface (lampson run)
description: Use um agente do Lampson a partir de um script, um cron ou outro programa — a mensagem entra e a resposta sai, em texto, eventos JSON ou um processo aberto com --stdio.
---
# Sem interface: `lampson run`

O mesmo agente, sem terminal nem web: uma mensagem entra, a resposta sai. Para scripts, tarefas de cron, outros programas.

```sh
lampson run "resuma as mudanças de hoje"                        # a resposta pelo stdout
lampson run --agent plan "revise o último commit"               # qualquer agente, integrado ou seu
echo "oi" | lampson run --agent tienda --thread cliente-42      # a mensagem também pode vir pelo stdin
lampson run --session 20261016-122626 "e os testes?"            # continuar uma sessão conhecida
```

`lampson run` não inicia o hub nem o servidor web: prepara a pasta do projeto e roda o turno.

## Opções

| opção | |
|---|---|
| `--agent ID` | o agente que responde (por padrão, `build`) |
| `--thread T` | a identidade da conversa fora do Lampson: um telefone, um ticket, `cto:tarea-17`. **Mesmo agente + mesmo thread = mesma conversa**, com seu histórico |
| `--session ID` | ou continuar uma sessão pelo id |
| `--json` | cada passo como uma linha JSON (veja abaixo) |
| `--ask` · `--strict` · `--yolo` | o modo de permissões; sem opção, o do agente, e se ele não definir, `strict` |

Sem ninguém por perto, o que pediria aprovação é **negado**: o modelo vê e explica na resposta.

**Código de saída**: `0` ok · `1` o turno terminou em erro · `2` uso inválido (agente inexistente, mensagem vazia).

## `--json`: os eventos

Uma linha JSON por evento. Primeiro `session`, depois o que o agente faz, e `done` no final:

```json
{"kind": "session", "data": {"session": "20261016-125226-8941", "agent": "tienda", "thread": "cliente-42", "mode": "strict"}, "agent": "tienda", "thread": "cliente-42"}
{"kind": "tool_call", "data": {"name": "read", "args": {"path": ".lampson/tienda/catalogo.json"}}, "agent": "tienda", "thread": "cliente-42"}
{"kind": "tool_result", "data": {"call": {…}, "output": "…"}, "agent": "tienda", "thread": "cliente-42"}
{"kind": "assistant", "data": "Sim, temos pão integral a $3.200.", "agent": "tienda", "thread": "cliente-42"}
{"kind": "done", "data": {"agent": "tienda", "thread": "cliente-42", "session": "…", "text": "Sim, temos pão integral a $3.200.", "steps": 2, "usage": {"input": 1079, "output": 357, "cached": 448}, "stopped": "done"}, "agent": "tienda", "thread": "cliente-42"}
```

Os tipos de evento: `session`, `assistant`, `tool_call`, `tool_result`, `tool_denied`, `usage`, `inbox`, `error`, `compact` e `done`. Em `done`, `stopped` é `done`, `max_steps`, `budget` ou `error: …`.

## `--stdio`: um processo aberto (modo local)

`lampson run --stdio` fica aberto e atende muitos pedidos: um por linha no stdin, com um `id` seu. É o que o [SDK](/pt/docs/sdk) usa no modo local — o Lampson dentro do seu programa, sem servidor.

```json
{"id": "r1", "op": "ask", "to": "tienda", "thread": "cliente-42", "text": "vocês têm pão integral?"}
{"id": "r2", "op": "agents"}
{"id": "r3", "op": "ping"}
```

Pelo stdout saem os mesmos eventos que com `--json`, cada um com o `id` do seu pedido, e um `done` ao terminar cada `ask`. Ao iniciar ele emite `{"kind": "ready", "data": {"agents": […], "protocol": 2, "warnings": […]}}`: em `warnings`, uma linha por ferramenta que algum agente lista e não vai ter (um plugin desligado, um nome errado). Antes de um `ask` desse agente sai também um evento `warning`. Com `LAMPSON_BUILTIN_TOOLS=off`, o processo não oferece nenhuma ferramenta própria do Lampson (é a opção `lampsonTools: false` do SDK).

- Conversas **diferentes** rodam em paralelo; dois pedidos da **mesma** conversa (agente + thread) são atendidos em ordem.
- `"mode": "strict"` ou `"yolo"` em um `ask` fixa as permissões desse pedido (é o seu programa, na sua máquina).
- Ferramentas do app (o que o `lampson.tool()` do SDK usa): `{"op": "tools", "tools": [{"name", "description", "parameters", "timeout"}]}` substitui a lista inteira. Quando o modelo chama uma, sai `{"kind": "tool_request", "data": {"call_id", "name", "args", "ctx"}}`, e o seu programa responde `{"op": "tool_result", "call_id", "output"}` (ou `"error"`). `ctx` é o contexto do pedido (`from`, `thread`, `meta`…), que o modelo não escreve.
- Uma linha que não é JSON devolve um `error` e o processo continua. Fechar o stdin encerra o processo quando os pedidos em andamento terminam.