Integrações de SDK e frameworks

Todo SDK se conecta ao GateLLM com os mesmos três passos. Encontre seu SDK, anote a convenção de base_url e a armadilha dele, e então copie o padrão.

O gateway é orientado a protocolo: qualquer que seja o SDK que você use, contanto que ele fale OpenAI / Anthropic / Gemini / DashScope / Realtime / MCP, apontar o base_url para o gateway e trocar por uma chave de acesso permite chamar qualquer modelo configurado — incluindo chamadas entre protocolos para modelos de outros fornecedores.

1

Aponte o base_url para o gateway

Padrão https://your-gateway.gatellm.io — incluir ou não /v1 depende do SDK (cada exemplo traz o valor exato).

2

Troque por uma chave de acesso do gateway

Não é uma chave upstream sk-… — a mesma chave de acesso é montada no cabeçalho que o seu SDK espera.

3

Use o nome de modelo do gateway

Aquele que você configurou no console — não o nome oficial do fornecedor.

Authorization: Bearer <key>
OpenAI · DashScope · genérico
Prefixo Bearer não diferencia maiúsculas de minúsculas
x-api-key: <key>
SDK Anthropic
Authorization também é aceito
x-goog-api-key: <key>
SDK Gemini
Authorization também é aceito

Matriz de seleção de SDK

SDK / frameworkLinguagemProtocoloDocumentação
SDKs oficiais dos fornecedoresExemplos no GitHub ↗
OpenAI SDKPython, Node.jsOpenAIDocumentação
Anthropic SDKPython, Node.jsAnthropicDocumentação
Google GenAI SDKPython, JavaScriptGeminiDocumentação
OpenAI-compatible third partiesPython, Node.jsOpenAI-compatibleDocumentação
DashScope nativo
DashScope SDKPythonDashScopeDocumentação
SDKs e gateways unificadosExemplos no GitHub ↗
Vercel AI SDKTypeScriptOpenAI / AnthropicDocumentação
LiteLLMPythonOpenAI-compatibleDocumentação
PortkeyNode.js, PythonOpenAI-compatibleDocumentação
Braintrust / LangbaseTypeScript, PythonOpenAI-compatibleDocumentação
Semantic KernelPython, .NETOpenAI-compatibleDocumentação
Spring AIJavaOpenAI-compatibleDocumentação
Frameworks de orquestraçãoExemplos no GitHub ↗
LangChainPython, TypeScriptOpenAI / AnthropicDocumentação
LangGraphPython, TypeScriptOpenAI / AnthropicDocumentação
LlamaIndexPython, TypeScriptOpenAI-compatibleDocumentação
CrewAIPythonOpenAI-compatible (LiteLLM)Documentação
AutoGen / AG2PythonOpenAI-compatibleDocumentação
DSPyPythonOpenAI-compatibleDocumentação
HaystackPythonOpenAI-compatibleDocumentação
Llama StackPythonOpenAI-compatibleDocumentação
SDKs de agentes
OpenAI Agents SDKPython, TypeScriptOpenAI ResponsesDocumentação
Claude Agent SDKPython, TypeScriptAnthropicDocumentação
Pydantic AIPythonOpenAI-compatibleDocumentação
Google ADKPythonOpenAI-compatible (LiteLLM)Documentação
MastraTypeScriptOpenAI-compatibleDocumentação
Microsoft Agent Framework.NET, PythonOpenAI-compatibleDocumentação
MCP SDKPython, TypeScriptMCPDocumentação
Tempo real e áudio
Realtime WebSocketAny WS clientOpenAI RealtimeDocumentação
openai_audio (ASR / TTS)Python, Node.jsOpenAI audioDocumentação
Local / auto-hospedado
OllamaRESTOpenAI-compatible (upstream)Documentação
vLLMRESTOpenAI-compatible (upstream)Documentação
llama.cpp serverRESTOpenAI-compatible (upstream)Documentação
SGLangRESTOpenAI-compatible (upstream)Documentação
Text Generation Inference (TGI)RESTOpenAI-compatible (upstream)Documentação
LM StudioRESTOpenAI-compatible (upstream)Documentação

Armadilhas

O nome do modelo precisa corresponder à configuração do gateway

Não é o nome oficial do fornecedor nem o ID do modelo upstream — é o nome que você deu no console. Nome errado → 404 model_not_found.

Incluir /v1 no base_url varia conforme o SDK

O SDK OpenAI usa /v1; o SDK Anthropic usa a raiz (ele mesmo acrescenta /v1/messages); o createAnthropic do Vercel AI SDK usa /v1 (ele acrescenta /messages). Errar isso adiciona ou remove um segmento de caminho.

Campos são traduzidos e restringidos entre protocolos

Um max_tokens pode virar max_output_tokens com limite inferior (por exemplo, ≥16) quando o upstream é um modelo de protocolo Responses — valor pequeno demais → 400.

Blocos de raciocínio são envolvidos pelo gateway

Conteúdo e assinaturas de raciocínio do Claude / Gemini passam adiante ou são removidos — pegue o elemento com type == "text" do array content, não presuma que content[0] é texto.

O SDK OpenAI Agents usa /v1/responses por padrão

Ele chama a API Responses, não Chat Completions. Se o upstream for openai (Chat), troque explicitamente com OpenAIChatCompletionsModel; se for openai_response, um nome de modelo em string funciona como está.

O LlamaIndex valida o nome do modelo contra uma allowlist

A classe OpenAI só aceita famílias que reconhece e rejeita nomes personalizados do gateway — use OpenAILike (Python) ou declare as informações do modelo explicitamente.

O CrewAI é movido pelo LiteLLM nos bastidores

base_url não é um parâmetro do framework — é a variável de ambiente OPENAI_API_BASE, e o modelo precisa do prefixo openai/.

O AutoGen exige model_info explícito

Nomes de modelo desconhecidos geram erro na lista padrão — declare model_info explicitamente para contornar a verificação.

O SDK Google GenAI aponta para a raiz

O base_url vai por http_options.base_url (sem /v1) e a chave é montada no cabeçalho x-goog-api-key.

FAQ