Agentes

Los agentes de IA que procesan el correo entrante: su modelo, su prompt de sistema, el historial de versiones del prompt y el catálogo de modelos disponibles. Ocho tools.

Ver el modelo Agent y el modelo LlmModel.

---

agents_list

Lectura · scope inbox/agents · permiso agents.list · GET /agents

Lista los agentes del workspace seleccionado.

Parámetro	Tipo	Descripción
cursor	string	Cursor opaco de una página anterior.
limit	integer	Tamaño de página, por defecto 25, máximo 100.
sort	string	Claves de ordenación, prefijo - para descendente.
llm_model	string	Filtra por modelo, en formato provider/model.
external_id	string	Filtra por el id en tu sistema.
created_at_gte / created_at_lte	string	Rango ISO 8601 sobre created_at.

agents_get

Lectura · scope inbox/agents · permiso agents.show · GET /agents/{id}

Obtiene un agente por id interno o external_id, incluida su versión actual.

Parámetro	Tipo	Descripción
id obligatorio	string	Id interno o external_id.

agents_create

Escritura · scope inbox/agents + write · permiso agents.create · POST /agents

Crea un agente. La versión empieza en 1.

Parámetro	Tipo	Descripción
label obligatorio	string	Nombre visible, 1–120 caracteres.
llm_model obligatorio	string	provider/model, enrutado por el Vercel AI Gateway.
system_message obligatorio	string	Prompt de sistema. Cambiarlo incrementa la versión del agente.
external_id	string	Id del registro en tu sistema.
skills_repo	string | null	URL git; la rama o el tag va en el fragmento (...git#branch).
custom_metadata	object	JSON libre, de quien llama.
idempotency_key	string	Protección contra repeticiones, 8–255 caracteres.

agents_upsert

Escritura · scope inbox/agents + write · permiso agents.create · PUT /agents

Crea o actualiza un agente, emparejado por id y luego external_id. Un system_message distinto incrementa la versión.

Parámetro	Tipo	Descripción
id	string (uuid)	Empareja primero por id interno.
external_id	string	Clave de emparejamiento en tu sistema.
label	string	Nombre visible, 1–120 caracteres.
llm_model	string	provider/model.
system_message	string	Prompt de sistema.
skills_repo	string | null	URL git, rama o tag en el fragmento.
custom_metadata	object	JSON libre.
idempotency_key	string	Protección contra repeticiones.

agents_update

Escritura · scope inbox/agents + write · permiso agents.update · PATCH /agents/{id}

Actualiza un agente. Cambiar el system_message congela una nueva versión inmutable; cambiar solo label, modelo o repositorio de skills, no.

Parámetro	Tipo	Descripción
id obligatorio	string	Id interno o external_id.
label	string	Nombre visible, 1–120 caracteres.
external_id	string	Id en tu sistema.
llm_model	string	provider/model.
system_message	string	Prompt de sistema. Cambiarlo incrementa la versión.
skills_repo	string | null	URL git, rama o tag en el fragmento.
custom_metadata	object	JSON libre.

agents_delete

Destructiva · scope inbox/agents + write · permiso agents.delete · DELETE /agents/{id}

Elimina (soft-delete) un agente. Los inboxes que apuntan a él dejan de procesar hasta que se reasignen.

Parámetro	Tipo	Descripción
id obligatorio	string	Id interno o external_id.

agents_versions_list

Lectura · scope inbox/agents · permiso agents.show · GET /agents/{id}/versions

Historial de versiones de prompt de un agente — cada entrada es el system_message exacto con el que se ejecutó una corrida.

Parámetro	Tipo	Descripción
id obligatorio	string	Id interno o external_id.
cursor	string	Cursor opaco de una página anterior.
limit	integer	Tamaño de página, por defecto 25, máximo 100.

models_list

Lectura · scope inbox/agents · permiso agents.list · GET /models

Catálogo de modelos de LLM disponibles a través del AI Gateway, con los precios actuales. No recibe parámetros.