Gerir modelos e ferramentas no nível do AI Gateway (pré-visualização)

APLICA-SE A: escalão do AI Gateway (pré-visualização)

Utilize o escalão AI Gateway (pré-visualização) para gerir os modelos e as ferramentas que as aplicações e os agentes invocam. Importar modelos para fornecer um endpoint governado para pedidos de modelo. Adicione servidores MCP para expor ferramentas aprovadas por meio de um endpoint do Model Context Protocol (MCP) com governação. As aplicações e os agentes autenticam-se junto do gateway com chaves de acesso em tempo de execução. O gateway usa a autenticação de backend que configurar para cada fornecedor de modelos ou backend da ferramenta.

Pré-requisitos

• Uma instância do escalão AI Gateway.
• Permissão para gerir a instância de nível do AI Gateway.
• Acesso ao modelo de prestador ou backend que planeia adicionar.
• Para autenticação de back-end com identidade gerida, permissão para atribuir a função necessária ao recurso de back-end.

Importar modelos

Use o assistente Adicionar modelos para ligar o nível AI Gateway ao Microsoft Foundry, Azure OpenAI, AWS Bedrock, Google Vertex, OpenAI, Anthropic ou endpoints personalizados. O gateway disponibiliza cada modelo nos endpoints suportados pelo seu backend, com o prefixo https://<gateway>.azure-api.net/default/models. O segmento seguinte do caminho é o formato da API do fornecedor. 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 ligação que o assistente requer variam consoante o fornecedor.

Escolha Importar do Foundry quando o seu modelo é executado num recurso do Microsoft Foundry, que inclui implementações do Azure OpenAI e do Azure AI Services — o assistente deteta automaticamente as implementações do recurso. Escolha Adicionar um modelo personalizado para AWS Bedrock, Google Vertex, OpenAI, Anthropic ou qualquer outro endpoint suportado, onde introduz os nomes do endpoint e dos modelos.

Use identidade gerida quando o fornecedor suporta a 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 da importação. Caso contrário, forneça a chave API ou o segredo do fornecedor durante a importação. O gateway armazena e protege a credencial.

Os chamadores referem-se ao 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 de Modelos e selecione Adicionar modelos. Escolhe como queres ligar-te.

Importação do Microsoft Foundry

1. Selecione Importar do Foundry.
2. Em Selecionar recurso, escolha a subscrição e o recurso Foundry. O assistente lista as implementações de modelos nesse recurso.
3. Nos detalhes do Fornecedor, introduza um nome do fornecedor e um nome de visualização, adicione uma descrição opcional e escolha o método de autenticação - Identidade gerida (recomendada, quando disponível) ou Baseada em chaves.
4. Selecione Criar. O gateway importa as implementações do recurso como modelos que os clientes solicitam por nome.

Adicionar um modelo personalizado

1. Selecionar Adicionar um modelo personalizado.
2. No Fornecedor, introduza um nome de exibição e o nome do fornecedor, e uma descrição opcional.
3. No Endpoint, introduza o URL base do endpoint, o nome do cabeçalho de autenticação (por exemplo, Authorization), e a chave da API.
4. Em Modelos, introduza o nome de cada modelo e selecione os seus endpoints suportados - conclusões de chat da OpenAI, respostas da OpenAI, mensagens da Anthropic ou Outro. Selecione Adicionar modelo para cada modelo que definir.
5. Selecione Criar.

Não há um passo separado de validação. O gateway configura a ligação quando crias o fornecedor. Depois de adicionar um modelo, pode atualizar a sua autenticação ou políticas, ou removê-lo quando já não for necessário.

Depois de o modelo ser adicionado, envie um pedido de teste através do 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 ainda não criaste uma chave de acesso em tempo de execução, cria uma a partir da página de Chaves . As candidaturas não precisam de credenciais diretas do fornecedor. Use vistas de monitorização para rever o volume de pedidos, latência, utilização de tokens e erros por nome do modelo.

encaminhamento da API Anthropic Messages

Diferentes fornecedores expõem diferentes formatos de API, e o gateway serve cada um no seu próprio caminho sob /default/models. Os modelos Anthropic utilizam a API Anthropic Messages em modo passthrough: o gateway preserva o formato nativo de pedido 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, introduza um nome de exibição e o nome do provider para Anthropic.
2. Em Endpoint, defina a URL de base do endpoint para https://api.anthropic.com, defina o nome do cabeçalho de autenticação para x-api-key e introduza a chave da API da Anthropic. O gateway armazena a chave e injeta-a nas chamadas de backend.
3. Em Models, introduza o nome do modelo Anthropic que os autores das chamadas enviam (como claude-fable-5) e selecione o endpoint Anthropic messages.
4. Selecione Criar. O gateway fornece encaminhamento de Anthropic Messages em /default/models/anthropic/v1/messages.

Os clientes chamam o caminho do gateway. O gateway armazena a credencial, injeta o backend x-api-key e encaminha o cabeçalho anthropic-version do autor da chamada para a 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 Anthropic Python funciona quando apontas base_url para o caminho do gateway. Por defeito, o SDK predefinido envia a credencial no cabeçalho x-api-key, por isso transmita a chave de acesso do runtime do gateway no cabeçalho api-key, recorrendo a default_headers. O valor api_key="unused" apenas cumpre o requisito do argumento obrigatório do SDK; o gateway ignora-o e injeta a chave Anthropic armazenada no backend. Defina model para o nome do modelo 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 tempos de espera e o tratamento das respostas antes da produção, especialmente se as políticas inspecionarem os corpos.

Adicionar servidores MCP

O escalão AI Gateway permite que as equipas de plataforma publiquem servidores MCP por detrás de um único endpoint MCP sujeito a governação. 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 incorporados para aplicações SaaS comuns (mais de 1.000 integrações pré-construídas, sem servidor para alojar).

Use servidores MCP quando os agentes precisarem de ligar a sistemas empresariais, ferramentas de desenvolvimento, armazenamentos de conhecimento ou APIs internas. Os agentes autenticam-se uma vez no gateway e não precisam de credenciais separadas para cada backend. Para cada backend, escolhe como o gateway se autentica: Nenhum, Chave API, OAuth 2.0 ou Identidade Gerida.

Um único servidor MCP federa um ou mais backends. Cada backend contribui com ferramentas, e o gateway atribui um espaço de nomes às ferramentas de cada backend com o nome do backend, para que ferramentas com nomes idênticos de backends diferentes não entrem em conflito. Por exemplo, uma ferramenta create_issue de um backend denominado github é exposta aos agentes no espaço de nomes github, distinta de uma ferramenta create_issue noutro backend.

Cada fonte contribui com ferramentas de forma diferente:

• Servidor MCP — federa as ferramentas a partir de um endpoint MCP remoto que já hospeda.
• Especificação OpenAPI — transforma as operações da API que seleciona em ferramentas; O resumo ou descrição da operação torna-se a descrição da ferramenta.
• Conector incorporado — utiliza uma ligação gerida a uma aplicação SaaS como Office 365, SharePoint, GitHub ou Salesforce. Os conectores OAuth pedem consentimento quando configuras a ligação.

Para criar um servidor MCP:

1. No portal de níveis AI Gateway, selecione os servidores MCP.
2. Selecione Adicionar servidor MCP.
3. No Código-Fonte, escolha um tipo de backend para começar: servidor MCP, especificação OpenAPI ou conector incorporado. Podes adicionar mais backends depois.
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 se autentica nele: Nenhum, Chave API, OAuth 2.0 ou Identidade Gerida. Para API Key, introduza o nome e valor do cabeçalho; os valores são encriptados em repouso.
6. Para federar mais serviços atrás do mesmo endpoint, adiciona outro backend e repete.
7. Selecione Confirmar e depois Criar.

Não existe um passo separado para o teste de conectividade. O gateway configura e verifica cada backend quando crias o servidor.

O gateway cria um endpoint MCP que federa todos os backends selecionados. Os clientes chamam o endpoint governado e autenticam-se com uma chave de acesso em tempo de execução.

Os agentes contactam o servidor MCP em:

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

Envie a chave de acesso de tempo de execução no cabeçalho api-key. Aponta qualquer framework cliente ou agente compatível com MCP para esta URL. Por exemplo, liste as ferramentas disponíveis com um pedido de 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 sua descrição OpenAPI. Selecione operações para expor como ferramentas, edite os nomes e as descrições das ferramentas, configure um método de autenticação de servidor suportado e crie o ativo MCP. O gateway mapeia as chamadas de ferramenta para operações REST.

Utilize o gateway para servidores MCP para centralizar:

• Discovery — forneça um catálogo de servidores MCP aprovados para programadores e agentes.
• Autenticação — os clientes autenticam-se no gateway. O gateway armazena credenciais backend, por isso a configuração do cliente não contém segredos a montante.
• Disponibilização de ferramentas — escolha quais as operações de backend que cada servidor disponibiliza como ferramentas. Na versão de pré-visualização, cada chave de acesso em tempo de execução pode invocar todos os recursos publicados no gateway.
• Observabilidade — o gateway emite métricas de utilização de tokens OpenTelemetry (OTLP) para tráfego de modelos, que pode enviar para o Application Insights ou outro destino OTLP. A monitorização do tráfego da ferramenta MCP (volume de pedidos, latência e erros) está disponível no portal quando utiliza o Application Insights; A exportação do OpenTelemetry (OTLP) para tráfego da ferramenta MCP ainda não está disponível.
• Governação — aplique as mesmas políticas ao tráfego MCP que usa para modelos, como limites de taxa e segurança de conteúdos.

Depois de criares o servidor, configura o acesso em tempo de execução antes de o partilhar. Adicione políticas como segurança de conteúdo, filtros de IP e limites para a taxa de tokens e de pedidos, aplicáveis ao gateway ou a ativos publicados específicos.

Conteúdo relacionado

• Visão geral dos níveis do AI Gateway
• Início rápido: Criar uma instância do escalão AI Gateway
• Gerir, proteger e operar o escalão do AI Gateway
• Configurar redes privadas