Nuvem Agents

Nuvem Agents es la capa de runtime para agentes de IA. Cada agente tiene conversaciones persistentes, memoria a largo plazo, y puede ser disparado por eventos, crons o webhooks.

Crear un agente

POST /v1/agents
Authorization: Bearer <api_key>
{
  "name": "soporte-latam",
  "description": "Agente de soporte en español/portugués",
  "systemPrompt": "Sos un agente de soporte amigable para usuarios de LATAM...",
  "provider": "anthropic",
  "model": "claude-sonnet-4-5",
  "tools": ["search", "database"],
  "maxTokens": 2000
}

Conversaciones

# Iniciar conversación
POST /v1/agents/:agentId/conversations
{ "metadata": { "userId": "usr_abc" } }

# Enviar mensaje
POST /v1/agents/:agentId/conversations/:conversationId/messages
{ "content": "¿Cuánto tarda el envío a Buenos Aires?" }

# Listar conversaciones
GET /v1/agents/:agentId/conversations

Runs (ejecución autónoma)

# Iniciar run autónomo
POST /v1/agents/:agentId/runs
{
  "input": "Analizar ventas de la última semana y generar reporte",
  "maxSteps": 10
}

# Estado del run
GET /v1/agents/:agentId/runs/:runId

# Listar runs
GET /v1/agents/:agentId/runs

Triggers

# Trigger por evento de DB
POST /v1/agents/:agentId/triggers
{
  "type": "db_event",
  "table": "orders",
  "event": "INSERT",
  "prompt": "Nuevo pedido recibido: {{record.id}}. Notificar al equipo."
}

# Trigger por cron
POST /v1/agents/:agentId/triggers
{
  "type": "cron",
  "schedule": "0 8 * * 1-5",
  "prompt": "Generá el resumen diario de operaciones"
}

# Trigger por webhook
POST /v1/agents/:agentId/triggers
{
  "type": "webhook",
  "name": "github-pr",
  "prompt": "Nuevo PR: {{payload.title}}. Revisá el código y dejá comentarios."
}

Templates LATAM

Nuvem incluye templates preconfigurados para casos de uso comunes en LATAM:

Template	Descripción
soporte-es	Agente de soporte en español
soporte-pt	Agente de soporte em português
ventas-latam	Agente de ventas con contexto regional
analista-datos	Analista de datos con acceso a DB
moderador-contenido	Moderación de contenido en ES/PT

# Crear desde template
POST /v1/agents/templates/:templateId/deploy
{ "name": "mi-agente-soporte" }

SDK

JavaScript

import { createClient } from '@nuvem/js';

const nuvem = createClient({ apiKey: process.env.NUVEM_API_KEY! });

// Chat con agente
const conv = await nuvem.agents.createConversation('soporte-latam');
const response = await conv.sendMessage('¿Cuál es mi saldo?');
console.log(response.content);

// Run autónomo
const run = await nuvem.agents.run('analista-datos', {
  input: 'Resumir ventas de esta semana',
});
await run.waitForCompletion();
console.log(run.result);

Métricas

GET /v1/agents/metrics?period=7d

Retorna: total conversations, total runs, avg response time, tokens consumed, cost breakdown por proveedor.

Errores comunes

Código	Mensaje	Causa
agent_not_found	Agente inexistente	ID inválido
conversation_not_found	Conversación inexistente	ID inválido
run_failed	El run falló	Error en ejecución autónoma
max_steps_reached	Límite de pasos alcanzado	Aumentar maxSteps