> ## Documentation Index
> Fetch the complete documentation index at: https://docs.base44.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Módulo Agents

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

<Warning>
  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](/developers).
</Warning>

# 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](#concepts)
* [Métodos](#methods)
* [Ejemplos](#examples) (Create, Get Conversations, List, Subscribe, Send Message, WhatsApp)
* [Estructura del mensaje](#message-structure)
* [Estructura de la conversación](#conversation-structure)
* [Patrones comunes](#common-patterns)

## 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

```javascript theme={null}
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

```javascript theme={null}
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).

```javascript theme={null}
const conversation = await base44.agents.getConversation("conv-id-123");

console.log(conversation.messages);
```

### Listar con filtros

```javascript theme={null}
// 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.

```javascript theme={null}
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

```javascript theme={null}
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

```javascript theme={null}
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

```javascript theme={null}
{
  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

```javascript theme={null}
{
  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

```javascript theme={null}
// 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**.

```typescript theme={null}
/**
 * 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

```typescript theme={null}
/** 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

```typescript theme={null}
/** 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

```typescript theme={null}
/** 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

```typescript theme={null}
/** 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

```typescript theme={null}
/** 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

```typescript theme={null}
/** 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;
}
```

<Note>Esta página fue traducida usando IA. Para obtener la información más precisa y actualizada, consulta la [versión en inglés](/).</Note>