# Cómo construir un agente de IA

Un **agente de IA** es un programa que recibe una instrucción en lenguaje natural, decide qué herramientas usar para cumplirla, las ejecuta y responde. Lo que lo separa de una integración normal con un modelo de lenguaje es la palabra *decide*: nadie escribió por adelantado la secuencia de pasos.

En Meteor un agente se llama **Met**, y son tres cosas: un **prompt** que define qué hace, un conjunto de **herramientas** que puede usar, y **acceso a datos** del negocio. El modelo de lenguaje es el cuarto componente y el más intercambiable — no es lo que determina si el agente sirve.

## Agente o flujo: la decisión que hay que tomar primero

Es la confusión más costosa, porque se paga en producción y no en desarrollo.

| | agente | flujo |
|---|---|---|
| decide la secuencia | el modelo, en cada ejecución | tú, al construirlo |
| bueno para | lo que no se puede prever | lo que no puede improvisarse |
| ejemplo | responder una consulta que nadie anticipó | cobrar, despachar, notificar |
| falla como | contesta algo razonable pero equivocado | se queda quieto ante lo inesperado |

La respuesta correcta casi nunca es una de las dos: **el agente atiende la conversación y llama a un flujo cuando hay que ejecutar algo que no admite improvisación.** Un agente que cobra decidiendo el monto es un incidente esperando su turno; un flujo que intenta atender una queja es un formulario disfrazado.

En Meteor los dos existen y se llaman entre sí — un Met puede disparar un flujo como una de sus herramientas.

## Los cinco pasos

### 1. Consigue una API key

Desde el panel, en Ajustes → Desarrolladores. Empieza con una de prueba (`met_test_`): ejecuta gratis, con tope diario, y los scopes que producen efectos reales quedan restringidos — no hay forma de mandarle un mensaje a un cliente de verdad por accidente.

```bash
npm install @meteor.ia/sdk
```

Detalle completo en [Autenticación](autenticacion.html).

### 2. Define qué hace el agente

El prompt es la definición del agente, no un adorno. Lo que decide la calidad no es la extensión sino la precisión sobre **qué no debe hacer** y **cuándo pasarle el turno a un humano**.

Un Met se crea desde el panel o por API, y ahí mismo se le asignan sus habilidades. Ver [Mets y sus herramientas](mets-y-herramientas.html).

### 3. Dale acceso a los datos del negocio

Un agente sin datos improvisa. En Meteor los datos viven en **colecciones** — tablas del workspace que el agente lee y escribe sin que programes un endpoint por cada una:

```ts
import Met from '@meteor.ia/sdk';
const met = new Met(process.env.MET_API_KEY!, { workspaceId: 7 });

const cols = await met.collections.list();
await met.items.create(cols[0].id, { data: { titulo: 'Consulta nueva' } });
```

Si los datos están en otro sistema, se conectan como [integraciones MCP](integraciones-mcp.html) y el agente las usa como herramientas.

### 4. Ejecútalo

```ts
const run = await met.runs.create({ input: 'Resume las consultas de hoy' });
console.log(run.output);
```

Con `stream: true` la respuesta llega token por token por SSE, que es lo que quieres en una interfaz de chat. Ver [Ejecutar Mets](ejecutar-agentes.html) y [Streaming](streaming.html).

### 5. Conéctalo a un canal

Un agente que solo responde por API no atiende a nadie. Conectando WhatsApp, Messenger o Instagram al workspace, el Met contesta en el hilo del contacto:

```ts
await met.contacts.sendMessage(42, 'Ya quedó agendada la visita');
```

Aquí hay un límite que conviene saber **antes** de escribir código: fuera de la ventana de 24 horas desde el último mensaje de la persona, WhatsApp solo permite escribir con **plantillas aprobadas por Meta**. No es un límite de Meteor y no se puede saltear. Ver [CRM y contactos](contactos.html).

## Lo que casi siempre se olvida

**Un agente necesita poder rendirse.** El caso que decide si la gente vuelve a escribirle no es el que resuelve bien, sino el que no puede resolver: si no hay una salida hacia un humano, la conversación muere ahí. En Meteor eso es el autopiloto — se pausa por minutos y se reanuda solo, en vez de apagarse hasta que alguien se acuerde. Ver [Operación del workspace](operacion-del-workspace.html).

**Las ejecuciones se cobran, así que hay que poder mirarlas.** `GET /billing/executions` da una fila por ejecución con su costo. Cuando el total no cuadra, la respuesta casi siempre es un agente que se llama a sí mismo en un bucle.

**Todo lo que un agente hizo queda auditable.** Cada ejecución tiene su traza, y el `request_id` de la respuesta HTTP la une con lo que ves en el panel. Ver [Eventos en vivo](eventos.html).

## Usar Meteor desde tu propio agente

Si ya tienes un agente —en Claude, en Cursor, o uno propio— no necesitas la API: Meteor expone un **servidor MCP remoto** con 22 herramientas `met_*`. Tu agente ejecuta Mets, consulta el CRM, dispara tareas y lee datos como herramientas nativas:

```
https://api.met.meteor.com.co/api/v1/mcp
```

El catálogo se filtra por los scopes de tu API key: una herramienta cuyo scope no tienes simplemente no aparece. Ver [Servidor MCP](../mcp.html).

## Preguntas frecuentes

### ¿Necesito entrenar un modelo?

No. Un agente se define con prompt, herramientas y datos; el modelo es un componente intercambiable. Entrenar tiene sentido cuando el problema es que el modelo no *sabe* algo del dominio, y casi siempre el problema real es que no *puede* hacer algo — y eso se arregla con una herramienta, no con entrenamiento.

### ¿Cuánto tarda tener uno funcionando?

Un Met contestando con acceso a una colección son unas horas. Lo que toma tiempo es lo otro: definir cuándo se rinde, qué no debe decir, y qué pasa cuando la herramienta que necesita está caída.

### ¿Puedo probar sin afectar datos reales?

Sí, con una key `met_test_`. Las ejecuciones quedan con `livemode: false` y no debitan Energía.

### ¿Qué lenguajes tienen SDK?

TypeScript (`@meteor.ia/sdk`) y Python (`meteor-ia`), los dos con paridad completa sobre las 300 operaciones públicas. También hay un CLI (`met`) y la API REST con su OpenAPI publicado.

### ¿Y si mi caso no es conversacional?

Buena parte de lo que la gente construye no es un chat: es un procedimiento que corre solo. Eso son [tareas](tareas.html) — se disparan por API, por horario o por un evento, y sus pasos pueden ejecutar Mets.