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

O Gate.AI fornece endpoints de API compatíveis com 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, faturamento ou políticas de acesso empresarial.

Pré-requisitos

• Conta no Gate.AI com chave de API criada
• Python 3.10 ou superior, com permissão para instalar dependências

Fonte do conteúdo: documentação oficial do Gate.AI e materiais de produto, 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 roteamento de modelos com model="auto"
• Substituir por um 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 do desenvolvedor do Gate.AI.

Passo 1: Instalar dependências Python

Este passo instala as integrações necessárias 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 langchain_openai e langgraph normalmente.

Passo 2: Armazenar a chave API do Gate.AI

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

• Em ambiente 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.

Nunca envie sua chave API real para o Git. Para projetos de equipe, recomenda-se usar gerenciadores de chaves, configurações de CI 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 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 adicione /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 requisições para o modelo adequado com base na tarefa, regras de roteamento ou configuração.

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

Passo 4: Construir um prompt 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 der erro antes de retornar o texto, verifique a chave API, URL base e configuração do modelo, antes de modificar a estrutura da cadeia.

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 uma revisão em outro, 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 a 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 por 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, use inicialmente model="auto"

• Para resultados reproduzí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 IDs, pois a disponibilidade depende da sua conta, do produto e das regras do provedor de modelos (até junho de 2026).

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

| Parâmetro | Exemplo | Cenário de uso | Importância | | ------------------ | ---------------------------------------------------- | ------------------------------| -------------------------------------------------------- | | Variável da API | GATEAI_API_KEY | Shell e código Python | Garante que a credencial não esteja no código fonte | | URL base | | ChatOpenAI(base_url=...) | Direciona 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: Requisição retorna 401, invalid_api_key ou erro de autenticação

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

Problema: Requisição retorna 404, falha na conexão 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 lança ModuleNotFoundError

• Causa: Virtual environment sem langchain-openai ou langgraph instalado
• Solução: Ative o ambiente virtual e execute pip install -U langchain langchain-openai langgraph

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

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

Problema: Fluxo do LangGraph não retorna estado completo

• Causa: Nó não retornou a chave esperada ou falta aresta no grafo
• Solução: Confirme que cada nó retorna um dicionário com as chaves corretas e que o grafo inclui START, as arestas entre nós 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 plataforma 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