Crea aplicaciones agénticas con AceDataCloud AI Chat v2

Un endpoint de chat puede devolver texto. Un endpoint de agente puede inspeccionar un archivo, buscar en la web, llamar a una herramienta autorizada, solicitar información faltante y transmitir cada paso de vuelta a tu interfaz.

Esa es la diferencia práctica detrás de AceDataCloud AI Chat v2. El endpoint en POST https://api.acedata.cloud/aichat2/conversations conserva el estilo de solicitud simple de la API de conversación original mientras añade bloques de contenido multimodal, uso autónomo de herramientas en múltiples rondas, conexiones MCP, eventos de streaming estructurados, conversaciones reanudables y acciones CRUD de conversación.

Arquitectura de AI Chat v2: entradas multimodales, herramientas de agente y eventos estructurados

Esta guía se centra en las decisiones de integración que importan al pasar de un chatbot básico a una experiencia de agente en producción.

¿Qué cambia en AI Chat v2?

AI Chat v2 es una actualización integral de la interfaz original /aichat/conversations. Sus principales capacidades son:

  • Entrada multimodal: envía bloques ordenados de text, image_url y file_url en un solo array message.
  • Uso autónomo de herramientas: el modelo puede llamar herramientas integradas y servidores MCP autorizados por el usuario a lo largo de múltiples rondas.
  • Streaming tipado: representa texto, actividad de herramientas, citas, tarjetas, artefactos, errores y datos de finalización como eventos separados.
  • Pausar y reanudar: maneja un evento ask_user_question y continúa la misma conversación con un resultado de herramienta.
  • Gestión de conversaciones: recupera, recupera por lotes, actualiza y elimina mediante acciones en el mismo endpoint.
  • Solicitudes retrocompatibles: los clientes existentes de model + question pueden migrar cambiando la ruta del endpoint.

El cambio arquitectónico importante es que tu frontend ya no tiene que tratar la respuesta como una única cadena opaca. Puede convertirse en un espacio de trabajo impulsado por eventos.

Comienza con la ruta retrocompatible

La migración de menor riesgo es intencionalmente pequeña. Conserva el cuerpo de solicitud existente y cambia solo el endpoint:

curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer YOUR_API_TOKEN' \
  -H 'content-type: application/json' \
  -d '{
    "model": "YOUR_SUPPORTED_MODEL",
    "question": "Summarize the three most important points in this request.",
    "stateful": true
  }'

En modo JSON, la respuesta conserva la forma familiar:

{
  "answer": "...",
  "id": "conversation-uuid"
}

Conserva el id devuelto. Enviarlo en la siguiente solicitud continúa la conversación gestionada sin requerir que tu cliente reenvíe el historial completo de mensajes.

stateful tiene como valor predeterminado true. Establécelo explícitamente en false cuando una ronda no deba almacenarse.

Este primer paso de migración te permite validar la autenticación, disponibilidad del modelo, latencia y comportamiento de la aplicación antes de introducir herramientas o una nueva UI de streaming.

Usa message cuando el orden y la modalidad importen

El campo anterior question es conveniente para prompts de solo texto. Para texto mezclado con imágenes o archivos, usa un array message ordenado:

{
  "model": "YOUR_SUPPORTED_MODEL",
  "stateful": true,
  "message": [
    {
      "type": "text",
      "text": "Read the attached report and compare its chart with this screenshot. Return five findings."
    },
    {
      "type": "file_url",
      "file_url": {
        "url": "https://example.com/report.pdf"
      }
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/dashboard.png"
      }
    }
  ]
}

Los bloques de contenido compatibles son:

Bloque Valor requerido Mejor uso
text text Instrucciones, contexto y preguntas
image_url image_url.url Capturas de pantalla, gráficos, imágenes de productos
file_url file_url.url PDF, CSV, TXT y otros archivos

AI Chat v2 todavía reconoce el array anterior references. Las extensiones de imagen se convierten en bloques de imagen, mientras que otras URL se convierten en bloques de archivo. Esa compatibilidad es útil durante la migración, pero message es el mejor contrato a largo plazo cuando el orden del contenido importa.

Diseña el cliente alrededor de eventos, no solo de tokens

Elige el formato de respuesta con el encabezado accept:

Cliente Encabezado Formato
UI del navegador text/event-stream Eventos enviados por servidor
Node, Python, CLI, worker application/x-ndjson Un evento JSON por línea
Solicitud de backend simple application/json Objeto final {answer, id}

Un consumidor mínimo de NDJSON en Python puede ensamblar texto mientras conserva otros tipos de eventos:

import json
import os
import requests

url = "https://api.acedata.cloud/aichat2/conversations"
headers = {
    "accept": "application/x-ndjson",
    "authorization": f"Bearer {os.environ['ACEDATA_API_TOKEN']}",
    "content-type": "application/json",
}
payload = {
    "model": os.environ["ACEDATA_CHAT_MODEL"],
    "question": "Research the topic, cite sources, and return a concise brief.",
    "stateful": True,
}

with requests.post(url, json=payload, headers=headers, stream=True, timeout=120) as response:
    response.raise_for_status()
    answer = []

    for raw_line in response.iter_lines():
        if not raw_line:
            continue

        event = json.loads(raw_line)
        event_type = event.get("type")

        if event_type == "text_delta":
            answer.append(event.get("content", ""))
        elif event_type == "tool_use":
            print("tool started:", event.get("tool_name"))
        elif event_type == "tool_result":
            print("tool finished; error =", event.get("is_error"))
        elif event_type == "citation":
            print("source:", event)
        elif event_type == "artifact":
            print("artifact:", event)
        elif event_type == "error":
            raise RuntimeError(event.get("message", "unknown agent error"))
        elif event_type == "done":
            print("usage:", event.get("usage"))
            print("terminal reason:", event.get("terminal_reason"))

print("".join(answer))

Las interfaces de producción deben definir un renderizador o controlador para cada familia de eventos:

  • text_delta actualiza la región de respuesta.
  • tool_use y tool_result impulsan los estados de actividad y las vistas de auditoría.
  • citation adjunta fuentes a la salida relevante.
  • card representa vistas previas estructuradas.
  • artifact expone un entregable generado por separado.
  • thinking debe manejarse solo cuando el modelo elegido lo exponga.
  • error termina o recupera la ronda actual.
  • done cierra el stream y registra el uso de tokens junto con la razón de terminación.

Si tu interfaz solo necesita la respuesta final, concatena content de cada text_delta. Eso equivale al answer devuelto en modo JSON.

Permite que el agente use herramientas, pero haz visible la actividad

Las llamadas a herramientas están habilitadas de forma predeterminada. AI Chat v2 puede usar capacidades integradas como búsqueda web, extracción de páginas y lectura de archivos. También puede montar conexiones MCP autorizadas por el usuario, como Google Drive, Notion, Slack o GitHub.

El stream expone claramente el límite:

{"type":"tool_use","tool_id":"toolu_01","tool_name":"web_search","input":{"query":"topic"}}
{"type":"tool_result","tool_id":"toolu_01","output":"...","is_error":false}

Empareja tool_use y tool_result mediante tool_id. Esto permite indicadores de progreso, mediciones de latencia, manejo de errores y un registro de auditoría legible para el operador.

Usa max_turns para limitar cuántas rondas autónomas de herramientas pueden ocurrir en una solicitud. El rango aceptado es de 1 a 500; el valor predeterminado documentado es 500. Un valor menor reduce la ejecución abierta. Establecer max_turns: 1 fuerza una única respuesta y evita llamadas a herramientas.

Un patrón práctico de despliegue es:

  1. Comienza en modo JSON sin herramientas en la UI del producto.
  2. Añade NDJSON o SSE y representa text_delta junto con done.
  3. Muestra la actividad de herramientas como una línea de tiempo contraída.
  4. Añade representación de citas y artefactos.
  5. Establece un max_turns deliberado según la complejidad de la tarea y la tolerancia de costos.
  6. Habilita conexiones con capacidad de escritura solo después de revisar su modelo de confirmación.

Maneja las preguntas como una máquina de estados reanudable

Un agente a veces necesita aclaración. En ese caso, el stream puede emitir ask_user_question, y la conversación entra en un estado awaiting_user_input.

Tu cliente debe:

  1. Guardar el id de conversación y el tool_id.
  2. Representar la pregunta y sus opciones.
  3. Recopilar la respuesta del usuario.
  4. Enviar otra solicitud con el mismo id de conversación.
  5. Devolver la respuesta a través de tool_results para la llamada de herramienta pendiente. Esto es más sólido que pretender que el agente puede terminar con información faltante. También hace posibles las puertas de aprobación para acciones sensibles.

Separar la ejecución interactiva y desatendida

Para webhooks, trabajos de CI/CD y sistemas de monitorización, async: true devuelve un identificador de tarea mientras el trabajo continúa. El resultado puede recuperarse más tarde o entregarse a una URL de callback HTTP(S).

El acceso de escritura desatendido debe ser explícito. AI Chat v2 admite allowed_skills, allowed_mcp_servers o un objeto equivalente unattended_policy. Una lista vacía no autoriza ninguna capacidad. La preautorización no omite el propio mecanismo de seguridad de un conector; una habilidad que no admite confirmación desatendida debería seguir realizando una ejecución en seco o rechazar la escritura.

Esa distinción importa: la disponibilidad de la conexión no es lo mismo que el permiso para actuar sin una persona presente.

Lista de verificación para producción

Antes de lanzar una interfaz agéntica, verifica:

  • Las credenciales de API se almacenan en el lado del servidor, nunca en el código del navegador.
  • Los nombres de los modelos proceden de la lista actual de modelos compatibles en lugar de suposiciones codificadas de forma rígida.
  • El analizador de flujos tolera fragmentos parciales de red y tipos de eventos desconocidos.
  • Los eventos de herramientas se emparejan mediante tool_id y los errores se registran.
  • max_turns se establece intencionadamente.
  • Las URL de citas y artefactos se representan de forma segura.
  • ask_user_question conserva suficiente estado para reanudar más tarde.
  • Las conexiones con capacidad de escritura conservan la confirmación o una autorización desatendida de alcance limitado.
  • done.usage y terminal_reason alimentan la observabilidad.
  • Las políticas de eliminación y retención de conversaciones coinciden con los requisitos de tu producto.

El camino más corto de chatbot a agente

AI Chat v2 no obliga a una reescritura completa. Empieza cambiando el endpoint y conservando el cuerpo de solicitud actual. Luego pasa a bloques multimodales de message, adopta el streaming estructurado, expón el progreso de las herramientas y añade el manejo de pausa y reanudación.

El resultado es un cliente que puede crecer desde respuestas simples hasta un flujo de trabajo de agente auditable, sin inventar un protocolo independiente para archivos, herramientas, citas, artefactos o aclaraciones del usuario.

Recursos oficiales