AI 에이전트

여러 대화 턴에 걸쳐 장기 기억을 활용하는 멀티툴 오케스트레이션.

에이전트는 서버 측에서 대화 상태를 유지합니다: 모델을 호출하고, 내장 도구(기억)를 자동으로 실행하며, 최종 답변이 준비되었거나 사용자가 정의한 도구를 실행해야 할 때만 제어권을 다시 넘깁니다.

대화 만들기

http

POST /v1/agents/conversations

json

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

tools는 사용자 정의 도구를 선언합니다(아래 참조) — 내장 도구(기억, 비디오 생성)는 별도로 선언하지 않아도 항상 이용 가능합니다.

메시지 보내기

http

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

json

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

응답은 항상 대화의 전체 상태입니다:

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는 idle(새 메시지를 받을 준비됨), requires_action(사용자의 사용자 정의 도구 중 하나가 결과를 기다리는 중), 또는 generating_media(비디오 생성이 진행 중, 아래 참조) 값을 가집니다.

내장 도구

search_memory — 에이전트의 장기 기억을 검색합니다(query 매개변수, 선택적으로 top_k)
remember — 정보를 저장합니다(content 매개변수)
generate_video — 비디오 생성을 시작합니다(POST /v1/video/generate와 동일한 매개변수: prompt, duration_seconds, narration_text, scenes — 비디오 가이드 참고)

이 세 가지 도구는 서버에서 자동으로 실행됩니다 — 별도로 할 일은 없으며 대화가 스스로 이어집니다(generate_video는 예외로, 작업이 완료될 때까지 대화를 generating_media 상태로 전환합니다; idle이 될 때까지 GET /v1/agents/conversations/{id}를 폴링하세요).

사용자 정의 도구

대화를 생성할 때 자신만의 도구를 선언하세요(tools). 모델이 이를 호출하면 상태가 requires_action으로 바뀌고 대화가 멈춥니다 — 도구를 실행하고 결과를 반환하는 것은 사용자의 몫입니다:

http

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

json

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

대화가 idle 상태가 아니면 POST .../messages는 409 conflict를 반환합니다 — 새 메시지를 보내기 전에 대기 중인 도구가 처리될 때까지 기다리세요.

목록 조회 / 확인

bash

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