Lampson como motor

Receita: receber pedidos pelo chat

Um agente que atende o chat de um negócio e recebe o pedido completo: o quê e quanto, entrega ou retirada, o endereço, o nome, como paga, o resumo, a confirmação e o número do pedido. O pedido fica salvo, o estoque baixa e o cliente fica registrado para a próxima vez.

São três arquivos: o plugin orders (vem com o Lampson), o catálogo do seu negócio e o agente.

Se em vez de um plugin você quiser ferramentas próprias, com o seu banco de dados e o cliente tirado do contexto do seu app, veja Receita: um agente de suporte.

1. O plugin orders§

Vem com o Lampson em ~/lampson/plugins/orders/. Ligue-o uma vez (/plugins on orders no terminal, ou o pill plugins na web). Suas ferramentas:

As contas quem faz é o plugin, nunca o modelo: place_order recalcula tudo a partir do catálogo, recusa uma forma de pagamento que você não aceita e não salva um pedido sem endereço ou sem estoque.

O plugin também traz suas instruções: o processo para receber um pedido (cotar sempre com quote, pedir só o que falta, resumir e esperar um "sim" antes de salvar). Por isso o prompt do seu agente não precisa explicar.

2. O catálogo§

.lampson/orders/catalog.json no seu projeto. Ao lado ficam os pedidos (P-0001.json…) e os clientes (customers.json).

{
  "store": "Panadería Sol",
  "hours": "lunes a sábado de 7 a 20 h; domingos de 8 a 13 h",
  "delivery": {"area": "hasta 5 km del local", "fee": 1500, "free_from": 15000, "eta": "1 a 2 horas"},
  "payment": ["efectivo", "transferencia", "tarjeta de débito"],
  "products": [
    {"sku": "PAN-INT", "name": "Pan integral de masa madre", "price": 3200, "unit": "unidad (700 g)", "stock": 14, "second_half": true},
    {"sku": "PAN-BLA", "name": "Pan blanco de campo", "price": 2400, "stock": 0, "notes": "vuelve mañana a las 7"},
    {"sku": "MED-LUN", "name": "Medialunas de manteca", "price": 900, "stock": 60, "pack": {"qty": 12, "price": 9600}},
    {"sku": "ALF-MAI", "name": "Alfajores de maicena", "price": 700, "stock": 40, "gluten_free": true}
  ],
  "policies": ["No hacemos descuentos fuera de las promos del catálogo."]
}

• pack: preço por quantidade (a dúzia por $9.600).
• second_half: levando 2, o segundo pela metade do preço.
• delivery.free_from: entrega grátis a partir desse subtotal.
• notes, policies e qualquer outro campo (gluten_free, vegan…) o agente lê como estão.

3. O agente§

.lampson/agents/tienda.agent.json. O prompt diz quem ele é — o processo vem do plugin:

{
  "id": "tienda",
  "description": "Atiende a los clientes de Panadería Sol por chat y toma sus pedidos",
  "base": "none",
  "system": "Eres quien atiende el chat de Panadería Sol, una panadería de barrio en Rosario. Los clientes escriben desde el celular. Tono: cálido, rioplatense (vos), breve. Sin markdown. Precios con punto de miles ($3.200). No hables de archivos ni herramientas.",
  "tools": [{"name": "plugin_orders_*", "approve": "auto"}],
  "permission": "strict",
  "steps": 10
}

"approve": "auto" deixa só as ferramentas de orders rodarem sem ninguém aprovar; todo o resto continua strict. → Agentes

4. Conectar§

lampson channel on telegram      # ou Chatwoot para WhatsApp/Instagram → /docs/channels
lampson key add --agent tienda   # ou o seu app/bot pela API → /docs/api

Uma conversa real§

Esta é uma conversa de verdade com o agente acima (modelo glm-5.3-flash), digitando como as pessoas digitam: várias mensagens seguidas, com pausas de 2 a 6 segundos. Cada mensagem entrou separada e a caixa de entrada juntou todas. Está em espanhol, como aconteceu — uma padaria de bairro em Rosário, na Argentina.

O que ficou salvo:

// .lampson/orders/P-0001.json (resumido)
{"id": "P-0001", "customer": {"name": "Martín Ferreyra"}, "delivery": "delivery",
 "address": "Entre Ríos 845, 2do A (al lado de la farmacia)", "payment": "transferencia",
 "lines": [{"sku": "MED-LUN", "qty": 12, "amount": 9600, "promo": "1 x pack of 12"},
           {"sku": "PAN-INT", "qty": 2, "amount": 4800, "promo": "1 x second at half price"},
           {"sku": "ALF-MAI", "qty": 2, "amount": 1400}],
 "delivery_fee": 0, "total": 15800, "status": "new"}

P-0002 salvou "when": "mañana 2026-10-17 a las 8 h" e a nota da surpresa. O estoque baixou (integral 14 → 12, medialunas 60 → 48, alfajores 40 → 38).

O que a conversa mostra:

• Rajadas → uma resposta. Cada bloco de 2 a 5 mensagens recebeu uma resposta que responde tudo. No quinto, o endereço chegou em quatro mensagens ao longo de 24 segundos: as que chegaram enquanto o agente trabalhava entraram no mesmo turno, e se chegam quando ele já está escrevendo a resposta, o Lampson a descarta e responde de novo com tudo.
• Sem contas inventadas. Cada total saiu de quote, com a promoção do segundo pão, o preço da dúzia e a entrega grátis a partir de $15.000.
• Sem estoque, uma alternativa. O pão branco tinha estoque 0: ele disse, disse quando volta e ofereceu opções.
• O que não sabe, não inventa. A chave para a transferência não está no catálogo, então ele não inventou uma. Coloque em policies e ele vai informar.
• Nada é salvo sem um "sim". Mostrou o resumo e esperou a confirmação.
• Tempos: cada resposta chegou de 14 a 25 segundos depois da última mensagem do cliente: os 3 segundos que a caixa de entrada espera caso ele continue digitando, mais o modelo e as ferramentas.

Um cliente que volta§

A Ana já tinha comprado (aquele pedido entrou por uma loja virtual, veja abaixo). Ela escreve de novo:

find_customer a encontrou pelo telefone, com os pedidos anteriores.

Sem chat: um pedido que chega de outro sistema§

As mesmas instruções do plugin cobrem o caso sem ninguém do outro lado: a sua loja virtual, um script ou outro agente manda o pedido completo pela API, e o agente confere e salva.

curl -X POST https://seu-lampson/w/tienda/v1/messages -H "Authorization: Bearer lk_…" \
  -d '{"to": "tienda", "thread": "web:881", "text": "Pedido de la tienda web #881 (ya pagado y confirmado por el cliente). Cliente: Ana Gómez, tel 341 555 0101. Items: 1 x PAN-SG, 6 x ALF-MAI. Retira en el local. Pago: tarjeta de débito. Respondé solo con el número de pedido y el total, o con el problema."}'

{"text": "Pedido P-0003 registrado. Total: $8.300. Retira en el local (Av. Belgrano 1450), pago con tarjeta de débito.", "steps": 3, …}

Alterar ou cancelar um pedido§

Enquanto o pedido está "new" (a loja não começou), o cliente pode alterá-lo ou cancelá-lo pelo chat: update_order recebe o carrinho completo novo, recalcula o total e move o estoque só pela diferença; cancel_order o deixa "cancelled" e devolve todo o estoque. Cada mudança fica no history do pedido.

Quando a loja muda o status ("preparing", "sent"… editando o status em .lampson/orders/P-NNNN.json), o agente não pode mais mexer nele e avisa o cliente.

Uma cliente real, com o mesmo agente:

E o Martín, quando a loja já estava fazendo a torta (P-0002 em "preparing"):

(Na primeira conversa do Martín o agente fez um pedido separado para a torta: update_order ainda não existia. Agora ele altera o pedido existente.)

Limites de hoje§

• O status de um pedido (preparing, sent…) a loja muda à mão em .lampson/orders/: ainda não há um painel para isso.
• O pagamento é com a loja; o plugin não cobra.
• Para outra coisa (horários, reservas, orçamentos), copie a pasta do plugin e mude as ferramentas e o INSTRUCTIONS.md: o mesmo padrão serve para qualquer processo.