provedor de modelos do Microsoft Foundry

Microsoft Agent Framework dá suporte à inferência de modelo direto dos pontos de extremidade do projeto Microsoft Foundry, enquanto seu aplicativo possui a definição, as ferramentas e a orquestração do agente.

Para prompt gerenciado pelo serviço e agentes hospedados, consulte Microsoft Serviço do Agente de Fundiário.

Introdução

Adicione os pacotes NuGet necessários ao seu projeto.

dotnet add package Azure.Identity
dotnet add package Microsoft.Agents.AI.Foundry --prerelease

Dois padrões de integração

A integração do Microsoft Foundry expõe dois padrões de uso distintos:

Pattern	Tipo produzido	Description	Usar quando
Agente de Respostas	ChatClientAgent	Seu aplicativo fornece programaticamente um modelo, instruções e ferramentas em runtime por meio de AIProjectClient.AsAIAgent(...). Nenhum recurso de agente do lado do servidor é criado.	Você é o proprietário da definição do agente e deseja uma configuração simples e flexível. Esse é o padrão usado na maioria dos exemplos.
Agente de fundimento (prompt ou hospedado)	FoundryAgent	Gerenciado pelo servidor – Os Agentes de Prompt são definições nomeadas e com versão; Os Agentes Hospedados são aplicativos implantados acessados por meio de um ponto de extremidade específico do agente.	A Foundry é dona da definição do agente ou do runtime hospedado. Consulte Microsoft Serviço do Foundry Agent.

Agente de Respostas (inferência direta)

Use AsAIAgent diretamente no AIProjectClient com um modelo e instruções. Esse é o ponto de partida recomendado para a maioria dos cenários.

using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;

AIAgent agent = new AIProjectClient(
    new Uri("<your-foundry-project-endpoint>"),
    new DefaultAzureCredential())
        .AsAIAgent(
            model: "gpt-4o-mini",
            name: "Joker",
            instructions: "You are good at telling jokes.");

Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate."));

Warning

DefaultAzureCredential é conveniente para o desenvolvimento, mas requer uma consideração cuidadosa na produção. Em produção, considere o uso de uma credencial específica (por exemplo, ManagedIdentityCredential) para evitar problemas de latência, investigação de credenciais não intencionais e possíveis riscos de segurança de mecanismos de fallback.

Este caminho é baseado em código e não cria um recurso de agente gerenciado pelo servidor.

Usando o agente

O Responses Agent é um padrão AIAgent e dá suporte a sessões, ferramentas, middleware e streaming.

AgentSession session = await agent.CreateSessionAsync();
Console.WriteLine(await agent.RunAsync("Tell me a joke.", session));
Console.WriteLine(await agent.RunAsync("Now make it funnier.", session));

Para obter mais informações sobre como executar e interagir com agentes, consulte os tutoriais de introdução do Agente.

Tools

Os Agentes de Respostas do Foundry criados com base na superfície de ferramentas padrão do AIProjectClient.AsAIAgent(...) Agent Framework. Confira a visão geral das Ferramentas para a matriz de recursos completa.

Tool	Notes
Ferramentas de Funções	Suportado.
Aprovação da ferramenta	Suportado. Fornecido pelo cliente de chat com invocação de função do framework.
Interpretador de Código	Suportado.
Pesquisa de Arquivo	Suportado.
Ferramentas MCP hospedadas	Suportado.
Ferramentas MCP locais	Suportado.
Caixa de ferramentas do Microsoft Foundry	Suportado.

Fundição no Python

Em Python, todos os clientes específicos da Foundry agora residem em agent_framework.foundry.

• agent-framework-foundryfornece os conectores do Cloud Foundry: FoundryChatClient, , FoundryAgente FoundryEmbeddingClientFoundryMemoryProvider.
• agent-framework-foundry-local fornece FoundryLocalClient para a execução do modelo local.

Importante

Esta página aborda Microsoft pontos de extremidade de projeto e modelos do Foundry. Para o Serviço do Foundry Agent, consulte Microsoft Serviço de Agente de Fundimento. Se você tiver um endpoint de recurso autônomo do Azure OpenAI (), use as diretrizes de Python na página do provedor OpenAI . Se você quiser executar modelos com suporte localmente, consulte a página do provedor Local do Foundry.

Padrões de chat e agente do Foundry no Python

Scenario	Formato do Python	Usar quando
Inferência simples com o endpoint Foundry Responses	Agent(client=FoundryChatClient(...))	Seu aplicativo possui a definição do agente, as ferramentas e o loop de conversa, e você deseja um modelo implantado em um projeto do Foundry.
Agentes gerenciados pelo serviço no Serviço de Agentes da Foundry	FoundryAgent(...)	Você deseja se conectar a um PromptAgent ou HostedAgent criado e configurado no portal do Foundry ou por meio das APIs de serviço.

Installation

pip install agent-framework-foundry

O mesmo agent-framework-foundry pacote também inclui FoundryEmbeddingClient para inserções de ponto de extremidade de modelos do Foundry.

Configuration

FoundryChatClient

FOUNDRY_PROJECT_ENDPOINT="https://<your-project>.services.ai.azure.com"
FOUNDRY_MODEL="gpt-4o-mini"

FoundryEmbeddingClient

FOUNDRY_MODELS_ENDPOINT="https://<apim-instance>.azure-api.net/<foundry-instance>/models"
FOUNDRY_MODELS_API_KEY="<api-key>"
FOUNDRY_EMBEDDING_MODEL="text-embedding-3-small"
FOUNDRY_IMAGE_EMBEDDING_MODEL="Cohere-embed-v3-english"  # optional

FoundryChatClient usa o ponto de extremidade do projeto. FoundryEmbeddingClient usa o ponto de extremidade de modelos separados.

Escolha o cliente de Python certo

Scenario	Cliente preferencial	Notes
Recurso Azure OpenAI	OpenAIChatCompletionClient / OpenAIChatClient	Use a página do provedor OpenAI.
Inferência do projeto Microsoft Foundry	Agent(client=FoundryChatClient(...))	Usa o endpoint de Respostas do Foundry.
Agente gerenciado pelo serviço Microsoft Foundry	FoundryAgent	É recomendado para Agentes de Prompt e Agentes Hospedados.
Inserções de ponto de extremidade de modelos do Microsoft Foundry	FoundryEmbeddingClient	Usa FOUNDRY_MODELS_ENDPOINT mais FOUNDRY_EMBEDDING_MODEL / FOUNDRY_IMAGE_EMBEDDING_MODEL.
Runtime local do Foundry	Agent(client=FoundryLocalClient(...))	Consulte Foundry Local.

Criar um agente com FoundryChatClient

FoundryChatClient conecta-se a um modelo implantado em um projeto Foundry e usa o endpoint Respostas. Emparelhe-o com um padrão Agent quando seu aplicativo deve possuir instruções, ferramentas e gerenciamento de sessão.

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential

agent = Agent(
    client=FoundryChatClient(
        project_endpoint="https://your-project.services.ai.azure.com",
        model="gpt-4o-mini",
        credential=AzureCliCredential(),
    ),
    name="FoundryWeatherAgent",
    instructions="You are a helpful assistant.",
)

FoundryChatClient é o caminho de Python da Foundry para inferência direta e dá suporte a ferramentas, saídas estruturadas e streaming.

Tools

FoundryChatClient fornece métodos de fábrica estáticos para cada ferramenta de Foundry hospedada. As fábricas retornam objetos da ferramenta SDK que você passa para tools= em Agent ou diretamente para client.get_response(..., tools=[...]). Para ferramentas de agente gerenciado pelo serviço, consulte Microsoft Serviço do Foundry Agent.

As fábricas são métodos de classe, portanto você não precisa de uma instância para criar uma ferramenta:

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential

agent = Agent(
    client=FoundryChatClient(credential=AzureCliCredential()),
    instructions="You can search the web and run code.",
    tools=[
        FoundryChatClient.get_web_search_tool(),
        FoundryChatClient.get_code_interpreter_tool(),
    ],
)

Suporte de ferramentas

A tabela a seguir lista todas as ferramentas que o Python FoundryChatClient expõe hoje.

Tool	Fábrica em FoundryChatClient	Status	Detalhes
Ferramentas de Funções	n/a — passe qualquer chamável Python ou @ai_function	GA	Invocado localmente em seu processo de Python.
Aprovação da ferramenta	n/a — encapsula as ferramentas existentes	GA	Funciona com MCP hospedado e ferramentas de funções.
Interpretador de Código	get_code_interpreter_tool	GA	Execução de código em área restrita na Foundry.
Pesquisa de Arquivo	get_file_search_tool	GA	Pesquise arquivos carregados por meio de repositórios de vetores do Foundry.
Pesquisa na Web	get_web_search_tool	GA	Aterramento na Web com suporte do Bing gerenciado por Microsoft. Somente modelos do Azure OpenAI.
Geração de Imagem	get_image_generation_tool	GA	Geração de imagem hospedada no Foundry.
MCP hospedado	get_mcp_tool	GA	Servidor MCP remoto invocado pelo Foundry.
Local MCP	n/a — use MCPStreamableHTTPTool / MCPStdioTool	GA	É executado no seu processo; funciona com qualquer cliente.
Caixa de ferramentas do Microsoft Foundry	MCPStreamableHTTPTool ou FoundryToolbox	Beta	Consumido por MCP de FoundryChatClient; anexado no lado do servidor em FoundryAgent.
Aterramento do Bing	get_bing_grounding_tool	Experimental	Traga seu próprio grounding com o recurso do Bing Search.
Pesquisa Personalizada do Bing	get_bing_custom_search_tool	Preview	Fundamentação do Bing restrita a uma lista selecionada de domínios.
Pesquisa de IA do Azure	get_azure_ai_search_tool	Experimental	Pesquise em um índice do Pesquisa de IA do Azure  usando uma conexão do Foundry.
SharePoint	get_sharepoint_tool	Preview	Respostas básicas no conteúdo SharePoint.
Microsoft Fabric	get_fabric_tool	Preview	Consultar um agente de dados do Fabric.
Pesquisa de Memória	get_memory_search_tool	Preview	Pesquise um repositório de memória gerenciado pela Foundry.
Uso de Computadores	get_computer_use_tool	Preview	Permitir que o agente conduza um ambiente de desktop ou navegador.
Automação do navegador	get_browser_automation_tool	Preview	Controle um navegador usando uma conexão do Azure Playwright.
Agente para Agente (A2A)	get_a2a_tool	Preview	Chame outro agente A2A para usá-lo como ferramenta.

Note

As fábricas experimentais encapsulam tipos de SDK do GA Foundry, mas os wrappers em si podem mudar antes da GA. As fábricas de visualização encapsulam os tipos do SDK do Foundry cuja funcionalidade subjacente está em versão prévia e podem ser alteradas ou removidas. Ambos emitem ExperimentalWarning na primeira vez em que são utilizados em um processo.

Variantes de pesquisa na Web

A Foundry expõe três opções de aterramento com suporte do Bing. Escolha aquele que corresponda ao seu cenário:

• get_web_search_tool (GA) — padrão sem configuração; recurso do Bing gerenciado pela Microsoft. Somente modelos do Azure OpenAI. Limitado a user_location e search_context_size.
• get_bing_grounding_tool (experimental) – traga seu próprio recurso de aterramento com a pesquisa do Bing Azure. Compatível com count, freshness, market, set_lang e modelos Foundry não OpenAI.
• get_bing_custom_search_tool (versão prévia) — use sua própria instância do Bing Custom Search para restringir a fundamentação a um conjunto selecionado de domínios.

Todos os três enviam dados de pesquisa fora do limite de conformidade Azure. Confira a visão geral do embasamento na Web para ver a comparação completa.

client = FoundryChatClient(credential=AzureCliCredential())

# Default (GA): minimal configuration
web_search = client.get_web_search_tool(
    user_location={"city": "Amsterdam", "country": "NL"},
    search_context_size="medium",
)

Geração de imagem

get_image_generation_tool configura a ferramenta de geração de imagem hospedada do Foundry. O modelo produz conteúdo de imagem na resposta – não há arquivos extras para gerenciar.

image_gen = FoundryChatClient.get_image_generation_tool(
    model="gpt-image-1",
    size="1024x1024",
    output_format="png",
    quality="high",
)

Aterramento do Bing

get_bing_grounding_tool envolve a ferramenta Grounding with Bing Search Foundry. Crie você mesmo o recurso Grounding with Bing Search e adicione-o como uma conexão do projeto do Foundry; em seguida, forneça o ID da conexão.

bing = FoundryChatClient.get_bing_grounding_tool(
    connection_id="/subscriptions/.../connections/my-bing",
    market="en-US",
    freshness="Day",
    count=10,
)

Pesquisa personalizada do Bing

get_bing_custom_search_tool restringe a fundamentação à lista de permissões definida em um recurso de Pesquisa Personalizada do Bing.

bing_custom = FoundryChatClient.get_bing_custom_search_tool(
    connection_id="/subscriptions/.../connections/my-bing-custom",
    instance_name="docs-only",
    market="en-US",
)

Pesquisa de IA do Azure 

get_azure_ai_search_tool permite que o agente consulte um índice de Pesquisa de IA do Azure  por meio de uma conexão de projeto do Foundry.

ai_search = FoundryChatClient.get_azure_ai_search_tool(
    index_connection_id="/subscriptions/.../connections/my-search",
    index_name="product-docs",
    query_type="vector_semantic_hybrid",
    top_k=5,
)

SharePoint

get_sharepoint_tool baseia as respostas em conteúdo do SharePoint acessível por meio de uma conexão do Foundry com o SharePoint.

sharepoint = FoundryChatClient.get_sharepoint_tool(
    connection_id="/subscriptions/.../connections/my-sharepoint",
)

Microsoft Fabric

get_fabric_tool conecta o agente a um agente de dados do Microsoft Fabric por meio de uma conexão Foundry para que o agente possa responder a perguntas sobre seus dados do Fabric.

fabric = FoundryChatClient.get_fabric_tool(
    connection_id="/subscriptions/.../connections/my-fabric",
)

Pesquisa de memória

get_memory_search_tool permite que o agente pesquise um repositório de memória gerenciado pelo Foundry, opcionalmente com escopo para um usuário ou locatário.

memory = FoundryChatClient.get_memory_search_tool(
    memory_store_name="user-preferences",
    scope="{{$userId}}",
)

Uso do computador

get_computer_use_tool configura a ferramenta de pré-visualização do Computer Use — o modelo pode controlar um ambiente de desktop ou navegador por meio de ações de ponteiro e teclado.

computer = FoundryChatClient.get_computer_use_tool(
    environment="browser",
    display_width=1280,
    display_height=800,
)

Automação de navegador

get_browser_automation_tool conecta o agente a um recurso do Azure Playwright Testing via uma conexão do Foundry. O agente pode controlar um navegador real por meio do Playwright.

browser = FoundryChatClient.get_browser_automation_tool(
    connection_id="/subscriptions/.../connections/my-playwright",
)

Agente para Agente (A2A)

get_a2a_tool expõe um agente A2A remoto como uma ferramenta para que um agente do Foundry possa chamá-lo. Forneça uma base_url (e, opcionalmente, agent_card_path) ou um project_connection_id para uma conexão A2A armazenada.

a2a = FoundryChatClient.get_a2a_tool(
    base_url="https://remote-agent.example.com",
    agent_card_path="/.well-known/agent-card.json",
)

Para obter orientações gerais de descoberta, sessões e streaming do A2A, consulte o serviço de agente A2A.

Criar inserções com FoundryEmbeddingClient

Use FoundryEmbeddingClient quando quiser incorporar textos ou imagens de um endpoint de modelos Foundry.

from agent_framework.foundry import FoundryEmbeddingClient

async with FoundryEmbeddingClient() as client:
    result = await client.get_embeddings(["hello from Agent Framework"])
    print(result[0].dimensions)

Usando o agente

FoundryChatClientintegra-se com a experiência de Python Agent padrão, incluindo chamadas de ferramentas, sessões e respostas de streaming. Para runtimes locais, use a página separada do provedor Local do Foundry.

Para obter pacotes nomeados e com versão de configurações de ferramentas hospedadas, consulte Microsoft Caixa de Ferramentas do Foundry.

Foundry in Go

O SDK Go fornece agentes do Microsoft Foundry por meio de github.com/microsoft/agent-framework-go/provider/foundryprovider.

Consulte os exemplos do Foundry Go para obter inferência direta, ferramentas de função, ferramentas hospedadas, MCP e exemplos de servidor-agente.

O pacote suporta dois alvos de agente:

Target	Forma Go	Usar quando
Implantação de modelo com suporte do Project	foundryprovider.ModelDeployment("gpt-4o-mini")	Seu aplicativo possui instruções, ferramentas e fluxo de conversa.
Agente Foundry existente no servidor	foundryprovider.ServerAgent("my-agent")	A definição do agente já está configurada na Foundry.

Configuration

Defina o endpoint do projeto Foundry e a implantação do modelo:

FOUNDRY_PROJECT_ENDPOINT="https://<your-project>.services.ai.azure.com/api/projects/<project-id>"
FOUNDRY_MODEL="gpt-4o-mini"

Agente do Foundry apoiado por Project

Use ModelDeployment quando quiser criar um agente do Agent Framework no código e passar instruções, ferramentas, middleware e provedores de contexto do aplicativo Go.

import (
    "context"
    "os"

    "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
    "github.com/microsoft/agent-framework-go/agent"
    "github.com/microsoft/agent-framework-go/provider/foundryprovider"
)

endpoint := os.Getenv("FOUNDRY_PROJECT_ENDPOINT")
model := os.Getenv("FOUNDRY_MODEL")

token, err := azidentity.NewDefaultAzureCredential(nil)
if err != nil {
    panic(err)
}

a := foundryprovider.NewAgent(
    endpoint,
    token,
    foundryprovider.ModelDeployment(model),
    foundryprovider.AgentConfig{
        Instructions: "You are good at telling jokes.",
        Config: agent.Config{
            Name: "Joker",
        },
    },
)

resp, err := a.RunText(context.Background(), "Tell me a joke about a pirate.").Collect()

Agente Foundry existente no servidor

Use ServerAgent quando quiser invocar um agente já configurado no Foundry. O agente do lado do servidor tem suas próprias instruções e ferramentas, portanto AgentConfig.Instructions é ignorado para este destino.

a := foundryprovider.NewAgent(
    endpoint,
    token,
    foundryprovider.ServerAgent("my-agent"),
    foundryprovider.AgentConfig{
        Config: agent.Config{
            Name: "my-agent",
        },
    },
)

resp, err := a.RunText(ctx, "Summarize the current project status.").Collect()

Tools

Os agentes do Foundry com respaldo de projeto oferecem suporte à interface de ferramentas padrão do Go Agent Framework para ferramentas locais e declarações com suporte de ferramentas hospedadas.

Tool	Status	Notes
Ferramentas de Funções	Supported	As funções são executadas no seu processo Go.
Aprovação da ferramenta	Supported	Funciona com ferramentas de função locais por meio do loop de chamada automática da ferramenta.
Interpretador de Código	Supported	Use &hostedtool.CodeInterpreter{}.
Pesquisa na Web	Supported	Use &hostedtool.WebSearch{}.
Ferramentas MCP locais	Supported	Use tool/mcptool para se conectar a um servidor MCP e expor suas ferramentas localmente.
Ferramentas MCP hospedadas	Atualmente não há documentação para o Go Foundry	Use ferramentas MCP locais quando precisar de servidores MCP com agentes do Go Foundry.
Caixa de ferramentas do Microsoft Foundry	Atualmente não exposto por um helper em Go.

Para ferramentas de função local, adicione valores de tool.Tool a agent.Config.Tools:

a := foundryprovider.NewAgent(
    endpoint,
    token,
    foundryprovider.ModelDeployment(model),
    foundryprovider.AgentConfig{
        Instructions: "You are a helpful assistant.",
        Config: agent.Config{
            Tools: []tool.Tool{weatherTool},
        },
    },
)

Para execução de código hospedado, passe a declaração da ferramenta hospedada:

a := foundryprovider.NewAgent(
    endpoint,
    token,
    foundryprovider.ModelDeployment(model),
    foundryprovider.AgentConfig{
        Instructions: "You solve problems with code.",
        Config: agent.Config{
            Tools: []tool.Tool{&hostedtool.CodeInterpreter{}},
        },
    },
)

Cabeçalhos do cliente e modelo servido

A Foundry aceita cabeçalhos x-client-* por execução. Adicione-os com foundryprovider.WithClientHeader ou foundryprovider.WithClientHeaders:

resp, err := a.RunText(
    ctx,
    "Hello!",
    foundryprovider.WithClientHeader("x-client-scenario", "docs"),
).Collect()

Quando o Foundry retorna o cabeçalho de resposta x-ms-served-model, o provedor do Go o adiciona às propriedades adicionais de resposta/atualização como ServedModel.

if servedModel, ok := resp.AdditionalProperties["ServedModel"].(string); ok {
    fmt.Println(servedModel)
}

Provedor de memória Foundry

Use foundryprovider.NewMemoryProvider quando quiser que um agente do Agent Framework recupere e atualize um repositório de memória gerenciado pelo Foundry em cada execução.

import (
    "log/slog"

    "github.com/microsoft/agent-framework-go/agent"
    "github.com/microsoft/agent-framework-go/provider/foundryprovider"
)

memoryProvider := foundryprovider.NewMemoryProvider(
    endpoint,
    tokenCredential,
    "memory-store-sample",
    func(*agent.Session) string { return "user-123" },
    foundryprovider.MemoryProviderConfig{
        Logger: slog.Default(),
    },
)

a := foundryprovider.NewAgent(
    endpoint,
    tokenCredential,
    foundryprovider.ModelDeployment(model),
    foundryprovider.AgentConfig{
        Instructions: "Use known memories about the user when responding.",
        Config: agent.Config{
            Name:             "FoundryMemoryAgent",
            ContextProviders: []agent.ContextProvider{memoryProvider},
        },
    },
)

O endpoint deve ser um endpoint do Microsoft Foundry com escopo de projeto, e o armazenamento de memória já deve existir nesse projeto. O retorno de chamada de escopo deve retornar uma chave de partição de usuário, locatário ou conversa estável.

Dica

Consulte o exemplo de memória do Foundry em Go para ver um exemplo completo e executável.

Lacunas atuais do Go

Atualmente, o suporte ao Go não inclui APIs de implantação/ciclo de vida/administrador hospedados do Foundry, clientes de inserção ou auxiliares específicos do Go para Microsoft Caixa de Ferramentas do Foundry. Use o portal do Foundry ou os SDKs de serviço para essas operações.

Próximas Etapas 

Fábrica Local