Agentes

Os agentes de IA que processam o e-mail recebido: o modelo, o prompt de sistema, o histórico de versões do prompt e o catálogo de modelos disponíveis. Oito tools.

Veja o modelo Agent e o modelo LlmModel.

---

agents_list

Leitura · escopo inbox/agents · permissão agents.list · GET /agents

Lista os agentes do workspace selecionado.

Parâmetro	Tipo	Descrição
cursor	string	Cursor opaco de uma página anterior.
limit	integer	Tamanho da página, padrão 25, máximo 100.
sort	string	Chaves de ordenação, prefixo - para descendente.
llm_model	string	Filtra por modelo, no formato provider/model.
external_id	string	Filtra pelo id no seu sistema.
created_at_gte / created_at_lte	string	Intervalo ISO 8601 sobre created_at.

agents_get

Leitura · escopo inbox/agents · permissão agents.show · GET /agents/{id}

Busca um agente por id interno ou external_id, incluindo a versão atual.

Parâmetro	Tipo	Descrição
id obrigatório	string	Id interno ou external_id.

agents_create

Escrita · escopo inbox/agents + write · permissão agents.create · POST /agents

Cria um agente. A versão começa em 1.

Parâmetro	Tipo	Descrição
label obrigatório	string	Nome de exibição, 1–120 caracteres.
llm_model obrigatório	string	provider/model, roteado pelo Vercel AI Gateway.
system_message obrigatório	string	Prompt de sistema. Alterá-lo incrementa a versão do agente.
external_id	string	Id do registro no seu sistema.
skills_repo	string | null	URL git; branch ou tag vai no fragmento (...git#branch).
custom_metadata	object	JSON livre, de quem chama.
idempotency_key	string	Proteção contra replay, 8–255 caracteres.

agents_upsert

Escrita · escopo inbox/agents + write · permissão agents.create · PUT /agents

Cria ou atualiza um agente, casado por id e depois external_id. Um system_message diferente incrementa a versão.

Parâmetro	Tipo	Descrição
id	string (uuid)	Casa primeiro pelo id interno.
external_id	string	Chave de casamento no seu sistema.
label	string	Nome de exibição, 1–120 caracteres.
llm_model	string	provider/model.
system_message	string	Prompt de sistema.
skills_repo	string | null	URL git, branch ou tag no fragmento.
custom_metadata	object	JSON livre.
idempotency_key	string	Proteção contra replay.

agents_update

Escrita · escopo inbox/agents + write · permissão agents.update · PATCH /agents/{id}

Atualiza um agente. Alterar o system_message congela uma nova versão imutável; alterar apenas label, modelo ou repositório de skills, não.

Parâmetro	Tipo	Descrição
id obrigatório	string	Id interno ou external_id.
label	string	Nome de exibição, 1–120 caracteres.
external_id	string	Id no seu sistema.
llm_model	string	provider/model.
system_message	string	Prompt de sistema. Alterá-lo incrementa a versão.
skills_repo	string | null	URL git, branch ou tag no fragmento.
custom_metadata	object	JSON livre.

agents_delete

Destrutiva · escopo inbox/agents + write · permissão agents.delete · DELETE /agents/{id}

Exclui (soft-delete) um agente. As inboxes que apontam para ele param de processar até serem reatribuídas.

Parâmetro	Tipo	Descrição
id obrigatório	string	Id interno ou external_id.

agents_versions_list

Leitura · escopo inbox/agents · permissão agents.show · GET /agents/{id}/versions

Histórico de versões de prompt de um agente — cada entrada é o system_message exato com que uma execução rodou.

Parâmetro	Tipo	Descrição
id obrigatório	string	Id interno ou external_id.
cursor	string	Cursor opaco de uma página anterior.
limit	integer	Tamanho da página, padrão 25, máximo 100.

models_list

Leitura · escopo inbox/agents · permissão agents.list · GET /models

Catálogo de modelos de LLM disponíveis pelo AI Gateway, com os preços atuais. Não recebe parâmetros.