Agentes de IA

Orquestación multiherramienta con memoria a largo plazo, a lo largo de varios turnos de conversación.

Un agente mantiene el estado de una conversación en el servidor: llama al modelo, ejecuta automáticamente sus herramientas integradas (memoria), y solo devuelve el control cuando existe una respuesta final o cuando una herramienta que tú has definido debe ejecutarse.

Crear una conversación

http

POST /v1/agents/conversations

json

{
  "model": null,
  "routing_strategy": "auto",
  "system_prompt": "Tu es un assistant utile et concis.",
  "tools": []
}

tools declara tus propias herramientas personalizadas (ver más abajo) — las herramientas integradas (memoria, generación de vídeo) siempre están disponibles sin necesidad de declararlas.

Enviar un mensaje

http

POST /v1/agents/conversations/{id}/messages

json

{ "content": "Retiens que mon fournisseur prefere est Anthropic." }

La respuesta es siempre el estado completo de la conversación:

json

{
  "id": "1a63c0df-...",
  "model": null,
  "routing_strategy": "auto",
  "status": "idle",
  "messages": [
    { "id": "...", "role": "user", "content": "Retiens que mon fournisseur prefere est Anthropic.", "tool_calls": null, "tool_call_id": null },
    { "id": "...", "role": "assistant", "content": "", "tool_calls": [{ "id": "call_1", "name": "remember", "arguments": { "content": "Fournisseur prefere : Anthropic" } }], "tool_call_id": null },
    { "id": "...", "role": "tool", "content": "Memoire enregistree (id=...)", "tool_call_id": "call_1" },
    { "id": "...", "role": "assistant", "content": "C'est note !", "tool_calls": null, "tool_call_id": null }
  ],
  "created_at": "...",
  "updated_at": "..."
}

status vale idle (listo para un nuevo mensaje), requires_action (una de tus herramientas personalizadas espera un resultado) o generating_media (una generación de vídeo está en curso, ver más abajo).

Herramientas integradas

search_memory — busca en la memoria a largo plazo del agente (parámetro query, opcional top_k)
remember — guarda una información (parámetro content)
generate_video — inicia una generación de vídeo (mismos parámetros que POST /v1/video/generate: prompt, duration_seconds, narration_text, scenes — ver la guía Vídeo)

Estas tres herramientas son ejecutadas automáticamente por el servidor — no tienes que hacer nada, la conversación continúa sola (excepto para generate_video, que pone la conversación en generating_media mientras el job termina; consulta GET /v1/agents/conversations/{id} hasta idle).

Herramientas personalizadas

Declara tus propias herramientas al crear la conversación (tools). Cuando el modelo las llama, el estado pasa a requires_action y la conversación se detiene — te corresponde a ti ejecutar la herramienta y devolver el resultado:

http

POST /v1/agents/conversations/{id}/tool-outputs

json

{
  "outputs": [
    { "tool_call_id": "call_2", "output": "18C, nuageux" }
  ]
}

POST .../messages devuelve 409 conflict si la conversación no está idle — espera a que se resuelva una herramienta pendiente antes de enviar un nuevo mensaje.

Listar / consultar

bash

GET /v1/agents/conversations          # liste (resume, sans les messages)
GET /v1/agents/conversations/{id}      # detail complet