API do Grok Voice Agent: Uma maneira de criar assistentes de voz em tempo real

Os agentes de IA de voz estão em alta. Os usuários querem conversar com seus aplicativos em vez de digitar neles, e a tecnologia finalmente está boa o suficiente para tornar essas conversas naturais.

Se você quiser criar um, a API Grok Voice Agent da xAI é um bom ponto de partida. Ele oferece tempos de resposta inferiores a um segundo e custos mais baixos do que a maioria das alternativas, além de compatibilidade direta com o código OpenAI existente.

Este tutorial mostra como criar um agente de voz funcional do zero. Você vai conectar a autenticação, configurar as opções de personalidade e voz, adicionar chamadas de ferramentas e implantar na produção com o LiveKit na nuvem. A API funciona no Grok 3, que a xAI adaptou para conversas de voz em tempo real, em vez do fluxo de trabalho normal de entrada e saída de texto.

O que é a API do Grok Voice Agent?

A API Grok Voice Agent é a plataforma de conversação por voz em tempo real da xAI, lançada em dezembro de 2025. Ele processa o áudio direto, sem precisar converter de fala para texto e vice-versa, o que reduz o tempo de resposta e mantém as conversas soando naturais.

Os sistemas tradicionais de IA de voz juntam três etapas: transcrever a fala em texto, passar esse texto por um modelo de linguagem e, por fim, transformar a resposta de volta em áudio. Essa abordagem funciona, mas cada transferência entre componentes adiciona atraso. Quando você pensa na transcrição, processamento e síntese, leva de 500 ms a 1.000 ms para o usuário receber uma resposta. Essas pausas se acumulam e fazem com que as conversas pareçam mecânicas.

O Grok Voice Agent pula as conversões completamente. O sistema recebe áudio, processa no domínio do áudio e gera áudio usando um único modelo treinado em fala conversacional. Essa arquitetura oferece um tempo médio de resposta de áudio de 0,78 segundos, ao mesmo tempo em que suporta comunicação full-duplex (áudio bidirecional simultâneo, em que o agente pode ouvir e falar ao mesmo tempo), para que ele possa responder sem esperar pela vez de falar.

Configurando seu ambiente do Grok Voice Agent

Pra criar um agente de voz com o Grok, você precisa conectá-lo com o LiveKit, uma plataforma WebRTC de código aberto. A Grok fornece o modelo de IA conversacional, enquanto o LiveKit gerencia a infraestrutura de áudio em tempo real que conecta os usuários ao seu agente. Esta seção fala sobre como configurar os dois serviços.

Configurando o Grok

Visite console.x.ai e crie uma conta usando autenticação X, e-mail, Google ou Apple. O console xAI precisa de créditos pré-pagos antes de você poder fazer chamadas de API. Compre créditos na seção Faturamento.

Com créditos na sua conta, vá até Chaves API e crie uma nova chave. O console mostra a chave só uma vez, então anote ela rapidinho e guarde em um lugar seguro. Se perder, você vai precisar gerar um substituto e atualizar seus aplicativos. Para saber mais sobre o ecossistema da API da xAI, dá uma olhada no tutorial da API Grok 3.

Configurando o LiveKit

O LiveKit é uma infraestrutura WebRTC para áudio e vídeo em tempo real. Ele cuida da camada de transporte de áudio que o Grok precisa para se conectar com os usuários. Ao criar um agente de voz, o LiveKit gerencia salas onde as conversas rolam, encaminha fluxos de áudio entre os participantes e oferece uma infraestrutura de implantação. A estrutura LiveKit Agents cuida dessa complexidade, deixando você focar no comportamento do agente enquanto ela gerencia a conexão, a codificação de áudio e a detecção de turnos.

A estrutura suporta vários fornecedores de IA, incluindo a xAI. Inclui um ambiente de testes acessível por meio de uma interface web, que você vai usar para validar seu agente antes de implantá-lo.

Cadastre-se em nuvem.livekit.io. O nível gratuito oferece recursos suficientes para desenvolvimento e testes. Crie um projeto pelo painel. Vá até Configurações e depois Chaves API. Copie três credenciais: LIVEKIT_URL (o endpoint WebSocket do seu projeto), LIVEKIT_API_KEY (o identificador público) e LIVEKIT_API_SECRET (a chave de autenticação privada). Essas credenciais autenticam o código do seu agente com o seu projeto LiveKit na nuvem.

Instalando dependências e configuração

Instale os pacotes necessários:

uv add "livekit-agents[xai,openai]>=1.3.10" python-dotenv

Isso instala a estrutura de agentes LiveKit com o plug-in xAI e as dependências OpenAI (o plug-in xAI se baseia na compatibilidade com a API em tempo real da OpenAI), além do python-dotenv para gerenciamento de variáveis de ambiente.

Crie um arquivo .env na raiz do seu projeto:

XAI_API_KEY=xai-YourActualKeyHere
 LIVEKIT_URL=wss://your-project.livekit.cloud
 LIVEKIT_API_KEY=APIYourKeyHere
 LIVEKIT_API_SECRET=YourSecretHere

Troque os valores dos espaços reservados pelas suas credenciais reais. Carregue essas credenciais no seu código Python:

from dotenv import load_dotenv
 load_dotenv()

Isso deixa as credenciais disponíveis para as bibliotecas xAI e LiveKit. Adicione .env ao seu .gitignore para evitar vazamentos de credenciais no controle de versão.

Criando seu primeiro agente de voz Grok

Com o seu ambiente configurado, você pode criar um agente de voz funcional. Comece com as importações e a classe agente em um novo arquivo chamado agent.py:

from livekit.agents import Agent, AgentSession, AgentServer, JobContext, cli
from livekit.plugins.xai import realtime
from dotenv import load_dotenv

load_dotenv()

class ResearchAssistant(Agent):
	def __init__(self):
    	super().__init__(
        	instructions="You are a research assistant who helps users find information.",
 	)

Sua subclasse ` Agent ` só tem as instruções que definem como o agente reage. Funcionam como um aviso do sistema, dizendo ao agente qual papel desempenhar. A configuração real do modelo vai para outro lugar.

Depois, configura o servidor e o manipulador de conexão:

server = AgentServer()


@server.rtc_session()
async def entrypoint(ctx: JobContext):
	await ctx.connect()

 	session = AgentSession(
         llm=realtime.RealtimeModel(voice="ara"),
 	)

 	await session.start(
     	room=ctx.room,
     	agent=ResearchAssistant(),
 	)

O decorador ` @server.rtc_session() ` diz ao LiveKit para rodar sua função de ponto de entrada sempre que alguém se conectar. Por dentro, o AgentSession usa a configuração do modelo, incluindo qual das sete vozes do Grok usar (Ara, Eve, Leo, Sal, Rex, Mika ou Valentin). Quando o session.start() é executado, ele conecta seu agente à sala do LiveKit onde a conversa rola.

As conversas de voz envolvem esperar pela entrada e saída de áudio sem travar o programa, então a função usa async def e await para lidar com essas operações simultaneamente.

Por fim, adicione o ponto de entrada:

if __name__ == "__main__":
 	cli.run_app(server)

Execute seu agente no modo de desenvolvimento:

uv run agent.py dev

O terminal mostra a sequência de inicialização: inicialização do trabalhador, servidor HTTP escutando em uma porta local e registro no seu projeto LiveKit da nuvem.

Pra testar o agente, dá uma olhada no seu painel do LiveKit Cloud na nuvem.livekit.io. Escolha seu projeto e clique na aba Sandbox na barra lateral. Escolha o Web Voice Agent nos modelos.

A página do modelo mostra uma prévia da interface de voz junto com detalhes sobre o que ela inclui. Clique no botão Criar sandbox.

Na janela modal que aparece, você pode configurar uma URL personalizada, ativar recursos como compartilhamento de câmera e tela e ajustar as configurações de aparência. As configurações padrão funcionam bem para testes, então clique em Criar e, em seguida, em Concluído.

De volta à página Sandbox, sua nova área restrita aparece em Aplicativos da área restrita. Clique em Iniciar para abrir.

Clique em Iniciar chamada e dê permissão para usar o microfone quando for solicitado. Fique de olho no terminal pra ver essa mensagem de log, que mostra que o agente tá pronto pra receber áudio:

DEBUG livekit.agents start reading stream {"participant": "...", "source": "SOURCE_MICROPHONE", ...}

Depois que essa mensagem aparece, as respostas chegam rapidinho.

Quando você pergunta sobre algo que o agente não consegue acessar (como o tempo atual em uma cidade específica), ele explica suas limitações em vez de inventar respostas.

Como adicionar ferramentas aos seus agentes de voz Grok

O agente básico consegue manter uma conversa, mas não tem como pesquisar informações. A chamada de ferramentas permite que o Grok execute funções no meio da conversa e fale sobre os resultados. Você pode usar as ferramentas integradas do xAI ou criar as suas próprias.

Usando ferramentas integradas

O plugin xAI inclui WebSearch para consultas gerais na web e XSearch para pesquisar publicações no X. Importe-os e passe-os para AgentSession:

from livekit.agents import Agent, AgentSession, AgentServer, JobContext, cli
from livekit.plugins.xai import realtime
from livekit.plugins.xai.realtime import WebSearch, XSearch
from dotenv import load_dotenv

load_dotenv()


class ResearchAssistant(Agent):
 	def __init__(self):
     	super().__init__(
             instructions="""You are a research assistant with access to web search and X search.

- Use web search for general queries and current information
- Use X search when users ask about posts or what people are saying on X/Twitter

Always mention your sources when providing information.""",
     	)


server = AgentServer()


@server.rtc_session()
async def entrypoint(ctx: JobContext):
	await ctx.connect()

	session = AgentSession(
         llm=realtime.RealtimeModel(voice="ara"),
     	tools=[
         	WebSearch(),
         	XSearch(),
     	],
 	)

 	await session.start(
     	room=ctx.room,
     	agent=ResearchAssistant(),
 	)


if __name__ == "__main__":
 	cli.run_app(server)

O parâmetro ` tools ` aceita uma lista de objetos de ferramenta. Execute o agente e teste com perguntas como “Quais são as últimas notícias sobre IA?” ou “O que as pessoas estão falando sobre o Grok no X?” Os registros do terminal podem mostrar avisos sobre funções desconhecidas da IA, como web_search_with_snippets ou x_semantic_search, mas as ferramentas mostram as informações atuais mesmo assim.

O áudio full-duplex do Grok também fica bem claro quando você usa as ferramentas. Você pode interromper o agente enquanto ele estiver falando, e ele vai parar, ouvir e ajustar sua resposta. Isso faz com que as conversas pareçam menos robóticas do que os sistemas que exigem que se espere o agente terminar antes de falar.

Adicionando ferramentas personalizadas

As ferramentas integradas cobrem casos de uso comuns, mas definir suas próprias ferramentas te dá controle sobre os parâmetros, o tratamento de erros e quais APIs chamar. Esta seção mostra como criar uma ferramenta personalizada usando o ponto final de pesquisa do Firecrawl, que oferece opções de filtragem como limit, lang e country que a pesquisa integrada na web não oferece.

Cadastre-se em firecrawl.dev. O plano gratuito inclui 500 créditos e não precisa de cartão de crédito. Instale o SDK e adicione sua chave a .env:

uv add firecrawl-py

FIRECRAWL_API_KEY=fc-your-key-here

Ferramentas personalizadas são métodos decorados com @function_tool(). Atualize as importações em search_agent.py:

from livekit.agents import (
 	Agent,
 	AgentSession,
 	AgentServer,
 	JobContext,
 	cli,
 	function_tool,
 	RunContext,
 )

from livekit.plugins.xai import realtime
from livekit.plugins.xai.realtime import XSearch
from firecrawl import FirecrawlApp
from dotenv import load_dotenv

import os 
load_dotenv()

As adições são function_tool para o decorador, RunContext que é passado para as funções da ferramenta e FirecrawlApp para o cliente Firecrawl. WebSearch foi removido, pois a ferramenta personalizada o substitui.

Defina a ferramenta como um método na sua classe de agente:

class ResearchAssistant(Agent):
 	def __init__(self):
     	super().__init__(
             instructions="""You are a research assistant with access to web search and X search.

 - Use Firecrawl search for general queries and current information
 - Use X search when users ask about posts or what people are saying on X/Twitter

 Always mention your sources when providing information.""",
     	)
     	self.firecrawl = FirecrawlApp(api_key=os.getenv("FIRECRAWL_API_KEY"))

 	@function_tool()
     async def search_web(
     	self,
     	context: RunContext,
     	query: str,
 	) -> dict:
     	"""Search the web for current information using Firecrawl.

     	Args:
         	query: The search query
     	"""
     	result = self.firecrawl.search(query, limit=3)
     	return {
         	"results": [
             	{
                 	"title": item.title,
                 	"url": item.url,
                     "description": item.description,
             	}
             	for item in result.web
         	]
     	}

O Grok lê a string de documentação para entender o que a ferramenta faz. Quando você pergunta “Qual é a taxa de câmbio atual do dólar americano para o euro?”, o Grok pega a pergunta, chama sua função e coloca os resultados na resposta.

Os métodos decorados com @function_tool() são registrados automaticamente, portanto, remova WebSearch() da lista de ferramentas:

session = AgentSession(
     llm=realtime.RealtimeModel(voice="ara"),
 	tools=[
     	XSearch(),
 	],
 )

Execute o agente atualizado:

uv run search_agent.py dev

O terminal mostra a execução da ferramenta:

DEBUG livekit.agents executing tool {
 	"function": "search_web",
 	"arguments": "{\"query\":\"current USD to EURO exchange rate\"}",
 	...
 }
DEBUG livekit.agents tools execution completed {...}

Nos meus testes, o Firecrawl mostrou os resultados em cerca de dois segundos. Você pode juntar várias ferramentas personalizadas com as ferramentas integradas no mesmo agente. Um agente de suporte ao cliente, por exemplo, pode usar o XSearch junto com as ferramentas personalizadas lookup_order() e check_inventory(), que se conectam a bancos de dados internos.

Personalizando a detecção de curvas

As configurações padrão de detecção de turno funcionam bem em conversas normais. Os ajustes são necessários quando o ambiente ou o comportamento do usuário diferem do normal. Uma sala barulhenta pode fazer com que o agente responda aos sons de fundo, enquanto um usuário que faz uma pausa para organizar seus pensamentos pode ser interrompido antes de terminar.

from livekit.plugins.xai import realtime
from openai.types.beta.realtime.session import TurnDetection

session = AgentSession(
 	llm=realtime.RealtimeModel(
     	voice="ara",
     	turn_detection=TurnDetection(
         	type="server_vad",
         	threshold=0.5,
         	prefix_padding_ms=300,
         	silence_duration_ms=200,
     	),
 	),
 )

O parâmetro threshold define o volume que o áudio precisa ter para ser considerado fala, variando de 0,0 a 1,0. Aumentar esse valor para 0,7 ou mais ajuda em ambientes barulhentos, onde os sons de fundo podem acabar ativando respostas.

O parâmetroprefix_padding_ms define quanto áudio capturar antes do início detectado da fala. O padrão de 300 ms evita que a primeira sílaba seja cortada. Aumente isso se os usuários disserem que suas primeiras palavras estão sendo cortadas.

O parâmetrosilence_duration_ms controla quanto tempo o agente espera depois que você para de falar antes de responder. Com 200 ms, as conversas parecem bem responsivas. Aumentar isso para 400 ou 500 ms acomoda usuários que fazem uma pausa no meio da frase ou falam em um ritmo mais lento.

Para interfaces push-to-talk ou sistemas de telefonia em que você precisa de controle explícito sobre o fluxo da conversa, desative a detecção automática de virada:

session = AgentSession(
 	llm=realtime.RealtimeModel(
     	voice="ara",
     	turn_detection=None,
 	),
 )

O agente então espera por um sinal programático antes de responder, em vez de ficar à espera do silêncio.

Implantando o Grok Voice Agent na produção

O modo de desenvolvimento conecta o agente à sua máquina local. Para uma implantação de produção que funciona 24 horas por dia, 7 dias por semana, e se adapta à demanda, o LiveKit na nuvem hospeda seu agente na infraestrutura deles.

Preparando para a implantação

O LiveKit CLI descobre o tipo do seu projeto através dos arquivos de dependência. Crie um arquivo requirements.txt no diretório do seu agente:

livekit-agents[xai,openai]>=1.3.10
python-dotenv>=1.2.1
firecrawl-py>=4.12.0

Crie um arquivo separado para os segredos de produção. O LiveKit na nuvem fornece automaticamente LIVEKIT_URL, LIVEKIT_API_KEY e LIVEKIT_API_SECRET, então você só precisa incluir suas outras chaves API:

XAI_API_KEY=xai-your-key-here
FIRECRAWL_API_KEY=fc-your-key-here

Salve isso como .env.production e adicione ao .gitignore.

Implantando o agente

Autentique a CLI com sua conta LiveKit da nuvem:

lk cloud auth

Isso abre um navegador para conectar sua CLI ao seu projeto. Depois de autenticado, implante o agente:

lk agent create --secrets-file .env.production

A CLI registra seu agente, gera um Dockerfile, cria a imagem do contêiner e a implanta na nuvem de LiveKit. Os registros são enviados para o seu terminal assim que o agente é iniciado:

{"message": "registered worker", "level": "INFO", "name": "livekit.agents", "url": "https://your-project.livekit.cloud", "region": "Germany 2", ...}

Verifique o status da implantação:

lk agent status

┌─────────────────┬─────────────────┬────────────┬─────────┬────────┬─────────┬───────────┐
 │ ID          	│ Version     	│ Region 	│ Status  │ CPU	│ Mem 	│ Replicas  │
 ├─────────────────┼─────────────────┼────────────┼─────────┼────────┼─────────┼───────────┤
 │ CA_AAVy5WbUYpmA │ v20260109102531 │ eu-central │ Running │ 0m / 2 │ 0 / 4GB │ 0 / 1 / 1 │
 └─────────────────┴─────────────────┴────────────┴─────────┴────────┴─────────┴───────────┘

Como os usuários acessam seu agente

A URL nos registros de implantação (https://your-project.livekit.cloud) é o backend do WebSocket, não uma interface de usuário. Os usuários interagem com o seu agente por meio de um front-end que se conecta a esse back-end.

A área restrita que você criou antes serve pra isso. Vá até o painel do LiveKit, abra a seção Sandbox e copie o URL da sua sandbox. Esse URL é acessível ao público e funciona sem precisar de autenticação. Compartilhe com os usuários e eles poderão começar a conversar com seu agente imediatamente.

Para uma experiência personalizada, dá uma olhada no painel e muda a aparência da área restrita (logotipo, cores, texto dos botões) ou cria sua própria interface usando o o SDK JavaScript do LiveKit.

Gerenciando implantações

Veja os registros em tempo real do seu agente implantado:

lk agent logs

Implemente as atualizações depois de mexer no seu código:

lk agent deploy --secrets-file .env.production

O LiveKit usa implantações contínuas. Novas instâncias cuidam das novas sessões enquanto as instâncias já existentes terminam suas conversas ativas, então as atualizações não causam tempo de inatividade.

Volta para uma versão anterior se algo der errado:

lk agent rollback

O agente implantado funciona de forma independente da sua máquina local. Feche o terminal, desligue o computador e o agente continuará respondendo aos usuários. O LiveKit na nuvem cuida do dimensionamento, então picos de tráfego ativam instâncias adicionais automaticamente.

Custos de implantação

Usar um agente de voz Grok na produção tem dois custos: a API da xAI e a hospedagem do LiveKit.

A xAI cobra US$ 0,05 por minuto de conversa de voz. O LiveKit na nuvem cobra US$ 0,01 por minuto de tempo de sessão do agente. No total, espere pagar cerca de US$ 0,06 por minuto quando seu agente estiver atendendo usuários.

O plano gratuito do LiveKit (plano Build) inclui 1.000 minutos de sessão de agente por mês, sem necessidade de cartão de crédito. Isso dá pra cerca de 16 horas de conversa, o suficiente pra testes e aplicações com pouco tráfego. Os planos pagos começam em US$ 50/mês, com 5.000 minutos incluídos e limites de simultaneidade mais altos.

O agente não custa nada quando não está sendo usado. As cobranças só valem durante conversas ativas, então uma implantação que fica parada durante a noite não tem taxas do LiveKit. O faturamento da xAI segue o mesmo padrão, medindo só o uso real da API. Durante meus experimentos enquanto escrevia este artigo, gastei um total de 78 centavos no xAI, com o LiveKit coberto por seu plano gratuito.

Conclusão

Agora você tem um assistente de voz que escuta, pensa e responde. O agente se conecta a dados em tempo real por meio de ferramentas, ajusta seu comportamento de escuta para diferentes ambientes e funciona em uma infraestrutura que se adapta sem precisar mexer nela manualmente.

Os padrões de código abordados aqui se estendem a outros casos de uso. Troque as instruções do assistente de pesquisa pelas diretrizes de suporte ao cliente e adicione ferramentas que consultem seu banco de dados de pedidos. Crie um tutor de idiomas que procure frases de exemplo. Crie uma interface de voz para sua API atual.

A xAI tá planejando lançar pontos finais independentes de conversão de texto em fala e de fala em texto, o que vai abrir arquiteturas híbridas onde você pode misturar os recursos de voz do Grok com outros modelos de linguagem. Por enquanto, a API do agente de voz cuida de tudo.

A documentação do LiveKit Agents fala sobre recursos extras, tipo transferências entre vários agentes e persistência de sessão. Os documentos da xAI falam mais sobre formatos de áudio e recursos empresariais.