Gerencie modelos e ferramentas no nível do AI Gateway (prévia)

APLICA-SE A: camada do AI Gateway (prévia)

Use a camada AI Gateway (versão prévia) para gerenciar os modelos e as ferramentas que os aplicativos e agentes invocam. Importar modelos para disponibilizar um endpoint governado para solicitações ao modelo. Adicione servidores MCP para expor ferramentas aprovadas por meio de um endpoint governado do Model Context Protocol (MCP). Aplicações e agentes autenticam o gateway com chaves de acesso em tempo de execução. O gateway usa a autenticação de backend que você configura para cada provedor de modelo ou backend de ferramenta.

Pré-requisitos

• Uma instância do nível Gateway de IA.
• Permissão para gerenciar a instância de tier do AI Gateway.
• Acesso ao modelo de provedor ou backend que você pretende adicionar.
• Para a autenticação de back-end com identidade gerenciada, permissão para atribuir a função necessária ao recurso de back-end.

Importar modelos

Use o assistente Add models para conectar a camada AI Gateway ao Microsoft Foundry, Azure OpenAI, AWS Bedrock, Google Vertex, OpenAI, Anthropic ou endpoints personalizados. O gateway atende cada modelo nos endpoints que seu backend suporta, sob o prefixo https://<gateway>.azure-api.net/default/models. O próximo segmento de caminho é o formato da API do provedor. Por exemplo, modelos compatíveis com OpenAI são servidos em .../default/models/openai/v1 (como /chat/completions e /responses), e modelos Anthropic em .../default/models/anthropic/v1/messages. Os campos de conexão que o assistente solicita variam conforme o provedor.

Escolha Importar do Foundry quando seu modelo for executado em um recurso do Microsoft Foundry, que inclui implantações do Azure OpenAI e do Azure AI Services — o assistente detecta automaticamente as implantações do recurso. Escolha Adicionar um modelo personalizado para AWS Bedrock, Google Vertex, OpenAI, Anthropic ou qualquer outro endpoint suportado, onde você mesmo digita os nomes do endpoint e dos modelos.

Use identidade gerenciada quando o provedor suporta autenticação backend do Microsoft Entra ID, como o Microsoft Foundry. Atribua à identidade do gateway a função necessária no recurso de back-end antes de importar. Caso contrário, forneça a chave API ou o segredo do provedor durante a importação. O gateway armazena e protege a credencial.

Os chamadores referenciam o modelo pelo nome do modelo no model campo:

{
  "model": "gpt-5.6-sol",
  "messages": [
    {
      "role": "user",
      "content": "Summarize the incident report."
    }
  ]
}

O model valor é o nome do modelo dado pelo modelo importado.

Para adicionar modelos, abra a página Modelos e selecione Adicionar modelos. Escolha como você quer se conectar.

Importação do Microsoft Foundry

1. Selecione Importar do Foundry.
2. Em Selecionar recurso, escolha a assinatura e o recurso Foundry. O assistente lista as implantações de modelos nesse recurso.
3. Nos dados do Provedor, insira um nome do provedor e um nome de exibição, adicione uma descrição opcional e escolha o método de autenticação - Identidade gerenciada (recomendada, quando disponível) ou Baseada em chave.
4. Selecione Criar. O gateway importa as implantações do recurso como modelos que os clientes solicitam por nome.

Adicionar um modelo personalizado

1. Selecione Adicionar um modelo personalizado.
2. No Provedor, insira um nome de exibição e o nome do provedor, além de uma descrição opcional.
3. No Endpoint, insira a URL base do endpoint, o nome do cabeçalho de autenticação (por exemplo, Authorization) e a chave da API.
4. Em Models, insira o nome de cada modelo e selecione seus endpoints suportados - conclusão de chat OpenAI, respostas OpenAI, mensagens Anthropic ou Other. Selecione Adicionar modelo para cada modelo que você definir.
5. Selecione Criar.

Não existe uma etapa separada de validação. O gateway configura a conexão quando você cria o provedor. Depois de adicionar um modelo, você pode atualizar sua autenticação ou políticas, ou removê-lo quando não for mais necessário.

Após a adição do modelo, envie uma solicitação de teste pelo endpoint do gateway:

curl "https://<gateway>.azure-api.net/default/models/openai/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "api-key: <runtime-access-key>" \
  -d '{
    "model": "gpt-5.6-sol",
    "messages": [
      { "role": "user", "content": "Write a one-sentence status update." }
    ]
  }'

Se você ainda não criou uma chave de acesso em tempo de execução, crie uma a partir da página de Chaves . As inscrições não precisam de credenciais diretas de provedor. Use as visualizações de monitoramento para analisar o volume de solicitações, a latência, o uso de tokens e os erros por modelo.

Encaminhamento direto da API de Messages da Anthropic

Diferentes provedores expõem formatos de API diferentes, e o gateway atende cada um em seu próprio caminho sob /default/models. Modelos Anthropic utilizam a API Anthropic Messages em modo passthrough: o gateway preserva o formato nativo de solicitação e resposta do Anthropic Messages e encaminha chamadas para Anthropic em /default/models/anthropic/v1/messages. Use-o quando as aplicações já utilizam o Anthropic SDK ou /v1/messages.

Para adicionar um modelo Anthropic, use Adicionar modelos>Adicionar um modelo personalizado:

1. No Provider, insira um nome de exibição e o nome do provider para Anthropic.
2. Em Endpoint, defina a URL base do endpoint como https://api.anthropic.com, defina o nome do cabeçalho de autenticação como x-api-key e insira a chave de API da Anthropic. O gateway armazena a chave e a injeta nas chamadas do backend.
3. Em Models, insira o nome do modelo da Anthropic que os chamadores enviam (como claude-fable-5) e selecione o endpoint Mensagens da Anthropic.
4. Selecione Criar. O gateway oferece passthrough do Anthropic Messages em /default/models/anthropic/v1/messages.

Os clientes acessam o caminho do gateway. O gateway armazena a credencial, injeta o backend x-api-key e encaminha o cabeçalho anthropic-version do chamador para Anthropic.

curl -X POST "https://<gateway>.azure-api.net/default/models/anthropic/v1/messages" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -H "api-key: <runtime-access-key>" \
  -d '{"model":"claude-fable-5","max_tokens":256,"messages":[{"role":"user","content":"Write a product description for a trail running backpack."}]}'

O SDK Python da Anthropic funciona quando você aponta base_url para o caminho do gateway. Por padrão, o SDK padrão envia a credencial no cabeçalho x-api-key, então passe a chave de acesso em tempo de execução do gateway no cabeçalho api-key ao usar default_headers. O valor api_key="unused" serve apenas para atender ao argumento obrigatório do SDK; o gateway o ignora e injeta a chave Anthropic de backend armazenada. Defina model como o nome do modelo da Anthropic.

from anthropic import Anthropic

client = Anthropic(api_key="unused", base_url="https://<gateway>.azure-api.net/default/models/anthropic", default_headers={"api-key": "<runtime-access-key>"})
message = client.messages.create(model="claude-fable-5", max_tokens=256, messages=[{"role":"user","content":"Hello"}])
print(message.content[0].text)

Valide os timeouts e o tratamento das respostas antes da implantação em produção, especialmente se as políticas inspecionarem os corpos das mensagens.

Adicionar um servidor de MCP

O nível AI Gateway permite que as equipes de plataforma publiquem servidores MCP por trás de um único endpoint MCP gerenciado. O fluxo de trabalho de configuração é: criar um servidor MCP, anexar um ou mais backends e expor capacidades selecionadas do backend como ferramentas. Um único servidor MCP pode combinar três tipos de backends: servidores MCP remotos (por URL), ferramentas geradas a partir de uma especificação OpenAPI e conectores embutidos para aplicativos SaaS comuns (mais de 1.000 integrações pré-construídas, sem servidor para hospedar).

Use servidores MCP quando os agentes precisarem chamar sistemas de negócios, ferramentas para desenvolvedores, repositórios de conhecimento ou APIs internas. Agentes autenticam uma vez no gateway e não precisam de credenciais separadas para cada backend. Para cada backend, você escolhe como o gateway autentica nele: Nenhum, Chave de API, OAuth 2.0 ou Identidade Gerenciada.

Um único servidor MCP federa um ou mais backends. Cada backend fornece ferramentas, e o gateway aplica um namespace às ferramentas de cada backend usando o nome do backend, para que ferramentas com nomes idênticos de backends diferentes não entrem em conflito. Por exemplo, uma create_issue ferramenta de um backend chamado github é exposta a agentes sob o github namespace, diferente de uma create_issue ferramenta em outro backend.

Cada fonte contribui com ferramentas de forma diferente:

• Servidor MCP — federa as ferramentas a partir de um endpoint MCP remoto que você já hospeda.
• Especificação OpenAPI — transforma as operações de API selecionadas em ferramentas; O resumo ou descrição da operação torna-se a descrição da ferramenta.
• Conector embutido — utiliza uma conexão gerenciada com um aplicativo SaaS, como Office 365, SharePoint, GitHub ou Salesforce. Conectores OAuth solicitam consentimento quando você configura a conexão.

Para criar um servidor MCP:

1. No portal de níveis do AI Gateway, selecione servidores MCP.
2. Selecione Adicionar servidor MCP.
3. No Source, escolha um tipo de backend para começar: servidor MCP, especificação OpenAPI ou conector embutido. Você pode adicionar mais servidores de backend posteriormente.
4. Dê um nome único ao backend. O gateway prefixa as ferramentas desse backend com o nome no servidor MCP combinado.
5. Configure o backend e escolha como o gateway autentica nele: Nenhum, Chave de API, OAuth 2.0 ou Identidade Gerenciada. Em API Key, insira o nome e o valor do cabeçalho; os valores são criptografados em repouso.
6. Para federar mais serviços atrás do mesmo endpoint, adicione outro backend e repita.
7. Selecione Confirmar e depois Criar.

Não há uma etapa separada de teste de conectividade. O gateway configura e verifica cada backend quando você cria o servidor.

O gateway cria um único endpoint MCP que federa todos os backends selecionados. Os clientes fazem chamadas ao endpoint governado e se autenticam com uma chave de acesso de tempo de execução.

Os agentes ligam para o servidor MCP em:

https://<gateway>.azure-api.net/default/toolservers/<server-name>/mcp

Envie a chave de acesso de runtime no cabeçalho api-key. Aponte qualquer framework de cliente ou agente compatível com MCP para essa URL. Por exemplo, liste as ferramentas disponíveis com um pedido JSON-RPC tools/list :

curl "https://<gateway>.azure-api.net/default/toolservers/<server-name>/mcp" \
  -H "Content-Type: application/json" \
  -H "api-key: <runtime-access-key>" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }'

import requests

url = "https://<gateway>.azure-api.net/default/toolservers/<server-name>/mcp"
response = requests.post(
    url,
    headers={"api-key": "<runtime-access-key>", "Content-Type": "application/json"},
    json={"jsonrpc": "2.0", "id": 1, "method": "tools/list"},
)
print(response.json())

Se um sistema tiver uma API REST, mas não um servidor MCP, importe a descrição da OpenAPI dele. Selecione operações para expor como ferramentas, edite nomes e descrições de ferramentas, configure um método de autenticação backend suportado e crie o ativo MCP. O gateway mapeia chamadas de ferramenta para operações REST.

Use o gateway para servidores MCP para centralizar:

• Discovery — forneça um catálogo de servidores MCP aprovados para desenvolvedores e agentes.
• Autenticação — os clientes se autenticam no gateway. O gateway armazena as credenciais do backend, portanto a configuração do cliente não inclui segredos do serviço upstream.
• Exposição de ferramentas — escolha quais operações do backend cada servidor publica como ferramentas. Na pré-visualização, toda chave de acesso de tempo de execução pode acessar todos os recursos publicados no gateway.
• Observabilidade — o gateway emite métricas de uso de tokens OpenTelemetry (OTLP) para tráfego de modelos, que você pode enviar para o Application Insights ou outro destino OTLP. O monitoramento de tráfego da ferramenta MCP (volume de requisições, latência e erros) está disponível no portal quando você usa o Application Insights; A exportação do OpenTelemetry (OTLP) para tráfego da ferramenta MCP ainda não está disponível.
• Governança — aplique as mesmas políticas ao tráfego MCP que você usa para modelos, como limites de taxa e segurança de conteúdo.

Depois de criar o servidor, configure o acesso em tempo de execução antes de compartilhá-lo. Adicione políticas como segurança de conteúdo, filtros de IP e limites de taxa de tokens e solicitações, direcionadas ao gateway ou a ativos publicados específicos.

Conteúdo relacionado

• Visão geral dos níveis do AI Gateway
• Início Rápido: Crie uma instância de nível de AI Gateway
• Governar, proteger e operar a camada do Gateway de IA
• Configurar rede privada