Agents API permite consumir las conversaciones de tus proyectos de Aki Agent Web desde una aplicación externa. Esto te permite automatizar tareas mediante código utilizando tu Aki Agent en otras aplicaciones. La respuesta se entrega como un flujo de eventos SSE, por lo que puedes mostrarla a medida que se genera sin esperar a que termine todo el proceso.

IMPORTANTE: Esta funcionalidad es experimental y puede cambiar en cualquier momento.

Antes de empezar

1. Ingresa a Mi cuenta → Agents API.
2. Crea una API key y guarda el secreto completo. Aki Agent no guarda el secreto en texto plano, así que solo lo mostrará una vez.
3. Usa la API key en el encabezado Authorization de cada solicitud.
4. Usa un project_id propio o permite que la API cree un proyecto nuevo para la primera prueba.

Endpoint

El endpoint público es:

POST https://aki.ar/api/agents/v1/chat
Authorization: Bearer akia_live_...
Content-Type: application/json
Accept: text/event-stream

El formulario de prueba incluido al final de esta página envía la key directamente desde tu navegador al endpoint y no la guarda. Para una integración real, mantené la key en el servidor de tu aplicación y no la incluyas en el frontend ni en un repositorio.

Enviar un mensaje a un proyecto existente

El project_id debe pertenecer al mismo usuario que creó la API key. El campo message admite como máximo 5000 caracteres.

curl -N "https://aki.ar/api/agents/v1/chat" \
  -H "Authorization: Bearer akia_live_TU_SECRETO" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "project_id": 123,
    "message": "Analiza el proyecto y propón tres mejoras concretas.",
    "model": "AUTO"
  }'

La opción -N de cURL evita que la salida del flujo se acumule antes de mostrarla.

Crear un proyecto automáticamente

Si todavía no tienes un proyecto, omite project_id y envía create_project: true. También puedes indicar project_name y design_preferences para definir los valores iniciales.

curl -N "https://aki.ar/api/agents/v1/chat" \
  -H "Authorization: Bearer akia_live_TU_SECRETO" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "create_project": true,
    "project_name": "Proyecto creado por API",
    "design_preferences": {
      "style": "minimalista",
      "primary_color": "#2563EB"
    },
    "message": "Crea la estructura inicial de una landing para una cafetería.",
    "model": "openai/gpt-5.6-luna"
  }'

Valores para `model`

model es opcional y por defecto utiliza AUTO. Algunos valores que puedes enviar son:

• AUTO: enrutador recomendado para elegir el modelo según la tarea.
• openai/gpt-5.6-luna: tareas generales, preguntas y escritura con buena velocidad.
• openai/gpt-5.3-codex: programación, análisis de datos y generación de código.
• anthropic/claude-sonnet-5: escritura creativa, análisis profundo y tareas extensas.
• x-ai/grok-4.6: razonamiento avanzado y programación.

La disponibilidad, el costo y los límites de cada modelo dependen de tu cuenta. Envía el valor del modelo, no el nombre de una variable de entorno. Por ejemplo: "model": "AUTO" o "model": "openai/gpt-5.6-luna".

Mensajes largos: contextos y skills con `@`

El límite de message es de 5000 caracteres por solicitud. No intentes superar ese límite concatenando instrucciones muy largas. Si necesitas reutilizar instrucciones, criterios o información extensa, crea un contexto o una skill prearmada en el chat y llámala con @ cuando la necesites, por ejemplo @brief-brand, @mermaid o @plan. Así el mensaje puede quedarse enfocado en la tarea puntual.

Puedes escribir una o varias menciones directamente dentro de message. La API las resuelve contra los contextos y credenciales habilitados del usuario propietario de la API key, por ejemplo:

{
  "message": "@brief-brand Aplica este contexto a la pantalla y usa también @imagen-social si corresponde.",
  "model": "AUTO"
}

La resolución se hace por usuario, no de forma global ni por project_id. Si una integración ya conoce los slugs, también puede enviar los contextos como parte de selected_skills:

{
  "message": "Aplica el contexto de marca a esta pantalla.",
  "model": "AUTO",
  "selected_skills": [
    {
      "source": "contexto",
      "skillId": "brief-brand",
      "name": "@brief-brand",
      "repoUrl": "",
      "skillsUrl": ""
    }
  ]
}

También puedes invocar skills integradas, como @mermaid, usando la mención en message; selected_skills, selected_collections y attachment_ids son arrays de hasta 100 elementos.

Ejemplo con JavaScript

El endpoint devuelve text/event-stream. Este ejemplo lee los fragmentos recibidos; tu cliente puede procesar cada evento SSE según sus necesidades.

const response = await fetch(`${BASE_URL}/api/agents/v1/chat`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.AGENTS_API_KEY}`,
    Accept: "text/event-stream",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    project_id: 123,
    message: "Revisa el código y explica los problemas principales.",
    model: "openai/gpt-5.3-codex",
  }),
});

if (!response.ok) {
  throw new Error(await response.text());
}

const reader = response.body?.getReader();
if (!reader) throw new Error("La respuesta no contiene un flujo");

const decoder = new TextDecoder();
while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  process.stdout.write(decoder.decode(value, { stream: true }));
}

Campos disponibles

• message es obligatorio y admite entre 1 y 5000 caracteres.
• project_id es obligatorio, salvo que envíes create_project: true.
• project_name y design_preferences se utilizan al crear un proyecto nuevo.
• model es opcional; por defecto se utiliza AUTO.
• selected_skills, selected_collections y attachment_ids son arrays de hasta 100 elementos.
• ui_theme puede ser light o dark.

Errores frecuentes

• 400: JSON inválido, falta message, project_id inválido o falta create_project.
• 401: API key ausente, inválida o revocada.
• 403: la cuenta está suspendida.
• 404: el proyecto no existe o no pertenece al usuario de la key.
• 413: el mensaje supera los 5000 caracteres.
• 429: se superó el límite de solicitudes.
• 502: no fue posible contactar al servicio de chat.

Revocar una API key

Puedes revocar una key desde Mi cuenta → Agents API. Las integraciones que la utilicen dejarán de autenticarse inmediatamente.