Executar agents via API

Um run é uma unidade de trabalho do agent iniciada pelo seu sistema: você envia uma instrução, o agent a executa, e o run carrega o status e o resultado. Esta página percorre o ciclo completo — criar, consultar, coletar, cancelar.

Antes de começar

Um token de API com modo read_write, criado em Settings → API tokens (autenticação).
O ID do agent, visível na página do agent no dashboard.

Criar um run

Envie a instrução em input.message. Se o run reage a um evento, coloque o payload do evento em input.data — o agent o recebe como dados, nunca como instruções.

curl -X POST https://app.leme.ai/api/v1/agents/AGENT_ID/runs \
  -H "Authorization: Bearer leme_pat_v1_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: lead-4821" \
  -d '{
    "input": {
      "message": "Qualifique este lead e responda com um resumo curto.",
      "data": { "leadId": "4821", "origem": "landing-page" }
    },
    "metadata": { "leadId": "4821" }
  }'

string

obrigatório

A instrução para o agent. Até 128 KiB.

object

JSON livre com dados do evento, até 128 KiB. Chega ao agent demarcado como dado não confiável — use para payloads vindos do mundo externo.

object

Até 16 chaves de texto (valores de até 512 caracteres). Devolvido no run e nos webhooks — use para correlacionar com registros do seu sistema.

string

Continua uma sessão de API existente deste agent em vez de iniciar uma nova conversa. Runs na mesma sessão são processados em ordem.

string

URL HTTPS notificada quando o run termina. Veja Webhooks de conclusão.

string

Título opcional para a nova sessão, exibido no dashboard.

A resposta é 202 Accepted com o recurso do run:

{
  "id": "run_id",
  "object": "agent.run",
  "agentId": "agent_id",
  "sessionId": "session_id",
  "status": "queued",
  "statusDetail": null,
  "origin": "api",
  "input": { "message": "Qualifique este lead e responda com um resumo curto." },
  "output": null,
  "error": null,
  "metadata": { "leadId": "4821" },
  "createdAt": 1720000000000,
  "completedAt": null,
  "urls": { "self": "/api/v1/runs/run_id" }
}

Envie sempre um Idempotency-Key. Se a requisição for repetida, você recebe o run original de volta em vez de um duplicado. Detalhes na visão geral da API.

Acompanhar o run

Consulte a URL de urls.self até o status ser terminal:

curl https://app.leme.ai/api/v1/runs/RUN_ID \
  -H "Authorization: Bearer leme_pat_v1_..."

Status	Significado	Terminal
`queued`	Aguardando início	Não
`in_progress`	O agent está trabalhando. `statusDetail: "delegated"` indica trabalho delegado a um processo mais longo	Não
`waiting_approval`	Pausado aguardando aprovação humana no dashboard	Não
`completed`	Concluído — `output.text` traz a resposta do agent	Sim
`failed`	Algo deu errado — veja `error.code` e `error.message`	Sim
`canceled`	Cancelado antes de começar	Sim

Respostas não terminais incluem um header retry-after com o intervalo sugerido entre consultas. Quando o run conclui:

{
  "id": "run_id",
  "status": "completed",
  "output": { "text": "Lead de alta prioridade: decisor em uma empresa de 200 pessoas..." },
  "completedAt": 1720000042000
}

Um run em waiting_approval retoma depois que alguém aprova a ação pendente no dashboard. Se você registrou um callbackUrl, também recebe um evento run.waiting_approval nesse momento — útil para avisar quem aprova.

Prefere não consultar em loop? Registre um callbackUrl e receba um webhook assinado na conclusão — veja Webhooks de conclusão.

Listar runs

curl "https://app.leme.ai/api/v1/agents/AGENT_ID/runs?limit=20" \
  -H "Authorization: Bearer leme_pat_v1_..."

Retorna { "runs": [...], "nextCursor": "..." }, do mais recente para o mais antigo. Passe cursor para buscar a próxima página e status para filtrar (por exemplo, status=failed).

Cancelar um run

curl -X POST https://app.leme.ai/api/v1/runs/RUN_ID/cancel \
  -H "Authorization: Bearer leme_pat_v1_..."

Apenas runs ainda em queued podem ser cancelados. Um run já em execução retorna 409 not_cancellable; cancelar um run já finalizado é inofensivo e devolve o recurso sem alteração.

Continuar uma conversa

Cada run sem sessionId inicia uma sessão nova. Para manter contexto entre runs — uma conversa contínua com o mesmo agent — reutilize o sessionId retornado pelo primeiro run:

curl -X POST https://app.leme.ai/api/v1/agents/AGENT_ID/runs \
  -H "Authorization: Bearer leme_pat_v1_..." \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "SESSION_ID",
    "input": { "message": "Agora escreva um e-mail de follow-up para esse lead." }
  }'

A sessão aparece no dashboard como qualquer outra conversa, então seu time pode ler e assumir a qualquer momento.

Primeiros passos

Agents

Ferramentas e permissões

Automação

Artefatos

Workspace

API

Executar agents via API

Antes de começar

Criar um run

Acompanhar o run

Listar runs

Cancelar um run

Continuar uma conversa

​Antes de começar

​Criar um run

​Acompanhar o run

​Listar runs

​Cancelar um run

​Continuar uma conversa

Antes de começar

Criar um run

Acompanhar o run

Listar runs

Cancelar um run

Continuar uma conversa