TypeScript SDK

Todo lo que necesitas para consumir la Public API desde Node.js o el navegador usando nuestro SDK oficial.

Instalación

npm install @getsupervisor/agents-studio-sdk

yarn add @getsupervisor/agents-studio-sdk

pnpm add @getsupervisor/agents-studio-sdk

Configura el cliente

Define tus variables de entorno (usa el nuevo dominio productivo).

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

El baseUrl va sin /v1: el SDK agrega el prefijo de versión a cada ruta.

Crea un helper client.ts para reutilizar en tu aplicación:

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

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

// Cambia de workspace en caliente: client.workspace.set('ws-otro');
// Usa API Keys si prefieres: client.auth.setApiKey('sk_prod_...');

Define apiKey en la configuración inicial o usa client.auth.setApiKey('sk_...') para rotarla en caliente. El SDK enviará el header X-API-Key automáticamente.

Operaciones frecuentes

Listar agentes

import { client } from "./client";

const agents = await client.agents.list({
  limit: 10,
  filter: { status: "active" },
});

agents.data.forEach((item) => {
  console.log(`${item.agentId}: ${item.name} (${item.agentType})`);
});

if (agents.meta.hasNext) {
  const nextPage = await agents.next();
  console.log(`Total acumulado: ${nextPage.meta.total}`);
}

Crear y actualizar agentes

import { client } from "./client";

const draft = await client.agents.create({
  name: "Onboarding Bot",
  agentType: "chat",
  description: "Acompaña a nuevos usuarios durante su primera semana.",
  status: "inactive",
  debounceDelayMs: 0,
});

await client.agents.update(draft.agentId, {
  status: "active",
  description: "Acompaña y escala a soporte cuando la duda no es de producto.",
});

PATCH /v1/agents/{agentId} sólo acepta name, status, description, avatarUrl, avatarUploadId y debounceDelayMs. La validación corre con forbidNonWhitelisted, así que cualquier otra propiedad —metadata, por ejemplo— devuelve 400 property … should not exist en vez de ignorarse.

Versiones, instrucciones y horarios

import { client } from "./client";

const agentId = "11111111-2222-3333-4444-555555555555";

const version = await client.agents.versions.create(agentId);
await client.agents.versions.createInstruction(agentId, version.id, {
  order: 0,
  content: "Saluda con empatía y confirma el objetivo de la conversación.",
});
await client.agents.versions.publish(agentId, version.id, {
  notes: "Versión inicial productiva",
});

const businessDay = { startTime: "09:00", endTime: "18:00" };

await client.agents.schedule.create(agentId, {
  isEnabled: true,
  timezone: "America/Mexico_City",
  outOfHoursBehavior: "offline",
  outOfHoursMessage: "Fuera de horario, te contactaremos en cuanto volvamos.",
  rules: [
    { dayOfWeek: "monday", isEnabled: true, slot: businessDay },
    { dayOfWeek: "tuesday", isEnabled: true, slot: businessDay },
    { dayOfWeek: "wednesday", isEnabled: true, slot: businessDay },
    { dayOfWeek: "thursday", isEnabled: true, slot: businessDay },
    { dayOfWeek: "friday", isEnabled: true, slot: businessDay },
    { dayOfWeek: "saturday", isEnabled: false, slot: null },
    { dayOfWeek: "sunday", isEnabled: false, slot: null },
  ],
});

Versiones y horarios cuelgan del namespace agents: son client.agents.versions y client.agents.schedule (con el alias client.agents.schedules). No existen client.agentVersions ni client.agentSchedule — llamarlos revienta con un TypeError antes de emitir la petición.

El horario no se manda con una clave por día. rules es un arreglo de exactamente siete elementos —uno por cada día de monday a sunday— con la forma { dayOfWeek, isEnabled, slot }, donde slot lleva startTime y endTime en formato HH:mm (o null los días cerrados). isEnabled, timezone, outOfHoursBehavior y rules son obligatorios.

Stages y triggers del blueprint

const stages = client.agents.stages(agentId);
const { data } = await client.agents.blueprints(agentId).list();
const blueprintId = data[0].blueprint.blueprintId;

const listing = await stages.list(blueprintId, { limit: 10 });
console.log(listing.meta.total);

const blueprintStages = stages(blueprintId);

const created = await blueprintStages.create({
  name: "proposal",
  title: "Propuesta",
  goalPrompt: "Explica la solución recomendada y ofrece agendar una demo.",
  order: 2,
});

await stages.triggers(blueprintId, created.id).create({
  condition: { type: "intent", value: "schedule_call" },
  nextStageName: "handoff",
});

await stages.reorder(blueprintId, {
  stageIds: listing.data.map((stage) => stage.id),
  startingStageName: "greeting",
});

Los helpers devuelven los métodos list, get, create, update, delete, reorder y triggers(stageId) (con list, get, create, update, delete para cada trigger).

Conectar la tool `voice.calls`

import { client } from './client';

const connection = await client.tools.connect('voice.calls', {
  agentId: '11111111-2222-3333-4444-555555555555',
  metadata: {
    reason: 'demo-outbound',
    expectedOutcome: 'confirmar cita',
  },
});

console.log(connection.status); // connected o pending
console.log(connection.descriptionUsage);
console.log(connection.usageExample);

Ejecutar `voice.calls.startCall`

import { client } from './client';

await client.tools.execute('voice.calls', {
  agentId: '11111111-2222-3333-4444-555555555555',
  action: 'startCall',
  args: {
    to: '+525500000000',
    metadata: { reason: 'confirmar cita', customerId: 'cust-789' },
  },
});

API Keys y autenticación

import { client } from './client';

const created = await client.apiKeys.create({
  name: 'Backend Integration',
  environment: 'production',
  scopes: ['agents:read', 'tools:execute'],
});

const revealed = await client.apiKeys.show(created.id);
console.log(revealed.key); // se muestra una sola vez

await client.apiKeys.revoke(created.id);

Webhooks y suscripciones

import { client } from "./client";

const webhook = await client.webhooks.create({
  url: "https://example.com/webhooks/voice",
  description: "Eventos de llamadas de voz",
});

await client.webhooks.createSubscription(webhook.id, {
  eventKey: "call.callEnded",
});

Tres detalles que hacen fallar la copia a ojo: el webhook no tiene name (se identifica por su url y su description, y un name de más devuelve 400); las suscripciones se crean con client.webhooks.createSubscription(...), no con un sub-objeto client.webhooks.subscriptions; y el campo del evento es eventKey, no eventType. El catálogo de eventKey disponibles está en Notificaciones.

Manejo de errores e idempotencia

import { client } from "./client";
import {
  HttpError,
  NetworkError,
  TimeoutError,
} from "@getsupervisor/agents-studio-sdk";

try {
  await client.tools.execute(
    "voice.calls",
    {
      agentId: "11111111-2222-3333-4444-555555555555",
      action: "startCall",
      args: { to: "+525500000000" },
    },
    { idempotencyKey: `voice-${Date.now()}` },
  );
} catch (error) {
  if (error instanceof HttpError) {
    console.error("HTTP error", error.status, error.body);
  } else if (error instanceof TimeoutError) {
    console.error("Timeout: reintenta o amplía el timeout");
  } else if (error instanceof NetworkError) {
    console.error("Problema de red, el SDK reintentará según tu política");
  } else {
    throw error;
  }
}

Ejemplo completo: CRUD de agentes

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!,
  });

  // Crear un agente temporal
  const agent = await client.agents.create({
    name: "Demo Onboarding",
    agentType: "chat",
    description: "Integra nuevos usuarios durante su primera semana.",
    status: "inactive",
    debounceDelayMs: 0,
  });

  // Activar el agente y ajustar su descripción
  await client.agents.update(agent.agentId, {
    status: "active",
    description: "Integra nuevos usuarios de la campaña de onboarding.",
  });

  // Obtener listado paginado
  const list = await client.agents.list({ limit: 5 });
  list.data.forEach((item) => console.log(item.agentId, item.name));

  if (list.meta.hasNext) {
    const next = await list.next();
    console.log("Página 2:", next.data.length);
  }

  // Eliminar cuando termine la prueba
  await client.agents.delete(agent.agentId);
}

main().catch((error) => {
  console.error(error);
  process.exit(1);
});

Ejemplo completo: agente de voz productivo

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

async function bootstrapVoiceAgent() {
  const client = createClient({
    baseUrl:
      process.env.API_BASE_URL ?? "https://api-prod.studio.getsupervisor.ai",
    workspaceId: process.env.WORKSPACE_ID!,
    apiKey: process.env.API_KEY!,
    retry: { maxRetries: 2 },
  });

  const voiceTool = await client.tools
    .list({ agentType: "voice", limit: 10 })
    .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.");
  }

  const agent = await client.agents.create({
    name: `Voice demo ${new Date().toISOString()}`,
    agentType: "voice",
    description: "Demo de voz para validar el journey completo.",
    status: "inactive",
    debounceDelayMs: 0,
  });

  const version = await client.agents.versions.create(agent.agentId);

  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 pickActive = (page: typeof language) =>
    page.data.find((item) => item.isActive)?.id;

  await client.agents
    .blueprints(agent.agentId)
    .version(version.id)
    .create({
      languageId: pickActive(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: pickActive(messageStyle)!,
      personalityToneStyleId: pickActive(toneStyle)!,
      criticalRules: ["Nunca compartas información sensible."],
      topicsForbidden: ["Negociaciones legales", "Recomendaciones médicas"],
    });

  await client.agents.versions.createInstruction(agent.agentId, version.id, {
    order: 0,
    content:
      "Saluda con empatía, confirma el motivo de la llamada y ofrece opciones breves antes de escalar.",
  });

  await client.tools.connect(voiceTool.identifier, {
    agentId: agent.agentId,
    metadata: { escenario: "demo-voice" },
    auth: { type: "none" },
  });

  await client.agents.versions.publish(agent.agentId, version.id, {
    notes: "Primera versión con tool voice.calls configurada automáticamente.",
  });
}

bootstrapVoiceAgent().catch((error) => {
  console.error(error);
  process.exit(1);
});

Scopes disponibles

La tabla de scopes vive en un solo sitio: la guía de API Keys. Ahí está el listado que los guards verifican hoy —incluidos knowledge-bases:read y knowledge-bases:write, que necesita client.knowledgeBases, y los dos de uploads— junto con las combinaciones que exige el carril de subida de archivos.

Los scopes no admiten comodines: el guard compara cadenas exactas, así que agents:* no existe y no otorga nada. Enumera cada scope que necesites.

Consulta el archivo OpenAPI local (openapi/public-api.yaml) para validar qué scope exige cada endpoint.

Recursos adicionales

Revisa la guía MCP en ./mcp para combinar tools con agentes desde el Protocolo de Contexto de Modelo.
Usa la referencia OpenAPI (/openapi/public-api.yaml) para navegar los modelos y respuestas HTTP.
En la carpeta snippets/ de esta documentación encontrarás fragmentos reutilizables listos para copiar en tus integraciones.

Empezar

Referencia de endpoints

Agentes

Herramientas del agente

Telefonía

Webhooks

MCP

Instalación

Configura el cliente

Operaciones frecuentes

Listar agentes

Crear y actualizar agentes

Versiones, instrucciones y horarios

Stages y triggers del blueprint

Conectar la tool `voice.calls`

Ejecutar `voice.calls.startCall`

API Keys y autenticación

Webhooks y suscripciones

Manejo de errores e idempotencia

Ejemplo completo: CRUD de agentes

Ejemplo completo: agente de voz productivo

Scopes disponibles

Recursos adicionales

​Instalación

​Configura el cliente

​Operaciones frecuentes

​Listar agentes

​Crear y actualizar agentes

​Versiones, instrucciones y horarios

​Stages y triggers del blueprint

​Conectar la tool voice.calls

​Ejecutar voice.calls.startCall

​API Keys y autenticación

​Webhooks y suscripciones

​Manejo de errores e idempotencia

​Ejemplo completo: CRUD de agentes

​Ejemplo completo: agente de voz productivo

​Scopes disponibles

​Recursos adicionales

Instalación

Configura el cliente

Operaciones frecuentes

Listar agentes

Crear y actualizar agentes

Versiones, instrucciones y horarios

Stages y triggers del blueprint

Conectar la tool `voice.calls`

Ejecutar `voice.calls.startCall`

API Keys y autenticación

Webhooks y suscripciones

Manejo de errores e idempotencia

Ejemplo completo: CRUD de agentes

Ejemplo completo: agente de voz productivo

Scopes disponibles

Recursos adicionales