Empezar con el SDK TypeScript

Esta guía conecta una aplicación TypeScript de servidor con la API de decisiones alojada de System One. Instalarás el SDK, configurarás una clave de plataforma y un modelo del catálogo, y evaluarás un mensaje de soporte como una elección de equipo, una puntuación de urgencia y una probabilidad de cargo duplicado. La API devuelve decisiones: no enruta un ticket, no emite un reembolso y no ejecuta herramientas.

Preguntas frecuentes

Q: ¿Cómo empiezo con el SDK TypeScript de System One?
A: Install the System One TypeScript SDK, set your API key, choose a model such as Clef Flash or Jev, and call Choice, Score, or Noul for a typed decision from the hosted System One API.

Q: Credits?
A: Las cuentas nuevas reciben 100 créditos al registrarse; los créditos no caducan.

Preguntas frecuentes

¿Cómo empiezo con el SDK TypeScript de System One? Instala el SDK TypeScript de System One, define tu clave de API, elige un modelo como Clef Flash o Jev, y llama a Choice, Score o Noul para obtener una decisión tipada desde la API alojada de System One.

¿Créditos? Las cuentas nuevas reciben 100 créditos al registrarse; los créditos nunca caducan.

Instalación

El SDK admite Node.js 20 o superior. Los comandos de esta guía usan Node.js 22.18+, que puede ejecutar directamente estos archivos TypeScript .mts.

npm install @system-one-ai/core@0.8.0 @system-one-ai/adapter-system-one@0.7.0 @system-one-ai/transport-fetch@0.8.0

Este quickstart usa el trío alojado actual: core 0.8.0, adapter-system-one 0.7.0 y transport-fetch 0.8.0. Los paquetes se publican de forma independiente y todos resuelven core@^0.8.0. No existe un comando de inicialización aparte: construyes el cliente con createSystemOne({ apiKey, baseURL, model, adapter: systemOneAdapter, transport: createFetchTransport(), timeoutMs: 30_000, maxRetries: 0 }).

Crea un archivo .env local excluido del control de versiones:

SYSTEM_ONE_API_KEY=replace-with-your-platform-key
SYSTEM_ONE_BASE_URL=https://system-one.dev/v1
SYSTEM_ONE_MODEL=YOUR_MODEL_ID

Sustituye YOUR_MODEL_ID en .env por el name exacto de la entrada del catálogo que hayas elegido antes de continuar. La clave de API es tu credencial de plataforma de System One; no la guardes en prompts, en código de navegador ni en logs. Una operation key es distinta: genera un UUID nuevo para cada evaluación lógica nueva, no un valor compartido por entorno. Reintentar esa operación conserva la misma clave y la misma petición completa.

La API usa el origen del sitio principal, no el host de documentación: https://system-one.dev/v1 es la URL base del adaptador de System One y las decisiones se envían a /v1/systemone.

Tu primera Choice

El ejemplo usa un único mensaje de soporte como state y tres preguntas con nombre. choice() declara los equipos permitidos, score() declara una rúbrica de urgencia ordenada y booleanQuestion() pide una probabilidad en lugar de una acción de verdadero o falso. Para el diseño de esas preguntas, consulta primitivas de decisión Choice, Score y Noul.

Guárdalo como decision.mts:

import { createSystemOne, choice, score, booleanQuestion } from '@system-one-ai/core';
import { systemOneAdapter } from '@system-one-ai/adapter-system-one';
import { createFetchTransport } from '@system-one-ai/transport-fetch';

const apiKey = process.env.SYSTEM_ONE_API_KEY;
const baseURL = process.env.SYSTEM_ONE_BASE_URL;
const model = process.env.SYSTEM_ONE_MODEL;
if (!apiKey || !baseURL || !model || model === 'YOUR_MODEL_ID') {
  throw new Error('Set the API key, base URL, and catalog model.');
}

const client = createSystemOne({
  apiKey,
  baseURL,
  model,
  adapter: systemOneAdapter,
  transport: createFetchTransport(),
  timeoutMs: 30_000,
  maxRetries: 0,
});

const operation = {
  idempotencyKey: crypto.randomUUID(),
  request: {
    model,
    state: { message: 'I was charged twice for the same order.' },
    questions: {
      team: choice('Choose the team that should review this request.', {
        billing: 'Payments, invoices, and refunds',
        support: 'Technical troubleshooting',
        review: 'More context is needed',
      }),
      urgency: score('Rate urgency using this ordered rubric.', [
        'Can wait for normal review',
        'Needs a timely response',
        'Needs immediate human attention',
      ]),
      duplicate: booleanQuestion('Does the message report a duplicate charge?', {
        true: 'The same order was charged more than once',
        false: 'No duplicate charge is reported',
      }),
    },
  },
};

const result = await client.evaluate(operation.request, {
  headers: { 'Idempotency-Key': operation.idempotencyKey },
});

console.log({
  team: result.answers.team.choice,
  distribution: result.answers.team.probabilities,
  urgency: result.answers.urgency.score,
  duplicateProbability: result.answers.duplicate.probability,
  inputTokens: result.usage.inputTokens,
  model: result.model,
  requestId: result.response.requestId,
});

node --env-file=.env decision.mts

result.answers.team.choice es uno de los nombres de opción declarados, con su tipo literal conservado; result.answers.team.probabilities es el objeto de distribución. result.answers.urgency.score puede ser fraccionario entre 0 y 2 para esta rúbrica de tres niveles. result.answers.duplicate.probability es P(true) entre 0 y 1, no un booleano de JavaScript. result.model identifica el modelo devuelto y result.response.requestId sirve para diagnóstico. Las estadísticas y el recuento de tokens (result.usage.inputTokens) siguen siendo desconocidos cuando no están presentes: no los reemplaces por cero. Una respuesta bien tipada no prueba que el juicio sea correcto; tu aplicación decide si enruta el ticket o exige revisión humana.

Cada ejecución de este script inicia una nueva operación facturable, incluso si la entrada no cambia. La operación solo existe en memoria, así que volver a ejecutar el script no es una recuperación tras un timeout o un fallo.

Modelos

Elige el modelo con el directorio actual o con el selector del Playground. Consulta Model information junto al selector para revisar la tarifa y los límites del modelo seleccionado, y copia su name exacto: YOUR_MODEL_ID es un marcador de posición, no un alias admitido. También puedes obtener el directorio con GET /v1/models público. Comprueba que el modelo admite Choice, Score y Noul antes de enviar una decisión. Si omites model, la API alojada usa su modelo de despliegue por defecto.

Créditos

Las cuentas nuevas reciben 100 créditos gratuitos al registrarse, y esos créditos nunca caducan. Las llamadas a la API de decisiones alojada consumen los créditos de tu cuenta de System One al precio vigente del modelo seleccionado. Instalar el SDK no crea una cuenta alojada ni compra inferencia: es una configuración de desarrollo. Cada ejecución del ejemplo inicia una operación facturable, así que revisa el saldo de tu consola y la estimación antes de enviar decisiones.

Siguientes pasos

• Guía del SDK y migración desde el paquete anterior.
• Primitivas de decisión, referencia de la API y selección de modelo.
• Integración con agentes, versionado y tratamiento de datos.