Guia do LangSmith Tool Gateway: credenciais, tool kits, políticas e aprovações para chamadas de ferramentas
O LangSmith Tool Gateway entrou em beta pública em 19 de novembro de 2026. Ele reúne em uma única camada gerenciada as credenciais, a identidade e o acesso das chamadas de ferramentas feitas por agentes. Este guia usa um modelo See / Act As / Allow para mostrar como registrar servidores MCP, montar kits de ferramentas, escolher entre identidade por usuário e service key e adicionar políticas de bloqueio e de aprovação. Também aborda os limites documentados e os pontos em que esses controles deixam de proteger você.
O que é o LangSmith Tool Gateway e por que ele existe
Na descrição da própria LangChain, o LangSmith Tool Gateway é uma camada gerenciada de ferramentas que cuida das credenciais, da identidade e do acesso de cada chamada de ferramenta feita por um agente. Ele fica entre os seus agentes e os servidores MCP que eles chamam. Com isso, cada agente deixa de ter que resolver essas questões sozinho.
A LangChain lançou o Tool Gateway em beta pública em 19 de novembro de 2026, conforme noticiou o Unite.AI. A beta está disponível nos planos LangSmith Plus e Enterprise. No LangSmith Cloud, ela abrange as regiões GCP US, GCP EU, GCP APAC e AWS US, com exceção da Azure US.
Pense no grande varejista americano que a LangChain descreve no seu post de lançamento: a equipe de engenharia dele construiu mais de 50 servidores MCP que expõem mais de mil ferramentas. Cada agente deveria acessar apenas uma fatia pequena e aprovada desse catálogo, com credenciais adequadas ao seu contexto. É esse tipo de dispersão, com ferramentas e credenciais espalhadas por muitos servidores e agentes, que o gateway pretende colocar sob um único conjunto de controles.
Uma observação antes dos detalhes. Produtos em beta mudam, e vários detalhes de implementação importam para que o código funcione: nomes de campos de resposta, opções de configuração, formatos de endpoint, cabeçalhos de autenticação, requisitos de transporte e a cobertura de cada recurso por plano. Os exemplos abaixo usam marcadores para esses itens. Confirme cada um na documentação atual e em respostas reais durante os testes, e copie os valores exatamente, sem tentar adivinhar.
O modelo de governança See / Act As / Allow
Excessive Agency (agência excessiva), na definição usada pelo OWASP Gen AI Security Project, é a vulnerabilidade que permite a um LLM executar ações danosas em resposta a saídas inesperadas, ambíguas ou manipuladas. Suas três causas mais comuns são funcionalidade excessiva, permissões excessivas e autonomia excessiva.
Associamos cada uma dessas causas a um dos controles do gateway e chamamos o resultado de See / Act As / Allow:
- See (funcionalidade excessiva): quais ferramentas este agente enxerga? Kits de ferramentas.
- Act As (permissões excessivas): as credenciais de quem uma chamada carrega? Configurações de identidade.
- Allow (autonomia excessiva): esta chamada específica deve ser executada? Políticas de bloqueio e de aprovação.
As camadas não compensam umas às outras. Um agente de reembolsos com um kit de duas ferramentas continua carregando tudo o que a sua credencial permite. Se essa credencial for a service key do backend e nenhuma política bloquear uma ferramenta destrutiva, o kit pequeno reduziu o cardápio sem reduzir o risco.
Como uma chamada de ferramenta passa pelo gateway
Uma chamada de ferramenta envolve três etapas de autenticação separadas, detalhadas por completo na página How Tool Gateway works. Para fins de design, duas delas são as mais importantes. Quem faz a chamada se autentica apenas no LangSmith. Em seguida, o Tool Gateway escolhe uma credencial armazenada e a usa para se autenticar no servidor MCP. Como resultado, quem chama nunca tem acesso ao token ou à chave de API do servidor. É o mesmo padrão de um proxy de credenciais que mantém as chaves de API fora dos agentes de IA: o agente pede, o proxy guarda o segredo.
O design está alinhado às orientações de autorização da especificação MCP. Quando um servidor MCP chama APIs upstream, ele usa um token separado, emitido pelo servidor de autorização upstream, e não deve repassar o token que recebeu do cliente MCP. Os servidores de autorização também devem emitir tokens de acesso de curta duração para reduzir o impacto de vazamentos.
Quando um usuário ainda não conectou uma conta
Se uma chamada precisa da credencial de um usuário e esse usuário ainda não conectou a conta, a chamada retorna um link de login. Um cliente compatível com URL elicitation do MCP mostra o link ao usuário. Os demais clientes recebem uma resposta HTTP 428 com o link. Depois que o usuário se conecta, as chamadas seguintes usam a credencial armazenada.
Sugerimos que o seu cliente trate essa resposta como uma etapa de login esperada, e não como um erro. Mostre o link, aguarde o usuário e tente novamente uma única vez:
resp = call_tool(req)
if resp.status == 428:
link = sign_in_link_from(resp.body) # placeholder field name
show_sign_in(link)
await user_confirms_sign_in()
resp = call_tool(req) # retry once, never loopO que o gateway não faz com as respostas
A resposta de cada servidor chega a quem chamou sem alterações. A recomendação da LangChain é tratar a saída das ferramentas como entrada não confiável para o seu agente. O gateway não é um filtro de conteúdo. Defesas como a separação entre instruções e dados contra prompt injection continuam sendo responsabilidade sua e fazem parte do design do agente.
Passo a passo da configuração: servidores, kits, modo de busca e uma primeira requisição
Telas e caminhos de API podem mudar durante a beta. Por isso, estes passos seguem os conceitos documentados, e não cliques.
- Registre cada servidor MCP. Adicione o servidor para que o gateway, e não o seu agente, se autentique nele, e consulte a documentação de identidade antes de decidir as credenciais de quem as chamadas devem carregar.
- Crie um kit por função de agente. Escolha ferramentas dos servidores registrados, dê ao kit o nome da função que ele atende e mantenha-o pequeno. A documentação de tool kits explica como criar e atualizar kits.
- Use o modo de busca em catálogos grandes. Se uma função realmente precisa de muitas ferramentas, o modo de busca evita carregar todas de uma vez.
- Envie uma primeira requisição a partir do seu backend. Um chamador de backend envia a service key junto com um cabeçalho X-LangSmith-Identity que indica o usuário em nome de quem a chamada é feita:
POST <your kit's MCP endpoint, as shown in LangSmith>
<auth header carrying the service key>
X-LangSmith-Identity: <user this call acts for>
<standard MCP tool call payload>As linhas de endpoint e de autenticação são marcadores, como indicado na observação do início. Use os valores exatos do LangSmith e da documentação atual.
See: montando kits de ferramentas curados sem confundi-los com segurança
Um kit é um conjunto curado de ferramentas retiradas dos servidores registrados no gateway. O objetivo é o foco: um agente que cuida de reembolsos não tem motivo para enxergar uma ferramenta de calendário ou de deploy. Kits menores também melhoram a qualidade, porque a LangChain observa que, quando um agente tem centenas ou milhares de ferramentas, carregar todas de uma vez aumenta a latência e dificulta a escolha da ferramenta certa. São permitidas até 10.000 ferramentas por kit, mas trate esse número como um teto, não como uma meta.
Kits não são controle de acesso
O mesmo chamador que usa um kit também pode usar kits/me/mcp, que disponibiliza todas as ferramentas que esse chamador pode usar. Por isso, a documentação da LangChain afirma claramente que um kit não é um controle de acesso. Tirar uma ferramenta de um kit não impede uma chamada que a identidade do agente tem permissão para fazer. A aplicação das regras precisa ficar em Act As e Allow.
Mantenha os kits atualizados
O Tool Gateway mantém em cache a lista de ferramentas de cada servidor por duas horas, segundo a documentação de tool kits. Inclua a atualização dos kits em cada release de servidor MCP, ou aceite que os agentes podem ver uma lista de ferramentas com até duas horas de atraso após uma mudança. Isso pesa mais quando um release remove uma ferramenta que você não quer mais que os agentes alcancem.
Act As: escolhendo a identidade para usuários e agentes autônomos
A identidade define as permissões de quem uma chamada de ferramenta carrega. No nosso mapeamento See / Act As / Allow, esta é a camada que trata as permissões excessivas. Antes de escolher um padrão, sugerimos ler a documentação de identidade junto com as duas abordagens abaixo.
Credenciais por usuário
Cada usuário conecta a própria conta pelo fluxo de login descrito acima. Isso funciona bem para assistentes que agem em nome de uma pessoa, já que o agente só pode fazer o que essa pessoa já pode fazer no sistema upstream.
Service key com o cabeçalho X-LangSmith-Identity
Sistemas de backend usam uma service key junto com um cabeçalho X-LangSmith-Identity. O Tool Gateway confia no valor desse cabeçalho exatamente como foi enviado. Portanto, qualquer chamador que tenha a service key pode agir como qualquer usuário. Envie o cabeçalho apenas a partir de um backend que você controla e nunca exponha a service key a um navegador ou a um usuário final; essa é a orientação da própria LangChain. Trate essa chave como uma credencial root.
A comparação abaixo é uma avaliação nossa, não documentação da LangChain.
| Pergunta | Credenciais por usuário | Service key em um backend |
|---|---|---|
| Em nome de quem a chamada age | Uma pessoa que conectou a própria conta | Qualquer identidade que o seu backend envie no cabeçalho |
| Uso típico | Assistentes interativos e copilotos | Serviços de backend e agentes sem supervisão ou agendados |
| Principal risco | Contas conectadas com direitos mais amplos do que a tarefa exige | Uma chave vazada permite se passar por qualquer usuário |
| Políticas de aprovação | Viáveis, porque a pessoa está presente para confirmar | Só são úteis se houver uma pessoa presente; caso contrário, use políticas de bloqueio |
Nossa regra prática: use credenciais por usuário quando houver uma pessoa presente e a ação for dela, e a service key, enviada apenas a partir de um backend que você controla, quando um job roda sem supervisão ou age em nome do sistema.
Allow: escrevendo políticas de bloqueio e de aprovação que realmente funcionam
As políticas são a camada de aplicação das regras, e dois comportamentos padrão descritos na documentação de políticas determinam todo o resto. Uma chamada que não corresponde a nenhuma política é executada. Se uma chamada corresponde a uma política de bloqueio e a uma de aprovação ao mesmo tempo, ela é bloqueada. O primeiro padrão é o que pega as pessoas de surpresa: uma ferramenta para a qual ninguém escreveu uma política é uma ferramenta que todo chamador autorizado pode usar.
Quem realmente aprova
Em uma política de aprovação, quem aprova a chamada é o próprio chamador, e não um revisor separado. Cada chamada é confirmada antes de ser executada, mas nada é encaminhado a um administrador. Um agente rodando sem ninguém presente não consegue aprovar chamadas. Para esse caso, a LangChain recomenda uma política de bloqueio que impeça o agente de chamar a ferramenta.
O controle com humano no circuito (human-in-the-loop), em que uma pessoa aprova ações de alto impacto antes que aconteçam, está entre as mitigações recomendadas pelo OWASP. A aprovação pelo chamador faz sentido quando um usuário deixa um assistente enviar um e-mail da própria conta. Ela não serve para ações que exigem um segundo par de olhos, como um reembolso acima de um limite definido pela sua equipe financeira. Nesses casos, bloqueie a ferramenta no gateway ou crie uma etapa de aprovação prévia na sua própria aplicação.
Capacidade
Uma organização pode ter até 1.000 políticas que se aplicam a todos os workspaces, mais até 100 políticas por workspace. Criar uma política além de qualquer um desses limites retorna um erro 422. Coloque regras como o bloqueio de ferramentas irreversíveis para agentes sem supervisão no nível da organização, e regras específicas de cada equipe nos workspaces. Se você gera políticas automaticamente, trate o 422 para que o script falhe de forma visível, em vez de deixar uma regra sem ser criada.
Um playbook de rollout: de segredos espalhados a um único gateway governado
Execute estes passos do menor para o maior risco.
- Inventário. Liste todos os servidores MCP e ferramentas que os seus agentes usam e classifique cada um por impacto: leitura, escrita, irreversível ou voltado para o exterior.
- Registre os servidores. Transfira as credenciais upstream para o gateway e depois confirme que nenhuma configuração de agente ainda guarda uma chave upstream.
- See. Monte um kit por função de agente, com o menor conjunto útil de ferramentas.
- Act As. Credenciais por usuário para assistentes que agem em nome de pessoas; a service key, apenas a partir de um backend, para jobs autônomos.
- Allow. Primeiro as políticas de bloqueio, para agentes sem supervisão e ferramentas irreversíveis; depois as políticas de aprovação, para chamadas interativas sensíveis.
- Confirme que os traces estão chegando. Verifique o projeto de tracing tool-gateway e a aba Usage após as primeiras chamadas de teste.
- Teste de carga. Teste contra os limites documentados (veja Ressalvas abaixo) com tráfego realista.
Checklist antes da produção
- [ ] Nenhuma chave ou token upstream permanece no código dos agentes, nos prompts ou na configuração dos clientes
- [ ] Nenhum agente sem supervisão depende de uma política de aprovação
- [ ] Os clientes tratam respostas de login HTTP 428 sem entrar em loop
- [ ] Os agentes tratam a saída das ferramentas como entrada não confiável
- [ ] A atualização dos kits faz parte do processo de release dos servidores MCP
Observabilidade: o que os traces e a aba Usage registram
Os traces de chamadas de ferramentas registram a ferramenta, o servidor, o usuário, o resultado e a duração de cada chamada. Os dados enviados à ferramenta ou retornados por ela não são armazenados. Payloads sensíveis ficam fora do registro, assim como os detalhes que você talvez queira mais tarde em uma investigação. Os traces vão para um projeto de tracing chamado tool-gateway, que o gateway cria ao registrar a primeira chamada, como explica a documentação de traces. Os traces do workspace são gratuitos e não contam para os seus limites de traces. O custo não é motivo para dispensá-los. Para verificações mais rápidas, a aba Usage lista as 100 chamadas de ferramentas mais recentes dos últimos 7 dias, com a ferramenta, o servidor, o resultado, a latência e o horário de início de cada uma. Essa visão serve para acompanhar o rollout ao vivo, não para auditoria de longo prazo.
Se o seu processo de compliance ou de resposta a incidentes exige análise forense no nível do payload, esse registro precisa ficar na camada do agente ou da aplicação, por exemplo junto com o tracing GenAI do OpenTelemetry para agentes.
Ressalvas, limites da beta e quando segredos por agente ainda bastam
Os limites rígidos listados na documentação do Tool Gateway da LangChain, a começar pela visão geral How Tool Gateway works, são: 1 MB de tamanho de requisição, 8 MB de tamanho de resposta, 60 segundos para o servidor MCP começar a responder e 100 requisições por segundo, com picos de até 1.000. As ferramentas que retornam documentos grandes ou dependem de sistemas upstream lentos são as primeiras que devem passar por teste de carga.
Durante a beta, o acesso fica restrito aos planos Plus e Enterprise e às quatro regiões de nuvem listadas. O comportamento da beta pode mudar, e este guia reflete a documentação disponível no lançamento. Sugerimos resolver os detalhes de implementação indicados no início, como requisitos de transporte e a cobertura dos recursos de governança por plano, antes de planejar uma migração.
Quando um gateway compensa
Um gateway compensa quando você tem muitos servidores MCP e muitos agentes, quando cada usuário precisa de acesso delegado ou quando uma equipe de segurança quer um único lugar para definir e revisar políticas.
Quando segredos por agente podem bastar
Nem toda equipe precisa disso. Se você roda um único agente com poucas ferramentas, um único responsável e nenhum acesso delegado por usuários, um gateway central pode acrescentar mais processo do que proteção.
Pontos principais
- O LangSmith Tool Gateway entrou em beta pública em 19 de novembro de 2026, nos planos Plus e Enterprise, nas regiões GCP US, GCP EU, GCP APAC e AWS US. A Azure US fica de fora.
- O modelo See / Act As / Allow associa as causas de Excessive Agency do OWASP a kits, identidade e políticas. Cada camada tem seus próprios limites.
- Quem chama se autentica apenas no LangSmith e nunca tem acesso aos tokens ou chaves de API dos servidores MCP upstream, em linha com a proibição de repasse de tokens da especificação MCP.
- Os kits de ferramentas definem o que um agente enxerga, mas não são controle de acesso, porque o chamador ainda pode acessar kits/me/mcp e todas as ferramentas que sua identidade permite.
- Com o cabeçalho X-LangSmith-Identity, qualquer pessoa que tenha a service key pode agir como qualquer usuário. Mantenha essa chave em um backend que você controla.
- Por padrão, as políticas permitem as chamadas, o bloqueio prevalece sobre a aprovação e quem aprova é o próprio chamador. Agentes sem supervisão precisam de políticas de bloqueio.
- Os traces não guardam payloads e a saída das ferramentas passa sem alterações. Planeje em torno dos limites de 1 MB por requisição, 8 MB por resposta, 60 segundos e 100 requisições por segundo.
Conclusão
Comece pelo inventário. Classifique cada ferramenta MCP usada pelos seus agentes como leitura, escrita, irreversível ou voltada para o exterior, e escreva políticas de bloqueio para as irreversíveis e as voltadas para o exterior antes de colocar qualquer agente atrás do gateway. Em seguida, leve uma única função de agente do início ao fim, com seu próprio kit pequeno e o modo de identidade que corresponde a quem realmente está presente. Amplie o rollout somente depois que as chamadas dessa função aparecerem no projeto de tracing tool-gateway e os testes de carga ficarem dentro dos limites documentados.
A exceção é a equipe pequena. Se você roda um único agente com poucas ferramentas e um único responsável, um segredo no servidor com escopo restrito e tokens de curta duração ainda pode ser a opção mais simples. O gateway pode esperar até a chegada de um segundo agente ou de acesso delegado por usuários.
Perguntas frequentes
O LangSmith Tool Gateway já está disponível de forma geral, e quais planos e regiões ele atende?
Ainda não. Ele foi lançado em beta pública em 19 de novembro de 2026. A beta está disponível nos planos LangSmith Plus e Enterprise e, no LangSmith Cloud, abrange GCP US, GCP EU, GCP APAC e AWS US. A Azure US fica de fora. Consulte a documentação atual antes de se comprometer, já que o escopo da beta pode mudar.
Os kits de ferramentas impedem um agente de chamar ferramentas fora do kit?
Não. A documentação da LangChain afirma que um kit não é um controle de acesso, porque o mesmo chamador pode usar kits/me/mcp, que disponibiliza todas as ferramentas que esse chamador pode usar. Os kits definem o que o agente enxerga. Para restringir o que ele pode realmente fazer, conte com o escopo de identidade e com políticas de bloqueio.
O que o meu cliente deve fazer ao receber um HTTP 428?
Trate a resposta como uma etapa de login. A resposta 428 traz um link de login para um usuário que ainda não conectou a conta. Mostre o link, aguarde o usuário confirmar o login e então repita a chamada original uma única vez. Para descobrir qual campo contém o link, consulte a documentação atual ou inspecione uma resposta real durante os testes.
Quem aprova uma chamada em uma política de aprovação, e o que devo fazer com agentes sem supervisão?
Quem aprova a chamada é o próprio chamador. Não há um revisor separado nem uma fila de administrador. Um agente rodando sem ninguém presente não consegue aprovar chamadas, por isso a LangChain recomenda políticas de bloqueio para impedir que esses agentes usem uma ferramenta. Se você precisa que uma segunda pessoa revise ações de alto impacto, crie essa etapa na sua própria aplicação ou bloqueie a ferramenta.
O Tool Gateway armazena as entradas e saídas das chamadas de ferramentas?
Não. Os traces de chamadas de ferramentas registram a ferramenta, o servidor, o usuário, o resultado e a duração de cada chamada, mas os dados enviados à ferramenta ou retornados por ela não são armazenados. Se você precisa de registros no nível do payload para compliance ou análise forense, planeje esse registro na camada da sua própria aplicação.
O gateway higieniza as respostas das ferramentas contra prompt injection?
Não. O Tool Gateway repassa a resposta de cada servidor ao chamador sem alterações, e a documentação recomenda tratar a saída das ferramentas como entrada não confiável para o seu agente. As defesas contra prompt injection continuam fazendo parte do design do agente.
Quais são os limites documentados de tamanho, tempo limite e taxa?
Os limites rígidos documentados são 1 MB de tamanho de requisição, 8 MB de tamanho de resposta, 60 segundos para o servidor MCP começar a responder e 100 requisições por segundo, com picos de até 1.000. Faça testes de carga com as ferramentas que retornam documentos grandes ou dependem de sistemas upstream lentos antes de ir para produção.
Fontes
- https://www.langchain.com/blog/langsmith-tool-gateway
- https://docs.langchain.com/langsmith/tool-gateway-how-it-works
- https://docs.langchain.com/langsmith/tool-gateway-quickstart
- https://docs.langchain.com/langsmith/tool-gateway-tool-kits
- https://docs.langchain.com/langsmith/tool-gateway-identity
- https://docs.langchain.com/langsmith/tool-gateway-policies
- https://docs.langchain.com/langsmith/tool-gateway-traces
- https://www.unite.ai/langchain-launches-langsmith-tool-gateway-to-govern-agent-tool-calls/
- https://superpowerdaily.com/posts/langchain-launches-a-gateway-to-control-which-tools-ai-agents-can-use
- https://modelcontextprotocol.io/specification/2025-03-26/basic/transports
- https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization/security-considerations
- https://genai.owasp.org/llmrisk/llm062025-excessive-agency/



