Guia de Integração do Gate.AI LangChain com LangGraph

O Gate.AI oferece endpoints compatíveis com a API do OpenAI, permitindo que desenvolvedores utilizem esse endpoint para integrar LangChain e LangGraph, realizando chamadas de modelos roteados pelo Gate.AI. Quando uma aplicação Python precisa de prompts baseados em cadeias, fluxos de trabalho de agentes baseados em gráficos, ou deseja construir uma gateway de modelos unificada que não exija reescrever a lógica para cada provedor de modelos, essa solução é especialmente relevante. Este documento abordará a configuração do ambiente local, testes de chamadas com LangChain, prompts com LangChain e um fluxo de trabalho simples com LangGraph. Não cobre implantação em produção, bancos de vetores, observabilidade, configurações de cobrança ou políticas de acesso empresarial.

Pré-requisitos

• Conta no Gate.AI com chave API criada
• Python 3.10 ou superior, com permissão para instalar pacotes dependentes

Fonte do conteúdo: documentação oficial do Gate.AI e materiais de produto, com data até junho de 2026.

O que você terá ao concluir este guia?

Você será capaz de conectar o Gate.AI ao LangChain usando ChatOpenAI e reutilizar a mesma configuração de modelo em fluxos de trabalho do LangGraph.

Este método ajuda você a:

• Chamar o Gate.AI em scripts Python locais
• Testar a configuração de modelo="auto" roteada pelo Gate.AI
• Substituir auto pelo ID de modelo verificado do Gate.AI quando necessário
• Executar prompts com LangChain
• Executar fluxos de trabalho de duas etapas com LangGraph

Para uma visão mais ampla sobre integração de APIs, consulte a documentação de API para desenvolvedores do Gate.AI.

Passo 1: Instalar dependências Python

Este passo instala os pacotes necessários para o fluxo de trabalho local, incluindo integração do LangChain com OpenAI e o pacote LangGraph.

• Criar e ativar ambiente virtual:

  bash python -m venv .venv source .venv/bin/activate

  pip install -U langchain langchain-openai langgraph

• Comando para ativar no PowerShell do Windows:

  powershell .venv\Scripts\Activate.ps1

Após a instalação, deve ser possível importar normalmente langchain_openai e langgraph.

Passo 2: Armazenar a chave API do Gate.AI

Este passo armazena a chave API fora do código fonte.

• No terminal bash, definir variável de ambiente:

  bash export GATEAI_API_KEY="SUA_CHAVE_API"

• No PowerShell do Windows:

  powershell setx GATEAI_API_KEY "SUA_CHAVE_API"

Após usar setx, reinicie a sessão do PowerShell para que a variável seja carregada.

Nunca envie sua chave API real para o Git. Para projetos de equipe, recomenda-se usar gerenciadores de segredos, configuração de chaves em CI/CD ou variáveis de ambiente internas aprovadas.

Passo 3: Configurar o Gate.AI no LangChain

Este passo cria um modelo de chat no LangChain que envia requisições compatíveis com o protocolo OpenAI ao Gate.AI.

• Segundo a documentação do Gate.AI de junho de 2026, a URL base compatível com OpenAI é:

• No LangChain, use essa URL como base_url. Não é necessário acrescentar /chat/completions; o LangChain gerencia a rota automaticamente.

• Exemplo:

  python import os from langchain_openai import ChatOpenAI

  llm = ChatOpenAI( model="auto", api_key=os.environ["GATEAI_API_KEY"], base_url="", temperature=0, )

  response = llm.invoke("Escreva uma frase explicando o que faz um roteador de modelos de IA.") print(response.content)

Saída esperada:

O roteador de modelos de IA distribui as requisições para o modelo adequado com base na tarefa, regras de roteamento ou configurações.

O conteúdo retornado pode variar, pois o roteamento do Gate.AI responde dinamicamente de acordo com o modelo selecionado.

Passo 4: Construir uma cadeia de prompts com LangChain

Este passo conecta prompts reutilizáveis, modelos suportados pelo Gate.AI e um parser de saída de string.

• Exemplo:

  python import os from langchain_openai import ChatOpenAI from langchain_core.prompts import ChatPromptTemplate from langchain_core.output_parsers import StrOutputParser

  llm = ChatOpenAI( model="auto", api_key=os.environ["GATEAI_API_KEY"], base_url="", temperature=0, )

  prompt = ChatPromptTemplate.from_messages( [ ("system", "Você é um assistente técnico conciso."), ("human", "Explique {topic} em três pontos principais."), ] )

  chain = prompt | llm | StrOutputParser()

  result = chain.invoke({"topic": "Roteamento de API do Gate.AI"}) print(result)

Você verá uma explicação resumida em três pontos. Se o script gerar erro antes de retornar o texto, verifique primeiro a chave API, URL base e configuração do modelo, ao invés de modificar a estrutura da cadeia diretamente.

Passo 5: Configurar o Gate.AI no LangGraph

Este passo reutiliza a mesma configuração de modelo do Gate.AI em um fluxo de trabalho do LangGraph.

O exemplo gera uma descrição curta em um nó, depois um nó de revisão, mantendo o fluxo simples para validar funcionalidades básicas antes de adicionar ferramentas, memória, busca ou roteamento condicional.

• Exemplo:

  python import os from typing_extensions import TypedDict from langchain_openai import ChatOpenAI from langgraph.graph import StateGraph, START, END

  llm = ChatOpenAI( model="auto", api_key=os.environ["GATEAI_API_KEY"], base_url="", temperature=0, )

  class WorkflowState(TypedDict): topic: str draft: str review: str

  def draft_node(state: WorkflowState) -> dict: response = llm.invoke( [ ("system", "Você escreve explicações técnicas curtas."), ("human", f"Escreva uma explicação de duas frases sobre {state['topic']}."), ] ) return {"draft": response.content}

  def review_node(state: WorkflowState) -> dict: response = llm.invoke( [ ("system", "Você revisa textos técnicos para clareza."), ("human", f"Revise este rascunho e sugira uma melhoria:\n\n{state['draft']}"), ] ) return {"review": response.content}

  builder = StateGraph(WorkflowState) builder.add_node("draft", draft_node) builder.add_node("review", review_node)

  builder.add_edge(START, "draft") builder.add_edge("draft", "review") builder.add_edge("review", END)

  app = builder.compile()

  result = app.invoke({"topic": "Gate.AI com LangGraph"})

  print("Rascunho:\n", result["draft"]) print("\nRevisão:\n", result["review"])

Você verá o rascunho gerado e as sugestões de revisão. Se o fluxo retornar apenas o rascunho, confirme que a aresta de draft para review está corretamente configurada.

Passo 6: Substituir roteamento automático pelo modelo específico

Para maior controle, você pode fixar o modelo assim:

• Se o roteamento automático do Gate.AI estiver ativado e sua conta suportar, inicialmente use model="auto"

• Para resultados reprodutíveis, avaliações consistentes, testes de latência ou revisão em produção, use o ID de modelo específico do Gate.AI

• Exemplo:

  python llm = ChatOpenAI( model="SEU_ID_DE_MODELO", api_key=os.environ["GATEAI_API_KEY"], base_url="", temperature=0, )

Obtenha o ID do modelo na lista de modelos do Gate.AI ou no console do Gate.AI. Não adivinhe o ID, pois a disponibilidade depende da sua conta, do estado do produto e das regras do provedor de modelos (até junho de 2026).

Quais configurações são mais críticas?

| Parâmetro | Exemplo de valor | Cenário de uso | Importância | | ------------------ | --------------------------------------------------------- | ------------------------------| -------------------------------------------------------- | | Variável da chave API | GATEAI_API_KEY | Shell e código Python | Garante que a credencial não apareça no código fonte | | URL base | | ChatOpenAI(base_url=...) | Encaminha requisições compatíveis com OpenAI ao Gate.AI | | Modelo | auto ou SEU_ID_DE_MODELO | ChatOpenAI(model=...) | Escolhe roteamento automático ou modelo fixo | | Temperatura | 0 | ChatOpenAI(temperature=0) | Reduz variabilidade na saída em ambientes de teste |

Para manter o roteamento consistente, recomenda-se usar o mesmo objeto llm no LangChain e no LangGraph. Modifique o parâmetro model apenas ao trocar de roteamento automático para modelo fixo.

Soluções comuns de problemas na integração do Gate.AI com LangChain e LangGraph

Problema: Resposta com erro 401, invalid_api_key ou erro de autenticação

• Causa: Chave API ausente, expirada, com erro de digitação ou shell não consegue ler
• Solução: Execute echo $GATEAI_API_KEY no terminal para verificar se a chave é válida e está configurada no Gate.AI. Se estiver em outra sessão, reinicie o terminal.

Problema: Resposta com erro 404, conexão falha ou endpoint não encontrado

• Causa: URL base incorreta. URL compatível com OpenAI deve ser:
• Solução: Assegure que base_url de cada instância de ChatOpenAI seja exatamente essa URL.

Problema: Python retorna ModuleNotFoundError

• Causa: Pacotes langchain-openai ou langgraph não instalados no ambiente virtual ativo
• Solução: Após ativar o ambiente virtual, execute: pip install -U langchain langchain-openai langgraph

Problema: Autenticação bem-sucedida, mas requisição ao modelo falha

• Causa: Modelo selecionado não disponível, com erro de digitação ou não suportado na requisição atual
• Solução: Teste inicialmente com model="auto". Para fixar o modelo, copie um ID válido do Gate.AI.

Problema: Fluxo do LangGraph retorna estado incompleto

• Causa: Nó não retornou a chave esperada ou a estrutura do grafo está incorreta
• Solução: Confirme que cada nó retorna um dicionário com as chaves corretas e que o grafo possui START, as arestas corretas e END.

Próximos passos: o que mais pode ser configurado ou construído?

• Integração via API do desenvolvedor do Gate.AI para conectar fluxos locais a toda a API do Gate.AI
• Para integração em editores de código AI, consulte o guia de integração do Gate.AI Cursor
• Para fluxos envolvendo Claude Code ou configurações compatíveis com Anthropic, consulte o guia de integração do Gate.AI Claude Code