---
title: "Use o SDK de TypeScript"
description: "Chame a API do Agents a partir de TypeScript ou JavaScript com @qomni/sdk: um método por operação, tipos do contrato e erros com código."
version: "pt-br"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.qomni.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Use o SDK de TypeScript

`@qomni/sdk` envolve cada operação da [referência](/pt-br/agents-api/) em um
método com os tipos do contrato: `qomni.agents.createCall`,
`qomni.agents.listCalls`, `qomni.agents.createRealtimeSession` e o restante.
É gerado a partir do contrato, então um método sempre pede o que a
operação pede.

## Antes de começar

- Bun, ou Node.js 22.18 ou superior (os dois executam TypeScript sem compilar).
- Uma chave de teste do Agents (`sk_agents_test_…`) na variável `QOMNI_KEY`,
  como no [início rápido](/pt-br/get-started/quickstart/).
- O pacote ainda não está no npm: instale-o a partir da pasta
  `sdks/typescript/` do repositório do Qomni.

1. ### Instale o pacote

   ```shell
   pnpm add ../qomni/sdks/typescript
   ```

2. ### Crie o cliente e faça uma chamada

   A chave decide o produto e o modo: uma chave do Agents serve em
   `qomni.agents`. Salve o código em `call.mts`.

   ```ts title="call.mts"
   import { Qomni, QomniError } from "@qomni/sdk";

   const qomni = new Qomni({ apiKey: process.env.QOMNI_KEY! });

   try {
     const call = await qomni.agents.createCall(
       { to: "+15005550001" },
       { idempotencyKey: "order-1001" },
     );
     console.log(call.id, call.status);
   } catch (error) {
     if (error instanceof QomniError) {
       console.error(error.status, error.code, error.message);
     } else {
       throw error;
     }
   }
   ```

3. ### Execute

   ```shell
   bun run call.mts
   ```

   Node.js 22.18 ou superior executa o mesmo arquivo sem alterações:

   ```shell
   node call.mts
   ```

## Você deve ver

```text title="Salida"
call_01hv4k8s2m9q7w3e5r6t8y0u1i completed
```

O SDK enviou `POST https://api.qomni.ai/agents/v1/calls` com sua chave em
`Authorization`, o corpo em JSON e `Idempotency-Key: order-1001`. Em modo
de teste nenhum telefone tocou: `+15005550001` é um número mágico que
termina `completed`. Se a chave não for válida, a API responde `401` e o SDK
lança um `QomniError` com o `code` do erro, por exemplo
`api_key_malformed`.

## Próximos passos

- Cada método tem o nome da sua operação na [referência do Agents](/pt-br/agents-api/):
  parâmetros de caminho, depois o corpo, depois a query, depois as opções
  (`idempotencyKey`, `signal`, `headers`). O exemplo em TypeScript de cada
  operação já usa o SDK.
- [Fale com um agente em tempo real](/pt-br/agents/realtime/): `createRealtimeSession` abre a conversa.
- [Erros](/pt-br/concepts/errors/): os códigos que um `QomniError` pode trazer.
- [Idempotência](/pt-br/concepts/idempotency/): quando enviar `idempotencyKey`.

Source: https://docs.qomni.ai/pt-br/get-started/sdks/index.mdx
