Fornecedor de modelos Microsoft Foundry

O Microsoft Agent Framework suporta inferência direta de modelos a partir dos endpoints do projeto Microsoft Foundry, enquanto a sua aplicação detém a definição do agente, ferramentas e orquestração.

Para Prompt e Agentes Hospedados geridos por serviços, veja Microsoft Foundry Agent Service.

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 com o Microsoft Foundry expõe dois padrões de utilização distintos:

Pattern	Tipo de produto produzido	Description	Utilizar quando
Agente de Respostas	ChatClientAgent	A sua aplicação fornece programaticamente um modelo, instruções e ferramentas em tempo de execução via AIProjectClient.AsAIAgent(...). Não é criado nenhum recurso agente do lado do servidor.	Tem a definição de agente e quer uma configuração simples e flexível. Este é o padrão usado na maioria das amostras.
Agente da Fundição (Prompt ou Hospedado)	FoundryAgent	Gerido pelo servidor — Os Prompt Agents são definições nomeadas e versionadas; Os Agentes Alojados são aplicações implementadas acedidas através de um endpoint específico do agente.	A Foundry detém a definição do agente ou o tempo de execução hospedado. Ver Serviço de Agentes Microsoft Foundry.

Agente de Respostas (inferência direta)

Use AsAIAgent diretamente no AIProjectClient com um modelo e instruções. Este é 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 usar uma credencial específica (por exemplo, ManagedIdentityCredential) para evitar problemas de latência, sondagens não intencionais de credenciais e potenciais riscos de segurança provenientes de mecanismos de recurso.

Este caminho é centrado no código e não cria um recurso de agente gerido pelo servidor.

Usando o agente

O Response Agent é um padrão AIAgent e suporta 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 mais informações sobre como gerir e interagir com agentes, consulte os tutoriais de Início de Agentes.

Tools

Os Agentes de Respostas da Fundição criados suportam AIProjectClient.AsAIAgent(...) a superfície padrão da ferramenta Agent Framework. Consulte a visão geral das Ferramentas para a matriz completa de funcionalidades.

Tool	Notes
Ferramentas Funcionais	Apoiado.
Aprovação de Ferramentas	Apoiado. Fornecido pelo cliente de chat que invoca funções do framework.
Intérprete de código	Apoiado.
Pesquisa de ficheiros	Apoiado.
Ferramentas alojadas do MCP	Apoiado.
Ferramentas MCP Locais	Apoiado.
Microsoft Foundry Toolbox	Apoiado.

Ferramenta Foundry em Python

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

• agent-framework-foundry fornece os conectores cloud Foundry: FoundryChatClient, FoundryAgent, FoundryEmbeddingClient, e FoundryMemoryProvider.
• agent-framework-foundry-local permite FoundryLocalClient a execução local do modelo.

Importante

Esta página cobre o projeto Microsoft Foundry e modela endpoints. Para o Serviço de Agentes da Fundição, veja Serviço de Agentes da Microsoft Foundry. Se tiver um endpoint de recursos Azure OpenAI autónomo (https://<your-resource>.openai.azure.com), utilize as orientações Python na página do fornecedor OpenAI. Se quiser executar modelos suportados localmente, consulte a página do fornecedor local da Foundry.

Chat Foundry e padrões de agentes em Python

Scenario	Formato de Python	Utilizar quando
Inferência simples com o endpoint Foundry Answers	Agent(client=FoundryChatClient(...))	A tua aplicação detém a definição do agente, as ferramentas e o ciclo de conversa, e queres que um modelo seja implementado num projeto Foundry.
Agentes de gestão de serviços no Serviço de Agentes de Fundição	FoundryAgent(...)	Quer ligar-se a um PromptAgent ou HostedAgent que foi criado e configurado no portal Foundry ou através das APIs do serviço.

Instalação

pip install agent-framework-foundry

O mesmo agent-framework-foundry pacote também inclui FoundryEmbeddingClient embeddings de endpoints de modelos 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 endpoint do projeto. FoundryEmbeddingClient utiliza o endpoint de modelos separados.

Escolha o cliente Python certo

Scenario	Cliente preferencial	Notes
Recurso Azure OpenAI	OpenAIChatCompletionClient / OpenAIChatClient	Utilize a página do fornecedor OpenAI.
Inferência do projeto Microsoft Foundry	Agent(client=FoundryChatClient(...))	Utiliza o endpoint Foundry Responses.
Agente gerido pelo serviço Microsoft Foundry	FoundryAgent	Recomendado para Prompt Agents e HostedAgents.
Microsoft Foundry incorporações de modelos-ponto final	FoundryEmbeddingClient	Usa FOUNDRY_MODELS_ENDPOINT com FOUNDRY_EMBEDDING_MODEL / FOUNDRY_IMAGE_EMBEDDING_MODEL.
Tempo de execução Local do Foundry	Agent(client=FoundryLocalClient(...))	Ver o Foundry Local.

Crie um agente com FoundryChatClient

FoundryChatClient liga-se a um modelo implementado num projeto Foundry e utiliza o endpoint Responses. Emparelhe-o com um padrão Agent quando a aplicação deve ter instruções, ferramentas e manuseio de sessões.

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 primeiro caminho de Python da Foundry para inferência direta e suporta ferramentas, saídas estruturadas e streaming.

Tools

FoundryChatClient inclui métodos de fábrica estáticos para cada ferramenta Foundry alojada. As fábricas devolvem os objetos da ferramenta SDK que passa para tools= em Agent ou diretamente para client.get_response(..., tools=[...]). Para ferramentas de agentes geridos por serviços, consulte Microsoft Foundry Agent Service.

As fábricas são métodos de classes, por isso não precisas 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 abaixo lista todas as ferramentas que o Python FoundryChatClient expõe hoje.

Tool	Modo de fábrica ativado FoundryChatClient	Situação	Detail
Ferramentas Funcionais	N/A — Passe qualquer Python chamável ou @ai_function	disponibilidade geral	Executado localmente no seu processo Python.
Aprovação de Ferramentas	n/a — encapsula ferramentas existentes	disponibilidade geral	Funciona com MCP hospedado e ferramentas funcionais.
Intérprete de código	get_code_interpreter_tool	disponibilidade geral	Execução de código em sandbox no Foundry.
Pesquisa de ficheiros	get_file_search_tool	disponibilidade geral	Pesquise ficheiros carregados através de lojas vetoriais Foundry.
Pesquisa na Web	get_web_search_tool	disponibilidade geral	Ancoragem na Web suportada pelo Bing, gerida pela Microsoft. Apenas modelos do Azure OpenAI.
Geração de Imagem	get_image_generation_tool	disponibilidade geral	Geração de imagens alojada no Foundry.
MCP alojado	get_mcp_tool	disponibilidade geral	Servidor MCP remoto invocado pela Foundry.
Local MCP	n/a — utilize MCPStreamableHTTPTool / MCPStdioTool	disponibilidade geral	É executado no seu processo; funciona com qualquer cliente.
Microsoft Foundry Toolbox	MCPStreamableHTTPTool ou FoundryToolbox	Beta	Consumido através do MCP a partir de FoundryChatClient; anexado no lado do servidor em FoundryAgent.
Aterramento do Bing	get_bing_grounding_tool	Experimental	Traz o teu próprio recurso de Pesquisa sobre Grounding com Bing.
Pesquisa Personalizada Bing	get_bing_custom_search_tool	Preview	Base do Bing limitada a uma lista selecionada de domínios.
Pesquisa de IA do Azure	get_azure_ai_search_tool	Experimental	Pesquise num índice Pesquisa de IA do Azure através de uma ligação Foundry.
SharePoint	get_sharepoint_tool	Preview	Baseie as respostas no conteúdo 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 numa loja de memórias gerida pela Foundry.
Utilização de computadores	get_computer_use_tool	Preview	Deixe o agente controlar um ambiente de trabalho ou de navegador.
Automação de Navegadores	get_browser_automation_tool	Preview	Controle um navegador através de uma ligação ao Azure Playwright.
Agente-para-Agente (A2A)	get_a2a_tool	Preview	Chama outro agente da A2A como ferramenta.

Observação

As fábricas experimentais encapsulam os tipos do SDK do GA Foundry, mas os próprios encapsulamentos podem mudar antes da disponibilidade geral. Fábricas em pré-visualização envolvem tipos do SDK Foundry cuja capacidade subjacente se encontra em pré-visualização e pode ser alterada ou removida. Ambos emitem um ExperimentalWarning na primeira vez que são utilizados num processo.

Variantes da pesquisa web

Foundry disponibiliza três opções de ancoragem suportadas pelo Bing. Escolhe aquele que corresponde ao teu cenário:

• get_web_search_tool (GA) — predefinição sem configuração; recurso do Bing gerido pela Microsoft. Apenas modelos do Azure OpenAI. Limitado a user_location e search_context_size.
• get_bing_grounding_tool (experimental) — utilize o seu próprio recurso do Azure para Grounding with Bing Search. Suporta count, freshness, market, set_lang, e modelos Foundry não-OpenAI.
• get_bing_custom_search_tool (versão preliminar) — utilize a sua própria instância do Bing Custom Search para restringir a fundamentação a um conjunto selecionado de domínios.

Os três enviam dados de pesquisa fora do limite de conformidade do Azure. Consulte a visão geral do grounding web para 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 imagens

get_image_generation_tool configura a ferramenta de geração de imagens alojada do Foundry. O modelo produz conteúdo de imagem na resposta — não há ficheiros extra para gerir.

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

Fundamentação no Bing

get_bing_grounding_tool encapsula a ferramenta Grounding with Bing Search Foundry. Crias tu próprio o recurso de pesquisa Grounding with Bing e adicionas-no como ligação ao projeto Foundry, depois passas o ID da ligação.

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

Pesquisa personalizada no Bing

get_bing_custom_search_tool restringe a fundamentação à lista de permissões definida no recurso Bing Custom Search.

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 ao agente consultar um índice de Pesquisa de IA do Azure através de uma ligação ao projeto 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údos do SharePoint acessíveis através de uma ligação do Foundry ao SharePoint.

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

Microsoft Fabric

get_fabric_tool liga o agente a um agente de dados Microsoft Fabric através de uma ligação Foundry para que o agente possa responder a perguntas sobre os seus dados Fabric.

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

Pesquisa na memória

get_memory_search_tool permite ao agente pesquisar num arquivo de memória gerido pela Foundry, opcionalmente limitado a um utilizador ou inquilino.

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

Utilização do computador

get_computer_use_tool configura a ferramenta de Pré-visualização do Uso do Computador — o modelo pode controlar um ambiente de trabalho ou navegador emitindo ações de ponteiro e teclado.

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

Automatização do browser

get_browser_automation_tool liga o agente a um recurso do Azure Playwright Testing por meio de uma ligação do Foundry. O agente pode controlar um navegador real utilizando o 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 ferramenta para que um agente da Foundry o possa invocar. Forneça um base_url (e opcionalmente agent_card_path) ou um project_connection_id para uma ligação A2A armazenada.

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

Para descobertas gerais de A2A, sessões e orientações sobre streaming, consulte o serviço de agentes A2A.

Criar embeddings com FoundryEmbeddingClient

Use FoundryEmbeddingClient quando quiser embeddings de texto ou imagem a partir 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 padrão em PythonAgent, incluindo chamadas de ferramentas, sessões e respostas em streaming. Para tempos de execução locais, utilize a página separada do fornecedor local da Foundry.

Para pacotes nomeados e versionados de configurações de ferramentas alojadas, consulte Microsoft Foundry Toolbox.

Fundição em Go

O SDK de Go disponibiliza agentes do Microsoft Foundry através de github.com/microsoft/agent-framework-go/provider/foundryprovider.

Consulte os exemplos do Foundry Go para inferência direta, ferramentas funcionais, ferramentas alojadas, MCP e exemplos de servidor-agente.

O pacote suporta dois alvos de agente:

Target	Vai em forma	Utilizar quando
Implementação de modelos apoiados por Project	foundryprovider.ModelDeployment("gpt-4o-mini")	A sua aplicação controla as instruções, as ferramentas e o fluxo da conversa.
Agente Foundry existente do lado do servidor	foundryprovider.ServerAgent("my-agent")	A definição do agente já está configurada no Foundry.

Configuration

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

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

Agente da fundição apoiado pelo Project

Use ModelDeployment quando quiser criar um agente Agent Framework em código e passar instruções, ferramentas, middleware e fornecedores de contexto a partir da sua aplicação 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 do lado do servidor

Usa ServerAgent quando quiseres invocar um agente já configurado no Foundry. O agente no lado do servidor tem as suas próprias instruções e ferramentas, pelo que 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 Foundry suportados pelo Project suportam a superfície de ferramentas padrão do Go Agent Framework para ferramentas locais e declarações de ferramentas alojadas suportadas.

Tool	Situação	Notes
Ferramentas Funcionais	Suportado	As funções são executadas no seu processo Go.
Aprovação de Ferramentas	Suportado	Funciona com ferramentas de funções locais através do ciclo de chamada automática da ferramenta.
Intérprete de código	Suportado	Utilize &hostedtool.CodeInterpreter{}.
Pesquisa na Web	Suportado	Utilize &hostedtool.WebSearch{}.
Ferramentas MCP Locais	Suportado	Use tool/mcptool para se ligar a um servidor MCP e expor as suas ferramentas localmente.
Ferramentas alojadas do MCP	Atualmente, não existe documentação para o Go Foundry	Usa ferramentas MCP locais quando precisares de servidores MCP com agentes do Go Foundry.
Microsoft Foundry Toolbox	Neste momento não estou exposto através de um auxiliar do Go.

Para ferramentas de funções locais, adicione tool.Tool valores através de: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 alojado, passe a declaração da ferramenta alojada:

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 de cliente e modelo servido

A Foundry aceita x-client-* cabeçalhos 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 devolve o cabeçalho de resposta x-ms-served-model, o fornecedor de Go adiciona-o às propriedades adicionais de resposta/atualização como ServedModel.

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

Fornecedor de memória Foundry

Use foundryprovider.NewMemoryProvider quando quiser um agente do Agent Framework para recuperar e atualizar um armazenamento de memória gerido pela 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 tem de ser um endpoint do Microsoft Foundry ao nível do projeto, e o armazenamento de memória tem de já existir nesse projeto. O callback de âmbito deve devolver uma chave de partição estável para o utilizador, o tenant ou a conversa.

Tip

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

Lacunas atuais do Go

O suporte ao Go não inclui atualmente APIs de implementação/ciclo de vida/administração alojadas pelo Foundry, clientes de embeddings ou helpers específicos do Go para o Microsoft Foundry Toolbox. Use o portal Foundry ou os SDKs de serviço para essas operações.

Passos seguintes

Fundição Local