---
title: "Início rápido"
description: "Verifique sua chave do Agents e faça um agente ligar para um número em cinco minutos, pelo terminal, Python ou TypeScript."
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.

# Início rápido

Ao terminar este guia, você terá verificado sua chave e criado uma chamada com a
API do Agents. Tudo roda em **modo de teste**: nenhum número é discado e
nada é cobrado.

## Antes de começar

Você precisa de:

- Uma conta Qomni (teste grátis de 14 dias, sem cartão).
- Um terminal com `curl`, ou Python 3.9 ou superior, ou Node.js 18 ou superior.

1. ### Crie uma chave de teste

   Cadastre-se em [qomni.ai](https://qomni.ai). Em **Settings → API keys** do
   seu workspace, crie uma chave de teste: ela começa por `sk_agents_test_`.
   Guarde-a em uma variável de ambiente do seu shell:

   ```bash
   export QOMNI_KEY="sk_agents_test_…"
   ```

   Os exemplos desta página a leem de `QOMNI_KEY`. Não a escreva no seu
   código nem a envie para um repositório.

2. ### Instale o necessário

   Com cURL você não precisa de mais nada. Em Python usamos `requests`; o Node.js
   já traz `fetch`, e `tsx` executa TypeScript sem compilar.

   ```bash
   pip install requests
   ```

   ```bash
   npm install --save-dev tsx
   ```

3. ### Verifique a chave

   Peça à API o contexto da sua chave. Salve o código em `ping.py` ou
   `ping.mts`, ou cole o comando cURL no seu terminal:

   ```bash
   curl https://api.qomni.ai/agents/v1/ping \
     -H "Authorization: Bearer $QOMNI_KEY"
   ```

   ```python
   import os

   import requests

   key = os.environ["QOMNI_KEY"]
   response = requests.get(
       "https://api.qomni.ai/agents/v1/ping",
       headers={"Authorization": f"Bearer {key}"},
       timeout=10,
   )
   if not response.ok:
       error = response.json()["error"]
       raise SystemExit(f"{error['code']}: {error['message']}")
   print(response.json())
   ```

   ```typescript
   const response = await fetch("https://api.qomni.ai/agents/v1/ping", {
     headers: { Authorization: `Bearer ${process.env.QOMNI_KEY}` },
   });
   if (!response.ok) {
     const { error } = await response.json();
     throw new Error(`${error.code}: ${error.message}`);
   }
   console.log(await response.json());
   ```

   Execute:

   ```bash
   python ping.py
   ```

   ```bash
   npx tsx ping.mts
   ```

   Um `200` traz seu workspace e `livemode: false`, porque a chave é de
   teste. A resposta pode trazer mais campos: ignore os que você não conhece.

   ```json title="200 OK"
   {
     "product": "agents",
     "tenant": "acme",
     "cell": "co1",
     "region": "co",
     "livemode": false
   }
   ```

   Um `401` significa que a chave falta ou não é válida: o campo `code` do
   erro diz qual das duas. Veja [Erros](/pt-br/concepts/errors/).

4. ### Crie uma chamada

   Peça que um agente ligue para um número. Em modo de teste, `+15005550001` é
   um [número mágico](/pt-br/concepts/test-mode/) que sempre termina em
   `completed`. Salve o código em `create_call.py` ou `create_call.mts` e
   execute como no passo anterior:

   ```bash
   curl https://api.qomni.ai/agents/v1/calls \
     -H "Authorization: Bearer $QOMNI_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "to": "+15005550001" }'
   ```

   ```python
   import os

   import requests

   key = os.environ["QOMNI_KEY"]
   response = requests.post(
       "https://api.qomni.ai/agents/v1/calls",
       headers={"Authorization": f"Bearer {key}"},
       json={"to": "+15005550001"},
       timeout=10,
   )
   if not response.ok:
       error = response.json()["error"]
       raise SystemExit(f"{error['code']}: {error['message']}")
   call = response.json()
   print(call["id"], call["status"])
   ```

   ```typescript
   const url = "https://api.qomni.ai/agents/v1/calls";
   const response = await fetch(url, {
     method: "POST",
     headers: {
       Authorization: `Bearer ${process.env.QOMNI_KEY}`,
       "Content-Type": "application/json",
     },
     body: JSON.stringify({ to: "+15005550001" }),
   });
   if (!response.ok) {
     const { error } = await response.json();
     throw new Error(`${error.code}: ${error.message}`);
   }
   const call = await response.json();
   console.log(call.id, call.status);
   ```

   A API responde `201` com a chamada:

   ```json title="201 Created"
   {
     "id": "call_01k8x2m4v7q9r3t5w8y1z0a2b4",
     "to": "+15005550001",
     "status": "completed",
     "livemode": false,
     "cell": "co1",
     "region": "co",
     "created_at": "2026-10-21T15:04:05+00:00"
   }
   ```

## Você deve ver

A chamada existe, com status `completed`, e nenhum telefone tocou: assim
funciona o [modo de teste](/pt-br/concepts/test-mode/). Você acabou de fazer as duas
chamadas que qualquer integração com o Agents faz: verificar a chave e criar
uma chamada. `GET /calls` as devolve para você, a mais recente primeiro.

Se no passo 3 você viu `401`, o campo `code` diz por quê: `api_key_missing`
se o header falta, `api_key_malformed` se a chave foi copiada errado,
`api_key_invalid` se foi revogada.

## Próximo passo

Troque a chave de teste por uma real (`sk_agents_live_…`) e o mesmo código
faz chamadas de verdade. Antes disso, coloque o agente para conversar com seu app:

- [Fale com um agente em tempo real](/pt-br/agents/realtime/) — Crie uma sessão e converse com o agente por WebSocket, sem expor sua chave.

- [Referência do Agents](/pt-br/agents-api/): cada endpoint, campo e erro.
- [Idempotência e novas tentativas](/pt-br/concepts/idempotency/): tente de novo sem criar duas chamadas.

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