Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Ferramentas Externas e SDKs Suportados

Aula 3 de 12 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. Três pontos de entrada para o mesmo mecanismo
  2. O SDK nativo da xAI
  3. A API Responses, compatível com OpenAI
  4. A API Voice Agent
  5. O que não muda entre interfaces
  6. Pontos-chave

Três pontos de entrada para o mesmo mecanismo

A xAI expõe o MCP remoto através de três interfaces. Cada uma destina-se a um tipo diferente de programador: uma para novos projetos, outra para projetos migrados e a terceira para contextos de utilização específicos. O comportamento do MCP é exatamente o mesmo nos três casos; apenas a sintaxe de configuração e as ferramentas periféricas mudam. A sua escolha depende, portanto, da sua stack existente, e não das capacidades do protocolo.

O SDK nativo da xAI

Este é o método recomendado pela xAI. Fornece um auxiliar mcp() que condensa a configuração numa única chamada de função.

from xai_sdk import Client
from xai_sdk.tools import mcp

client = Client(api_key=os.getenv("XAI_API_KEY"))

chat = client.chat.create(
    model="grok-4.20-0309-reasoning",
    tools=[
        mcp(server_url="https://mcp.deepwiki.com/mcp")
    ],
    include=["verbose_streaming"],
)

O auxiliar mcp() aceita todos os parâmetros de configuração do MCP — URL, etiqueta, descrição, ferramentas permitidas, autenticação — e trata da sua formatação correta para a API. Esta é a sintaxe mais concisa e, crucialmente, aquela em que é menos provável cometer erros, uma vez que os nomes das chaves e a aninhamento são geridos automaticamente. Escolha este caminho para um novo projeto sem restrições de compatibilidade, para qualquer prototipagem rápida e sempre que utilizar funcionalidades específicas da xAI, como o streaming detalhado visível acima.

A API Responses, compatível com OpenAI

Esta interface aceita exatamente o formato da API OpenAI. Existe por uma razão específica: para que uma equipa que já tenha escrito a sua aplicação neste formato não tenha de reescrever tudo para experimentar o Grok. A alteração limita-se à chave da API e ao URL base.

from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("XAI_API_KEY"),
    base_url="https://api.x.ai/v1",
)

response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input=[{"role": "user", "content": "Explain the React project"}],
    tools=[{
        "type": "mcp",
        "server_url": "https://mcp.deepwiki.com/mcp",
        "server_label": "deepwiki",
    }],
)

Aqui, o servidor MCP é declarado como um elemento do array tools, com o tipo "mcp" e os parâmetros como pares chave-valor no mesmo objeto. Sem auxiliar: escreve o dicionário manualmente, o que deixa mais margem para erros de digitação nos nomes das chaves.

Esta compatibilidade tem um custo, e deve conhecê-lo antes de construir sobre ela. Dois parâmetros disponíveis no SDK nativo não estão disponíveis aqui: require_approval, que permite exigir validação humana antes de executar uma ferramenta MCP, e connector_id, que gere conectores OpenAI. Se o seu agente lida com operações sensíveis e contava com validação manual, esta limitação é um bloqueio e deve levá-lo de volta ao SDK nativo da xAI. A API Responses continua a ser a escolha certa para uma migração a partir da OpenAI sem reescrita, para um projeto multi-fornecedor onde alterna entre o Grok e outros modelos, e para uma equipa já familiarizada com este formato.

A API Voice Agent

A terceira interface foi concebida para agentes de voz. O cenário típico é um assistente telefónico que, no meio de uma conversa, precisa de consultar uma base de conhecimentos, verificar o estado de uma encomenda ou consultar um sistema externo — sem que o interlocutor experiencie um silêncio inexplicável.

A configuração do MCP segue o mesmo formato dos outros SDKs, com os mesmos parâmetros server_url, server_label e outros. A diferença reside no que acontece após a chamada da ferramenta: o resultado é integrado no fluxo de síntese de voz em vez de ser apresentado como texto. Isto molda a forma como escreve as descrições das suas ferramentas e enquadra as suas respostas, uma vez que o utilizador nunca verá uma tabela ou uma lista — apenas as ouvirá.

O que não muda entre interfaces

Seja qual for o SDK, a sequência é a mesma. O Grok descobre as ferramentas expostas pelo servidor MCP, seleciona a que corresponde ao pedido, formula a chamada com os parâmetros corretos e, em seguida, integra o resultado na sua resposta. Nenhuma das três interfaces torna o modelo mais ou menos competente na escolha de uma ferramenta.

As diferenças residem, portanto, noutros aspetos: concisão da sintaxe, funcionalidades periféricas disponíveis — streaming detalhado no SDK da xAI, compatibilidade de formato na API Responses, síntese de voz na Voice Agent — e os dois parâmetros em falta no formato OpenAI. Decida com base nestes critérios e não errará.

Pontos-chave

  • O SDK nativo da xAI com mcp() é o método mais simples e completo
  • A API Responses (formato OpenAI) facilita a migração, mas não suporta require_approval nem connector_id
  • A API Voice Agent liga agentes de voz a ferramentas MCP
  • O comportamento do MCP é idêntico nos três casos; apenas a sintaxe muda
  • Escolha com base na sua stack existente e nas suas necessidades específicas