Skip to main content

​
Get Started: tu primer agente de voz

Esta guía te lleva desde “cero” hasta tener tu primer agente de voz publicado, con una llamada de prueba y trazabilidad usando Logs y Calls.

​
Requisitos previos

  • Una cuenta activa en Agents Studio.
  • Acceso a un Workspace (Sandbox o Production).
  • Un número telefónico para pruebas (si tu workspace habilita llamadas).
Recomendación: empieza en Sandbox para iterar rápido y publicar cuando estés conforme.

​
Paso 1 — Entra al Workspace

  1. Abre https://agents.studio.getsupervisor.ai
  2. Inicia sesión y selecciona tu Workspace.

​
Paso 2 — Crea un agente de voz

  1. Ve a Agentes (/agents).
  2. Haz clic en Nuevo agente.
  3. Selecciona el tipo Voice (agente de voz).
  4. Completa:
    • Nombre (ej. “Ana · Ventas”).
    • Descripción (qué hace y para quién).
Si usas una plantilla (Marketplace), puedes acelerar la configuración inicial.

​
Paso 3 — Define la personalidad (blueprint)

En la pestaña de configuración del agente (Personalidad/Blueprint):
  • Rol: quién es el agente.
  • Objetivo: qué resultado de negocio debe lograr.
  • Saludo: la primera frase al iniciar.
  • Estilo y tono: cómo debe sonar (profesional, cálido, etc.).
  • Datos requeridos: qué información debe recolectar.
  • Reglas críticas / guardrails: lo que nunca debe hacer.
Si tu equipo usa un flujo (Workflow/Stages), asegúrate de que el blueprint y el flujo no se contradigan.

​
Paso 4 — Selecciona una voz

  1. En el selector de voz, busca una voz alineada a tu marca.
  2. Filtra por idioma/locale y género si lo necesitas.
  3. Reproduce un preview (si está disponible) antes de elegir.
Técnicamente, la voz se guarda en el blueprint como voiceId (un ítem del catálogo). El cambio se vuelve efectivo al publicar.

​
Paso 5 — Agrega instrucciones (el “cerebro” operable)

Ve a la pestaña Instrucciones y agrega directrices claras de negocio. Ejemplos:
  • “Si el cliente pregunta por precios, no des cifras exactas; ofrece enviar una cotización por correo.”
  • “Valida nombre y motivo de la llamada antes de proponer una solución.”
  • “Si el cliente está molesto, reconoce el problema y ofrece escalar a humano.”
Usa instrucciones cortas y accionables. Prioriza con order para que lo más importante quede arriba.

​
Paso 6 — Conecta herramientas (si aplica)

Dependiendo de tu caso de uso, puedes habilitar herramientas desde el agente o desde el Marketplace (/dashboard/marketplace):
  • Telefonía/llamadas
  • Integraciones (CRM, calendario, etc.)
Para referencia técnica de tools, consulta:

​
Paso 7 — Publica la versión

  1. En la parte superior del editor, haz clic en Publish.
  2. (Opcional) Agrega Notas de versión para documentar el cambio.
  3. Confirma.
Publicar promueve una versión draft a active (archivando la versión activa previa). En algunos flujos puedes re-publicar una versión active para forzar sincronización.

​
(Opcional) El mismo journey pero por API (TypeScript SDK)

Si tu equipo quiere automatizar el despliegue (por ejemplo desde un backend, CI o un script), puedes replicar el mismo flujo del UI usando el SDK oficial de TypeScript. Este ejemplo hace exactamente lo mismo que los pasos anteriores:
  1. Crea un agente (Voice)
  2. Crea una versión
  3. Crea el blueprint (personalidad)
  4. Conecta la tool voice.calls
  5. Publica la versión
Usa un Workspace de Sandbox para validar el flujo y luego cambia API_BASE_URL, WORKSPACE_ID y API_KEY a tu entorno productivo.

​
Variables de entorno

export API_BASE_URL="https://api-prod.studio.getsupervisor.ai/v1"
export WORKSPACE_ID="00000000-1111-2222-3333-444455556666"
export API_KEY="sk_live_..."

​
Script: crear y publicar tu primer agente de voz

import { createClient } from '@getsupervisor/agents-studio-sdk';

async function main() {
  const client = createClient({
    baseUrl: process.env.API_BASE_URL!,
    workspaceId: process.env.WORKSPACE_ID!,
    apiKey: process.env.API_KEY!,
    retry: { maxRetries: 2 },
  });

  // 1) Crea el agente
  const agent = await client.agents.create({
    name: `Mi primer agente de voz (${new Date().toISOString()})`,
    agentType: 'voice',
    status: 'inactive',
    description: 'Agente de voz inicial (Get Started).',
  });

  // 2) Crea una versión (draft)
  const version = await client.agentVersions.create(agent.agentId);

  // 3) Crea el blueprint (personalidad)
  // Tip: si no sabes qué IDs usar, toma ítems activos del catálogo.
  const [language, messageStyle, toneStyle] = await Promise.all([
    client.catalogs.list({ limit: 10, filter: { type: 'language' } }),
    client.catalogs.list({ limit: 10, filter: { type: 'message_style' } }),
    client.catalogs.list({ limit: 10, filter: { type: 'tone_style' } }),
  ]);

  const pickActiveId = (page: typeof language) =>
    page.data.find((item) => item.isActive)?.id;

  await client.agents
    .blueprints(agent.agentId)
    .version(version.id)
    .create({
      languageId: pickActiveId(language)!,
      personalityName: 'Ava',
      personalityRole: 'Voice concierge',
      targetAudience: 'Clientes con dudas rápidas',
      mainGoal: 'Resolver preguntas comunes y escalar cuando sea necesario',
      personalityInitialGreeting:
        'Hola, soy Ava del equipo de soporte. ¿En qué puedo ayudarte?',
      personalityMessageStyleId: pickActiveId(messageStyle)!,
      personalityToneStyleId: pickActiveId(toneStyle)!,
      criticalRules: ['Nunca compartas información sensible.'],
      outputVariables: [
        {
          type: 'string',
          name: 'call_summary',
          description: 'Resumen breve de la llamada.',
          required: true,
        },
        {
          type: 'enum',
          name: 'call_outcome',
          description: 'Resultado principal de la llamada.',
          choices: ['resolved', 'escalated', 'follow_up'],
          required: true,
        },
      ],
    });

  // 4) Conecta tools (al menos voice.calls)
  const voiceTool = await client.tools
    .list({ agentType: 'voice', limit: 20 })
    .then((page) =>
      page.data.find((tool) => tool.identifier === 'voice.calls'),
    );

  if (!voiceTool) {
    throw new Error('La tool voice.calls no está disponible en tu workspace.');
  }

  await client.tools.connect(voiceTool.identifier, {
    workspaceId: client.workspace.get()!,
    agentId: agent.agentId,
    metadata: { reason: 'get-started' },
    auth: { type: 'none' },
  });

  // 5) Publish (convierte la versión en activa y sincroniza tools/proveedor)
  await client.agentVersions.publish(agent.agentId, version.id, {
    notes: 'Primera versión publicada desde el SDK (Get Started).',
  });

  console.log('Agente publicado:', {
    agentId: agent.agentId,
    versionId: version.id,
  });
}

main().catch((error) => {
  console.error(error);
  process.exit(1);
});
Para una referencia más completa (incluyendo buenas prácticas de retries, errores e idempotencia), consulta:

​
Paso 8 — Prueba una llamada

  • Si el UI ofrece un botón tipo Test Call, úsalo para llamar a un número de prueba.
  • Alternativamente, tu equipo puede usar endpoints de telefonía (para integraciones):

​
Paso 9 — Verifica resultados en Logs y Calls

​
Logs (/dashboard/logs)

  • Úsalos para depurar errores, ver eventos en vivo y correlacionar ejecuciones.
  • Si ejecutaste tools, ubica el toolExecutionId para rastrear la operación.

​
Calls (/dashboard/calls)

  • Revisa el historial de llamadas.
  • Filtra por agente y fechas.
  • Abre el detalle para ver transcripción, metadatos y (si aplica) grabación.
Para el contrato API de consultas (solo lectura):

​
Siguiente paso

Manual de usuario

Secciones del sitio: agentes, campañas, llamadas, marketplace, logs, versiones y más.

SDK

Automatiza: crea agentes, publica versiones, lista voces y consume llamadas.