---
title: "Use the TypeScript SDK"
description: "Call the Agents API from TypeScript or JavaScript with @qomni/sdk: one method per operation, types from the contract and errors with a code."
version: "en"
---

> 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 the TypeScript SDK

`@qomni/sdk` wraps every operation of the [reference](/agents-api/) in a
method with the contract's types: `qomni.agents.createCall`,
`qomni.agents.listCalls`, `qomni.agents.createRealtimeSession` and the rest.
It is generated from the contract, so a method always asks for what the
operation asks for.

## Before you begin

- Bun, or Node.js 22.18 or later (both run TypeScript without compiling).
- An Agents test key (`sk_agents_test_…`) in the `QOMNI_KEY` variable,
  as in the [quickstart](/get-started/quickstart/).
- The package is not on npm yet: install it from the
  `sdks/typescript/` folder of the Qomni repository.

1. ### Install the package

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

2. ### Create the client and make a call

   The key decides the product and the mode: an Agents key works in
   `qomni.agents`. Save the code as `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. ### Run it

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

   Node.js 22.18 or later runs the same file as is:

   ```shell
   node call.mts
   ```

## You should see

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

The SDK sent `POST https://api.qomni.ai/agents/v1/calls` with your key in
`Authorization`, the body as JSON and `Idempotency-Key: order-1001`. In test
mode no phone rang: `+15005550001` is a magic number that
ends `completed`. If the key is not valid, the API responds `401` and the SDK
throws a `QomniError` with the error's `code`, for example
`api_key_malformed`.

## Next steps

- Each method is named after its operation in the [Agents reference](/agents-api/):
  path parameters, then the body, then the query, then the options
  (`idempotencyKey`, `signal`, `headers`). The TypeScript example of each
  operation already uses the SDK.
- [Talk to an agent in real time](/agents/realtime/): `createRealtimeSession` opens the conversation.
- [Errors](/concepts/errors/): the codes a `QomniError` can carry.
- [Idempotency](/concepts/idempotency/): when to send `idempotencyKey`.

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