Skip to main content
La Public API es multi-tenant: cada petición debe incluir el Workspace ID y una API Key válida. Usa los ejemplos siguientes como plantilla y ajusta tus propios IDs.

​
Requisitos previos

  • Workspace habilitado y su identificador (WORKSPACE_ID).
  • API Key emitida por Agents Studio (X-API-Key).
  • URL base del entorno (prod: https://api-prod.studio.getsupervisor.ai/v1).
  • Node.js 18+ si usarás el SDK TypeScript.
Define estas variables de entorno para reutilizarlas en los ejemplos: 
export API_BASE_URL="https://api-prod.studio.getsupervisor.ai/v1"
export WORKSPACE_ID="00000000-1111-2222-3333-444455556666"
export API_KEY="sk_live_..."

​
Instala el SDK o prepara tu cliente HTTP

  • TypeScript SDK
  • cURL / HTTP
Instala el paquete oficial y añade tipos de Fetch si los necesitas (para Node.js < 18).
npm install @getsupervisor/agents-studio-sdk

// src/client.ts
import { createClient } from '@getsupervisor/agents-studio-sdk';

const client = createClient({
  baseUrl: process.env.API_BASE_URL!,
  workspaceId: process.env.WORKSPACE_ID!,
  apiKey: process.env.API_KEY!,
  // Opcional: configura reintentos o timeout personalizados
  retry: { maxRetries: 2, baseDelayMs: 300 },
});

export default client;

​
Lista tus agentes

  • TypeScript SDK
  • cURL
import client from './client';

const agents = await client.agents.list({ limit: 5 });

for (const item of agents.data) {
  console.log(`${item.agentId}: ${item.name} (${item.agentType})`);
}

if (agents.meta.hasNext) {
  const nextPage = await agents.next();
  console.log(`Siguiente página: ${nextPage.meta.page}`);
}

​
Crea un agente

  • TypeScript SDK
  • cURL
import client from './client';

const draft = await client.agents.create({
  name: 'Onboarding Bot',
  agentType: 'chat',
  description: 'Acompaña a nuevos usuarios en su primera semana.',
});

console.log('Draft creado:', draft.agentId, draft.status);

​
Conecta la tool voice.calls

Al crear una conexión de voz, la API rellena automáticamente descriptionUsage y usageExample con la guía estándar definida en voice-call-usage.template.ts.
  • TypeScript SDK
  • cURL
import client from './client';

const workspaceId = client.workspace.get() ?? process.env.WORKSPACE_ID!;
const agentId = '11111111-2222-3333-4444-555555555555';

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

console.log(connection.status); // connected

type ToolGuidanceMetadata = {
  usageGuidance?: {
    descriptionUsage?: string;
    usageExample?: string;
  };
};

const metadata = (connection.metadata ?? {}) as ToolGuidanceMetadata;
const guidance = metadata.usageGuidance;

console.log(guidance?.descriptionUsage);
console.log(guidance?.usageExample);

​
Ejecuta voice.calls.startCall

  • TypeScript SDK
  • cURL
import client from './client';

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

​
Manejo de errores e idempotencia

  • TypeScript SDK
  • cURL
import client from './client';
import {
  HttpError,
  TimeoutError,
  NetworkError,
} from '@getsupervisor/agents-studio-sdk';

try {
  await client.tools.execute(
    'voice.calls',
    {
      workspaceId: process.env.WORKSPACE_ID!,
      agentId: '11111111-2222-3333-4444-555555555555',
      action: 'startCall',
      args: { to: '+525500000000' },
    },
    { idempotencyKey: `voice-${Date.now()}` },
  );
} catch (err) {
  if (err instanceof HttpError) {
    console.error('HTTP error', err.status, err.body);
  } else if (err instanceof TimeoutError) {
    console.error('Timeout, reintenta más tarde');
  } else if (err instanceof NetworkError) {
    console.error('Error de red, reintento automático');
  } else {
    throw err;
  }
}

​
Recursos adicionales

  • La especificación completa está disponible en openapi/public-api.yaml.
  • Consulta la tabla de scopes en el SDK (apps/public-api/sdk/js/README.md) para validar los permisos necesarios por endpoint.
  • Para plantillas MCP vinculadas a voice.calls, revisa el archivo docs/mcp/tools_execution.md del repositorio.

Explora el OpenAPI

Lee el contrato completo y genera clientes o mocks desde la especificación oficial.