Esta página es parte de una habilidad de agente de codificación con IA y está escrita para agentes, no para humanos. Para la documentación de Base44 legible por humanos, consulta la documentación para desarrolladores.

Módulo Agents

Conversaciones y mensajes de agentes de IA mediante base44.agents.

Nota: Este módulo requiere un usuario registrado. Todos los métodos de agente funcionan en el contexto del usuario autenticado.

Contenido

Conceptos
Métodos
Ejemplos (Create, Get Conversations, List, Subscribe, Send Message, WhatsApp)
Estructura del mensaje
Estructura de la conversación
Patrones comunes

Conceptos

Conversation: Un diálogo entre un usuario y un agente de IA. Tiene ID único, nombre de agente, referencia de usuario y metadatos.
Message: Mensaje único en una conversación. Tiene rol (user, assistant, system), contenido, marcas de tiempo y metadatos opcionales.

Métodos

Método	Firma	Descripción
`createConversation(params)`	`Promise<Conversation>`	Crea una nueva conversación con un agente
`getConversations()`	`Promise<Conversation[]>`	Obtiene todas las conversaciones del usuario
`getConversation(id)`	`Promise<Conversation>`	Obtiene la conversación con mensajes (incluye resultados completos de llamadas a herramientas)
`listConversations(filterParams)`	`Promise<Conversation[]>`	Filtra/ordena/pagina conversaciones
`subscribeToConversation(id, onUpdate?)`	`() => void`	Actualizaciones en tiempo real mediante WebSocket; datos de llamadas a herramientas truncados (devuelve función de cancelación de suscripción)
`addMessage(conversation, message)`	`Promise<Message>`	Envía un mensaje
`getWhatsAppConnectURL(agentName)`	`string`	Obtiene la URL de conexión de WhatsApp para el agente

Ejemplos

Crear conversación

const conversation = await base44.agents.createConversation({
  agent_name: "support-agent",
  metadata: {
    order_id: "ORD-123",
    category: "billing"
  }
});

console.log(conversation.id);

Obtener todas las conversaciones

const conversations = await base44.agents.getConversations();

conversations.forEach(conv => {
  console.log(conv.id, conv.agent_name, conv.created_date);
});

Obtener una sola conversación (con mensajes)

Devuelve la conversación almacenada completa, incluyendo los resultados completos de las llamadas a herramientas (a diferencia de la suscripción en tiempo real, que trunca los datos de las llamadas a herramientas).

const conversation = await base44.agents.getConversation("conv-id-123");

console.log(conversation.messages);

Listar con filtros

// Usando el objeto filterParams con q, sort, limit, skip, fields
const recent = await base44.agents.listConversations({
  q: { agent_name: "support-agent" },
  sort: "-created_date",
  limit: 10,
  skip: 0
});

// Filtrar por metadatos
const highPriority = await base44.agents.listConversations({
  q: {
    agent_name: "support-agent",
    "metadata.priority": "high"
  },
  sort: "-updated_date",
  limit: 20
});

Suscribirse a actualizaciones (tiempo real)

Al recibir mensajes a través de esta suscripción, los datos de las llamadas a herramientas se truncan por eficiencia (arguments_string limitado a 500 caracteres, results a 50). Usa getConversation() después de que se complete el mensaje para recuperar los datos completos de las llamadas a herramientas.

const unsubscribe = base44.agents.subscribeToConversation(
  "conv-id-123",
  (updatedConversation) => {
    // Llamado cuando llegan nuevos mensajes
    console.log("New messages:", updatedConversation.messages);
  }
);

// Más tarde: cancelar suscripción
unsubscribe();

Enviar un mensaje

const conversation = await base44.agents.getConversation("conv-id-123");

await base44.agents.addMessage(conversation, {
  role: "user",
  content: "What's the weather like today?"
});

Obtener URL de conexión de WhatsApp

const whatsappUrl = base44.agents.getWhatsAppConnectURL("support-agent");
// Devuelve la URL para que los usuarios se conecten con el agente mediante WhatsApp
console.log(whatsappUrl);

Estructura del mensaje

{
  role: "user" | "assistant" | "system",
  content: "Message text or structured object",
  created_date: "2024-01-15T10:30:00Z",
  updated_date: "2024-01-15T10:30:00Z",
  
  // Campos opcionales
  reasoning: {
    content: "Agent's reasoning process",
    timing: 1500
  },
  tool_calls: [{
    name: "search",
    arguments: { query: "weather" },
    result: { ... },
    status: "success"
  }],
  file_urls: ["https://..."],
  usage: {
    prompt_tokens: 150,
    completion_tokens: 50
  },
  metadata: { ... },
  custom_context: { ... }
}

Estructura de la conversación

{
  id: "conv-id-123",
  app_id: "app-id",
  agent_name: "support-agent",
  created_by_id: "user-id",
  created_date: "2024-01-15T10:00:00Z",
  updated_date: "2024-01-15T10:30:00Z",
  messages: [ ... ],
  metadata: { ... }
}

Patrones comunes

Interfaz de chat

// Cargar conversación
const conv = await base44.agents.getConversation(conversationId);
setMessages(conv.messages);

// Suscribirse a actualizaciones
const unsubscribe = base44.agents.subscribeToConversation(conversationId, (updated) => {
  setMessages(updated.messages);
});

// Enviar mensaje
async function sendMessage(text) {
  await base44.agents.addMessage(conv, { role: "user", content: text });
}

// Limpieza al desmontar
return () => unsubscribe();

Definiciones de tipos

AgentNameRegistry y AgentName

Cómo obtener nombres de agente tipados: La CLI de Base44 puede generar una augmentación de AgentNameRegistry desde tu proyecto. Para saber cómo ejecutarlo, usa la habilidad base44-cli.

/**
 * Registro de nombres de agente.
 * Aumenta esta interfaz para habilitar autocompletado para nombres de agente.
 * Normalmente lo rellena el generador de tipos de la CLI de Base44.
 */
interface AgentNameRegistry {}

/**
 * Tipo de nombre de agente - usa claves del registro si está aumentado, de lo contrario string.
 */
type AgentName = keyof AgentNameRegistry extends never ? string : keyof AgentNameRegistry;

AgentConversation

/** Una conversación de agente que contiene mensajes intercambiados con un agente de IA. */
interface AgentConversation {
  /** Identificador único para la conversación. */
  id: string;
  /** ID de la aplicación. */
  app_id: string;
  /** Nombre del agente en esta conversación. */
  agent_name: string;
  /** ID del usuario que creó la conversación. */
  created_by_id: string;
  /** Cuándo se creó la conversación. */
  created_date: string;
  /** Cuándo se actualizó por última vez la conversación. */
  updated_date: string;
  /** Array de mensajes en la conversación. */
  messages: AgentMessage[];
  /** Metadatos opcionales asociados a la conversación. */
  metadata?: Record<string, any>;
}

AgentMessage

/** Un mensaje en una conversación de agente. */
interface AgentMessage {
  /** Identificador único para el mensaje. */
  id: string;
  /** Rol del remitente del mensaje. */
  role: "user" | "assistant" | "system";
  /** Cuándo se creó el mensaje. */
  created_date: string;
  /** Cuándo se actualizó por última vez el mensaje. */
  updated_date: string;
  /** Contenido del mensaje. */
  content?: string | Record<string, any>;
  /** Información opcional de razonamiento para el mensaje. */
  reasoning?: AgentMessageReasoning | null;
  /** URLs de archivos adjuntos al mensaje. */
  file_urls?: string[];
  /** Llamadas a herramientas realizadas por el agente. */
  tool_calls?: AgentMessageToolCall[];
  /** Estadísticas de uso de tokens. */
  usage?: AgentMessageUsage;
  /** Si el mensaje está oculto del usuario. */
  hidden?: boolean;
  /** Contexto personalizado proporcionado con el mensaje. */
  custom_context?: AgentMessageCustomContext[];
  /** Modelo usado para generar el mensaje. */
  model?: string;
  /** ID de checkpoint para el mensaje. */
  checkpoint_id?: string;
  /** Metadatos sobre cuándo y por quién se creó el mensaje. */
  metadata?: AgentMessageMetadata;
}

Tipos de soporte

/** Información de razonamiento para un mensaje de agente. */
interface AgentMessageReasoning {
  /** Cuándo comenzó el razonamiento. */
  start_date: string;
  /** Cuándo terminó el razonamiento. */
  end_date?: string;
  /** Contenido del razonamiento. */
  content: string;
}

/** Una llamada a herramienta realizada por el agente. */
interface AgentMessageToolCall {
  /** ID de llamada a herramienta. */
  id: string;
  /** Nombre de la herramienta llamada. */
  name: string;
  /** Argumentos pasados a la herramienta como string JSON. */
  arguments_string: string;
  /** Estado de la llamada a herramienta. */
  status: "running" | "success" | "error" | "stopped";
  /** Resultados de la llamada a herramienta. */
  results?: string;
}

/** Estadísticas de uso de tokens para un mensaje de agente. */
interface AgentMessageUsage {
  /** Número de tokens en el prompt. */
  prompt_tokens?: number;
  /** Número de tokens en el completado. */
  completion_tokens?: number;
}

/** Contexto personalizado proporcionado con un mensaje de agente. */
interface AgentMessageCustomContext {
  /** Mensaje de contexto. */
  message: string;
  /** Datos asociados para el contexto. */
  data: Record<string, any>;
  /** Tipo de contexto. */
  type: string;
}

/** Metadatos sobre cuándo y por quién se creó un mensaje. */
interface AgentMessageMetadata {
  /** Cuándo se creó el mensaje. */
  created_date: string;
  /** Correo del usuario que creó el mensaje. */
  created_by_email: string;
  /** Nombre completo del usuario que creó el mensaje. */
  created_by_full_name: string;
}

CreateConversationParams

/** Parámetros para crear una nueva conversación. */
interface CreateConversationParams {
  /** El nombre del agente con el que crear una conversación. */
  agent_name: AgentName;
  /** Metadatos opcionales para adjuntar a la conversación. */
  metadata?: Record<string, any>;
}

ModelFilterParams

/** Parámetros para filtrar, ordenar y paginar conversaciones. */
interface ModelFilterParams {
  /** Objeto de consulta con pares campo-valor para filtrar. */
  q?: Record<string, any>;
  /** Parámetro de ordenación (por ejemplo, "-created_date" para descendente). */
  sort?: string | null;
  /** Número máximo de resultados a devolver. */
  limit?: number | null;
  /** Número de resultados a saltar para paginación. */
  skip?: number | null;
  /** Array de nombres de campo a incluir en la respuesta. */
  fields?: string[] | null;
}

AgentsModule

/** Módulo Agents para gestionar conversaciones de agente de IA. */
interface AgentsModule {
  /** Obtiene todas las conversaciones de todos los agentes en la app. */
  getConversations(): Promise<AgentConversation[]>;

  /** Obtiene una conversación específica por ID. Devuelve la conversación almacenada completa incluyendo los resultados completos de llamadas a herramientas. */
  getConversation(conversationId: string): Promise<AgentConversation | undefined>;

  /** Lista conversaciones con filtrado, ordenación y paginación. */
  listConversations(filterParams: ModelFilterParams): Promise<AgentConversation[]>;

  /** Crea una nueva conversación con un agente. */
  createConversation(conversation: CreateConversationParams): Promise<AgentConversation>;

  /** Añade un mensaje a una conversación. */
  addMessage(conversation: AgentConversation, message: Partial<AgentMessage>): Promise<AgentMessage>;

  /** Suscribe a actualizaciones en tiempo real para una conversación. Devuelve función de cancelación de suscripción. */
  subscribeToConversation(conversationId: string, onUpdate?: (conversation: AgentConversation) => void): () => void;

  /** Obtiene la URL de conexión de WhatsApp para un agente. */
  getWhatsAppConnectURL(agentName: AgentName): string;
}

Esta página fue traducida usando IA. Para obtener la información más precisa y actualizada, consulta la versión en inglés.

​Módulo Agents

​Contenido

​Conceptos

​Métodos

​Ejemplos

​Crear conversación

​Obtener todas las conversaciones

​Obtener una sola conversación (con mensajes)

​Listar con filtros

​Suscribirse a actualizaciones (tiempo real)

​Enviar un mensaje

​Obtener URL de conexión de WhatsApp

​Estructura del mensaje

​Estructura de la conversación

​Patrones comunes

​Interfaz de chat

​Definiciones de tipos

​AgentNameRegistry y AgentName

​AgentConversation

​AgentMessage

​Tipos de soporte

​CreateConversationParams

​ModelFilterParams

​AgentsModule

Módulo Agents

Contenido

Conceptos

Métodos

Ejemplos

Crear conversación

Obtener todas las conversaciones

Obtener una sola conversación (con mensajes)

Listar con filtros

Suscribirse a actualizaciones (tiempo real)

Enviar un mensaje

Obtener URL de conexión de WhatsApp

Estructura del mensaje

Estructura de la conversación

Patrones comunes

Interfaz de chat

Definiciones de tipos

AgentNameRegistry y AgentName

AgentConversation

AgentMessage

Tipos de soporte

CreateConversationParams

ModelFilterParams

AgentsModule