Referência da API

Automations

Agende um prompt para um agent executar sozinho, com a versão, o ambiente, os cofres e a memória que você escolher.

Uma automation dispara um prompt para um agent em horários definidos por cron (ou sob demanda). Cada disparo cria uma session e vira um run consultável.

#Endpoints

Método	Caminho	Descrição
POST	`/v1/projects/:projectId/automations`	Cria a automation e registra a agenda.
GET	`/v1/projects/:projectId/automations`	Lista automations por cursor.
GET	`/v1/projects/:projectId/automations/:id`	Lê uma automation.
PATCH	`/v1/projects/:projectId/automations/:id`	Altera campos; só os presentes mudam.
DELETE	`/v1/projects/:projectId/automations/:id`	Remove a automation e a agenda.
POST	`/v1/projects/:projectId/automations/:id/run`	Dispara agora (202).
GET	`/v1/projects/:projectId/automations/:id/runs`	Lista os disparos por cursor.
POST	`/v1/projects/:projectId/automations/parse-schedule`	Converte uma descrição em linguagem natural para cron.

#Criar automation

json

{
  "name": "Relatório diário de pendências",
  "agentId": "agent_...",
  "agentVersion": 7,
  "prompt": "Liste as pendências abertas e resuma o que mudou desde ontem.",
  "trigger": { "type": "schedule", "cron": "0 8 * * 1-5", "timezone": "America/Sao_Paulo" },
  "environmentId": "env_...",
  "vaultIds": ["vault_..."],
  "resources": [
    { "memoryStoreId": "ms_...", "memoryStoreName": "Procedimentos", "mode": "read-write" }
  ]
}

Campo	Tipo	Observação
`name`	string	1 a 200 caracteres.
`agentId`	string	Agent que executa. Obrigatório na criação; o `PATCH` não troca de agent.
`agentVersion`	number	Pin de versão. Ausente ou `null` = versão corrente no momento do disparo.
`prompt`	string	Até 20000 caracteres. É a mensagem que abre a session.
`trigger`	object	`schedule` (com `cron`, `timezone`, `overlap`, `jitterSeconds`) ou `manual`.
`enabled`	boolean	Padrão `true`.
`environmentId`	string	Ambiente da session do disparo. `null` = ambiente base.
`vaultIds`	array	Até 16 cofres. Aceita id (`vault_...`) ou nome; a resposta traz sempre id.
`resources`	array	Até 16 mounts de memória. `memoryStoreId` aceita id (`ms_...`) ou nome.

memoryStoreName é obrigatório no corpo, mas o nome gravado vem sempre da store real.

O PATCH é parcial: campo ausente não muda. agentVersion, environmentId e description aceitam null para limpar.

#Referências validadas na escrita

Uma automation guarda ponteiros para quatro coisas que vivem fora dela — versão do agent, ambiente, cofres e repositórios de memória — e nada disso é lido no momento da escrita, só quando a agenda dispara, possivelmente semanas depois. Por isso a validação acontece na escrita, onde o erro ainda tem dono:

Código	HTTP	Quando
`automation.agent_archived`	422	Pin de versão em um agent arquivado.
`automation.agent_version_not_found`	422	A versão pedida não existe nesse agent.
`automation.environment_not_found`	422	O ambiente não existe neste projeto.
`automation.vault_not_found`	422	Um dos cofres não existe neste workspace.
`automation.memory_store_not_found`	422	Um dos repositórios de memória não existe neste projeto.
`agent.not_found`	404	O agent informado não existe no projeto.
`automation.not_found`	404	Automation inexistente ou fora do projeto.

O PATCH só revalida o que mudou de verdade. Reenviar o mesmo pin de um agent que foi arquivado depois não bloqueia a edição — senão a automation quebrada viraria uma prisão, sem como corrigi-la nem desligá-la pela tela de edição.

No disparo, a automation nunca cai por causa do pin. Se a versão fixada sumiu entre a escrita e o disparo, a execução degrada para a versão corrente e registra erro no log — melhor o relatório na versão errada do que nenhum relatório. Só quando não há versão utilizável é que o run vira error. O mesmo vale para os outros ponteiros: ambiente, cofre ou store que sumiram são soltos, e a session nasce sem eles.

#O que a automation não escolhe vem do agent

environmentId, vaultIds e resources são resolvidos no disparo, não na escrita da agenda: o que a automation declarou vence; o que ela deixou em branco cai no padrão de execução do agent e, na falta dele, no padrão da conta (ambiente padrão do projeto, sem cofre e sem memória).

Para a automation, "em branco" é null ou lista vazia — não existe a afirmação "sem cofre mesmo" que a criação de session tem. Quem precisa de uma session sem cofre remove o padrão do agent.

Como a resolução acontece no disparo, mudar o padrão do agent muda o próximo disparo da agenda. É deliberado: a automation segue o agent.

#Disparo e runs

http

POST /v1/projects/:projectId/automations/:id/run

Responde 202 com { "accepted": true } — o run acontece em workflow durável. Consulte o resultado em GET /:id/runs, que devolve o run junto do estado da session criada: