Começar com o SDK TypeScript

Instale o SDK TypeScript da System One, conecte a API hospedada, escolha um modelo e leia uma decisão tipada. Este guia conecta uma aplicação TypeScript no servidor à API de decisão hospedada da System One: você instala o SDK, configura uma chave de plataforma e um modelo do catálogo e avalia uma mensagem de suporte como escolha de equipe, nota de urgência e probabilidade de cobrança duplicada. A API devolve decisões; ela não roteia um ticket, não emite reembolso e não executa ferramentas.

Perguntas frequentes

Q: Como começo com o SDK TypeScript da 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: Novas contas recebem 100 créditos no cadastro; os créditos não expiram.

Como começo com o SDK TypeScript da System One?

Instale o SDK TypeScript da System One, defina sua chave de API, escolha um modelo como Clef Flash ou Jev e chame Choice, Score ou Noul para obter uma decisão tipada da API hospedada da System One.

Como funcionam os créditos?

Novas contas recebem 100 créditos no cadastro; créditos não expiram.

Instalação

O SDK suporta Node.js 20+. O comando abaixo usa os pacotes publicados para o serviço hospedado: core 0.8.0, adapter-system-one 0.7.0 e transport-fetch 0.8.0.

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

Crie um arquivo .env local, excluído do controle de versão:

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

A API usa a origem do site principal, não o host de documentação. A chave de API é a sua credencial de plataforma da System One. Uma chave de idempotência é outra coisa: crie um UUID aleatório novo para cada nova avaliação lógica, não uma configuração de ambiente compartilhada. Manter a mesma chave e a requisição completa ao repetir essa operação.

Substitua YOUR_MODEL_ID pelo valor exato de name da entrada escolhida do catálogo. O systemOneAdapter usa https://system-one.dev/v1 como URL base e envia as decisões para /v1/systemone; https://docs.system-one.dev serve documentação, não requisições de API.

Primeira decisão

Salve como decision.mts. O exemplo envia uma mensagem de suporte compartilhada como state e três perguntas nomeadas.

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

Cada execução deste script inicia uma nova operação cobrável, mesmo que a entrada não mude. A operação existe apenas em memória; executar o script de novo não é recuperação após um timeout ou uma falha. Verifique o saldo da conta antes de enviar a primeira decisão.

Entendendo o resultado

• team.choice é um dos nomes de opção declarados, com o tipo literal preservado.
• urgency.score pode ser fracionário entre 0 e 2 para esta rubrica de três níveis.
• duplicate.probability é P(true) de 0 a 1, não um booleano JavaScript.
• Estatísticas opcionais e contagens de tokens permanecem desconhecidas quando ausentes. Não as substitua por zero.

No fio, booleanQuestion() vira type: 'noul', com um campo de resposta chamado noul; o core expõe type: 'boolean' e probability. Esse resultado tipado não é o corpo HTTP exato e não expõe todos os cabeçalhos de resposta. Use o adaptador HTTP explícito e o transporte Fetch ao conectar a esta API hospedada.

O primeiro exemplo imprime metadados do SDK, não um recibo de cobrança. Se sua integração precisar do ID de contabilização da plataforma, dos créditos cobrados ou do status de replay, leia os cabeçalhos X-Request-Id, X-System-One-Credits e X-Idempotency-Replayed da resposta.

Modelos

Não fixe um modelo por conta própria. Copie o valor exato de name da seleção atual ou omita model para que a API hospedada use o padrão do serviço. Os IDs de modelo são opacos, os aliases podem mudar e o catálogo não é um conjunto fixo. Consulte Escolher um modelo e o diretório de modelos para comparar opções.

O cliente oficial independente @typesafe-ai/sdk@0.6.0 também é suportado. A URL base dele é a raiz da API sem /v1, porque ele acrescenta /v1/systemone por conta própria.

Créditos

Novas contas recebem 100 créditos no cadastro; créditos não expiram. Criar mais chaves não cria mais créditos de boas-vindas. O custo depende do tamanho da requisição, do número de perguntas e do preço atual do modelo escolhido. Rejeições de autenticação e de validação acontecem antes de qualquer cobrança; chamadas com falha devolvem os créditos reservados. Veja Faturamento e créditos para a fórmula de consumo.

Próximos passos

• Documentação do SDK e primitivos de decisão.
• Referência da API e escolha de modelo.
• Integração de agente, versionamento e chave de idempotência.