AI Agents

Multi-tool orchestration with long-term memory, across multiple conversation turns.

An agent maintains conversation state server-side: it calls the model, automatically executes its built-in tools (memory), and only hands control back to you once a final answer exists or a tool you defined needs to be executed.

Creating a conversation

http

POST /v1/agents/conversations

json

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

tools declares your own custom tools (see below) — built-in tools (memory, video generation) are always available without needing to be declared.

Sending a message

http

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

json

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

The response is always the full conversation state:

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 is idle (ready for a new message), requires_action (one of your custom tools is awaiting a result), or generating_media (a video generation is in progress, see below).

Built-in tools

search_memory — searches the agent's long-term memory (query parameter, optional top_k)
remember — stores a piece of information (content parameter)
generate_video — starts a video generation (same parameters as POST /v1/video/generate: prompt, duration_seconds, narration_text, scenes — see the Video guide)

These three tools are executed automatically by the server — you have nothing to do, the conversation continues on its own (except for generate_video, which puts the conversation into generating_media while the job finishes; poll GET /v1/agents/conversations/{id} until idle).

Custom tools

Declare your own tools when creating the conversation (tools). When the model calls them, the status switches to requires_action and the conversation stops — it's up to you to execute the tool and return the result:

http

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

json

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

POST .../messages returns 409 conflict if the conversation is not idle — wait for a pending tool to be resolved before sending a new message.

Listing / viewing

bash

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