Crear Conversación

Esta guía explica cómo crear una nueva conversación utilizando la API del sistema de agentes.

Endpoint

POST /api/conversations

Autenticación

La API requiere una clave de API válida que debe enviarse en uno de los siguientes headers:

Authorization: Bearer {api_key}
x-api-key: {api_key}

API Key de Ejemplo

<API_TOKEN>

Estructura de la Petición

Headers Requeridos

Content-Type: application/json
Authorization: Bearer <API_TOKEN>

Body de la Petición

{
  "agentId": "string",
  "sessionId": "string",
  "extraData": {
    "key": "value"
  },
  "messages": [
    {
      "role": "USER" | "ASSISTANT",
      "content": "string",
      "toolName": "string",
      "toolArgs": {
        "key": "value"
      }
    }
  ]
}

Parámetros

Campo	Tipo	Requerido	Descripción
`agentId`	string	✅	ID del agente que manejará la conversación
`sessionId`	string	✅	Identificador único de la sesión (se usa como uniqueId)
`extraData`	object	❌	Datos adicionales para la conversación (puede incluir sender, status, etc.)
`messages`	array	❌	Lista de mensajes para crear junto con la conversación
`messages[].role`	string	✅	Rol del mensaje: "USER" o "ASSISTANT"
`messages[].content`	string	❌	Contenido del mensaje
`messages[].toolName`	string	❌	Nombre de la herramienta utilizada
`messages[].toolArgs`	object	❌	Argumentos de la herramienta

Comportamiento de Eliminación y Recreación

Importante: Si ya existe una conversación con el mismo sessionId, el sistema:

Elimina la conversación existente y todos sus mensajes
Crea una nueva conversación con el mismo sessionId como uniqueId
Preserva el sessionId pero actualiza todos los demás datos (sender, status, extraData, messages)

Esto permite "reiniciar" conversaciones manteniendo el mismo identificador de sesión.

Ejemplo de Eliminación/Recreación

# Primera conversación
curl -X POST https://dev-agents.hal.onl/api/conversations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -d '{
    "agentId": "cmb66vgdq0008lta8wuc9etm9",
    "sessionId": "session-123",
    "extraData": {
      "sender": "user",
      "status": "active"
    },
    "messages": [
      {"role": "USER", "content": "Hola, primera conversación"}
    ]
  }'

# Segunda conversación con el mismo sessionId (elimina la anterior)
curl -X POST https://dev-agents.hal.onl/api/conversations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -d '{
    "agentId": "cmb66vgdq0008lta8wuc9etm9",
    "sessionId": "session-123",
    "extraData": {
      "sender": "admin",
      "status": "completed"
    },
    "messages": [
      {"role": "USER", "content": "Hola, segunda conversación"},
      {"role": "ASSISTANT", "content": "Esta es una nueva conversación"}
    ]
  }'

Ejemplos de Uso

Ejemplo 1: Conversación Básica

curl -X POST https://dev-agents.hal.onl/api/conversations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -d '{
    "agentId": "cmb66vgdq0008lta8wuc9etm9",
    "sessionId": "session-123",
    "extraData": {
      "sender": "user",
      "status": "active"
    }
  }'

Ejemplo 2: Conversación con Datos Adicionales

curl -X POST https://dev-agents.hal.onl/api/conversations \
  -H "Content-Type: application/json" \
  -H "x-api-key: <API_TOKEN>" \
  -d '{
    "agentId": "cmb66vgdq0008lta8wuc9etm9",
    "sessionId": "session-456",
    "extraData": {
      "sender": "admin",
      "status": "in_progress",
      "userId": "user_12345",
      "sessionType": "support",
      "priority": "high",
      "metadata": {
        "source": "web",
        "referrer": "https://example.com"
      }
    }
  }'

Ejemplo 3: Conversación con Mensajes Incluidos

curl -X POST https://dev-agents.hal.onl/api/conversations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -d '{
    "agentId": "cmb66vgdq0008lta8wuc9etm9",
    "sessionId": "medical-session-789",
    "extraData": {
      "sender": "patient",
      "status": "consultation",
      "patientId": "patient_456",
      "appointmentId": "apt_789"
    },
    "messages": [
      {
        "role": "USER",
        "content": "Hola, necesito una consulta médica"
      },
      {
        "role": "ASSISTANT",
        "content": "Hola, estaré encantado de ayudarte. ¿Cuál es tu consulta?"
      },
      {
        "role": "USER",
        "content": "Tengo dolor de cabeza desde hace 3 días"
      },
      {
        "role": "ASSISTANT",
        "content": "Entiendo. Voy a buscar información sobre posibles causas.",
        "toolName": "search_medical_info",
        "toolArgs": {
          "symptoms": ["dolor de cabeza"],
          "duration": "3 días"
        }
      }
    ]
  }'

Ejemplo 4: Usando JavaScript

const createConversation = async options => {
  const { agentId, sessionId, extraData, messages } = options

  const response = await fetch('https://dev-agents.hal.onl/api/conversations', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: 'Bearer <API_TOKEN>',
    },
    body: JSON.stringify({
      agentId,
      sessionId,
      extraData,
      messages,
    }),
  })

  if (!response.ok) {
    throw new Error(`Error: ${response.status}`)
  }

  return await response.json()
}

// Uso básico
const conversation = await createConversation({
  agentId: 'cmb66vgdq0008lta8wuc9etm9',
  sessionId: 'session-123',
  extraData: {
    sender: 'user',
    status: 'active',
    userId: 'user_12345',
    context: 'customer_support',
  },
})

// Uso con mensajes iniciales
const conversationWithMessages = await createConversation({
  agentId: 'cmb66vgdq0008lta8wuc9etm9',
  sessionId: 'medical-session-456',
  extraData: {
    sender: 'patient',
    status: 'consultation',
    patientId: 'patient_456',
    appointmentId: 'apt_789',
  },
  messages: [
    {
      role: 'USER',
      content: 'Hola, necesito una consulta médica',
    },
    {
      role: 'ASSISTANT',
      content: 'Hola, estaré encantado de ayudarte. ¿Cuál es tu consulta?',
    },
    {
      role: 'USER',
      content: 'Tengo dolor de cabeza desde hace 3 días',
    },
  ],
})

Ejemplo 5: Usando Python

import requests
import json

def create_conversation(agent_id, session_id, extra_data=None, messages=None):
    url = 'https://dev-agents.hal.onl/api/conversations'
    headers = {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer <API_TOKEN>'
    }

    payload = {
        'agentId': agent_id,
        'sessionId': session_id
    }
    
    if extra_data:
        payload['extraData'] = extra_data
    
    if messages:
        payload['messages'] = messages

    response = requests.post(url, headers=headers, json=payload)

    if response.status_code == 201:
        return response.json()
    else:
        raise Exception(f'Error {response.status_code}: {response.text}')

# Uso básico
conversation = create_conversation(
    agent_id='cmb66vgdq0008lta8wuc9etm9',
    session_id='session-123',
    extra_data={
        'sender': 'user',
        'status': 'active',
        'user_id': 'user_12345',
        'session_type': 'consultation'
    }
)

# Uso con mensajes
conversation_with_messages = create_conversation(
    agent_id='cmb66vgdq0008lta8wuc9etm9',
    session_id='medical-session-456',
    extra_data={
        'sender': 'patient',
        'status': 'consultation',
        'patient_id': 'patient_456',
        'appointment_id': 'apt_789'
    },
    messages=[
        {'role': 'USER', 'content': 'Hola, necesito una consulta médica'},
        {'role': 'ASSISTANT', 'content': 'Hola, estaré encantado de ayudarte. ¿Cuál es tu consulta?'}
    ]
)

Respuestas

Respuesta Exitosa (201 Created)

{
  "success": true,
  "conversation": {
    "id": "cm456def789ghi012",
    "uniqueId": "medical-session-789",
    "agentId": "cmb66vgdq0008lta8wuc9etm9",
    "extraData": {
      "sender": "patient",
      "status": "consultation",
      "patientId": "patient_456",
      "appointmentId": "apt_789"
    },
    "summaryByAI": "El usuario solicita una consulta médica y menciona dolor de cabeza de 3 días.",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "messages": [
      {
        "id": "msg_001",
        "role": "USER",
        "content": "Hola, necesito una consulta médica",
        "createdAt": "2024-01-15T10:30:01.000Z"
      },
      {
        "id": "msg_002",
        "role": "ASSISTANT",
        "content": "Hola, estaré encantado de ayudarte. ¿Cuál es tu consulta?",
        "createdAt": "2024-01-15T10:30:02.000Z"
      },
      {
        "id": "msg_003",
        "role": "USER",
        "content": "Tengo dolor de cabeza desde hace 3 días",
        "createdAt": "2024-01-15T10:30:03.000Z"
      },
      {
        "id": "msg_004",
        "role": "ASSISTANT",
        "content": "Entiendo. Voy a buscar información sobre posibles causas.",
        "toolName": "search_medical_info",
        "toolArgs": {
          "symptoms": ["dolor de cabeza"],
          "duration": "3 días"
        },
        "createdAt": "2024-01-15T10:30:04.000Z"
      }
    ]
  }
}

Campos de la Respuesta

Campo	Tipo	Descripción
`success`	boolean	Indica si la operación fue exitosa
`conversation.id`	string	ID interno de la conversación
`conversation.uniqueId`	string	UUID único de la conversación
`conversation.agentId`	string	ID del agente asignado
`conversation.extraData`	object	Datos adicionales almacenados
`conversation.summaryByAI`	string	Resumen generado por IA
`conversation.createdAt`	string	Fecha de creación en formato ISO
`conversation.messages`	array	Lista de mensajes de la conversación
`conversation.messages[].id`	string	ID único del mensaje
`conversation.messages[].role`	string	Rol del mensaje (USER o ASSISTANT)
`conversation.messages[].content`	string	Contenido del mensaje
`conversation.messages[].toolName`	string	Nombre de la herramienta utilizada
`conversation.messages[].toolArgs`	object	Argumentos de la herramienta
`conversation.messages[].createdAt`	string	Fecha de creación del mensaje en formato ISO

Códigos de Error

400 Bad Request

{
  "success": false,
  "error": "agentId es requerido"
}

{
  "success": false,
  "error": "sessionId es requerido"
}

401 Unauthorized

{
  "success": false,
  "error": "API key requerida en header Authorization o x-api-key"
}

{
  "success": false,
  "error": "API key inválida"
}

404 Not Found

{
  "success": false,
  "error": "Agente no encontrado o inactivo"
}

500 Internal Server Error

{
  "success": false,
  "error": "Error interno del servidor"
}