Início rápido: Construir agentes usando a API Responses

Neste guia de início rápido, vai chamar a API de Respostas no ponto final de um projeto do Foundry a partir do seu código para criar um agente efémero — um agente cuja definição (instruções, ferramentas, modelo) está no código da sua aplicação, em vez de existir como um recurso persistente no Foundry Agent Service. Cada chamada constrói o agente no seu processo e invoca a API de Respostas para inferência de modelos e orquestração de ferramentas.

Este padrão adequa-se a programadores, ISVs e nativos digitais que querem que as definições dos seus agentes sejam incluídas e versionadas com o resto do código da aplicação, em vez de serem um recurso fora de banda que alguém tem de manter sincronizado com a aplicação. Ao contrário dos agentes de prompt, não há nenhum recurso de agente para criar, atualizar ou eliminar no Foundry — a gestão do ciclo de vida é feita através de chamadas diretas à Responses API.

A API Responses é o único ponto de entrada para modelos e ferramentas para o Foundry. Pode invocá-lo em dois endpoints diferentes:

Ponto de extremidade do projeto Foundry (este guia de início rápido, recomendado) — suporte completo para o Foundry. Expõe modelos Foundry do catálogo e das ferramentas da plataforma (pesquisa de ficheiros, interpretador de código, memória, pesquisa na Web, MCP, SharePoint, WorkIQ, Fabric IQ, entre outros) através de uma única superfície da API delimitada ao projeto, disponível em {project_endpoint}/openai/v1/responses.
Azure endpoint OpenAI — melhor latência e máxima compatibilidade com clientes OpenAI existentes. Usa isto quando só precisares de modelos OpenAI e ferramentas OpenAI padrão e não precisares de capacidades específicas da Foundry.

O caminho recomendado é o Agent Framework, que trata da autenticação, cablagem de ferramentas e orquestração de mensagens por si. Em Python isto é FoundryChatClient; em .NET é AIProjectClient.AsAIAgent(...). O SDK OpenAI também funciona contra este endpoint e é abordado como alternativa em Use o SDK OpenAI diretamente.

Se você não tiver uma assinatura do Azure, crie uma conta gratuita.

Quando usar o padrão do agente efémero

Use este padrão quando estiver a hospedar código de agente fora do Foundry — potencialmente embutido na sua própria aplicação — mas quiser aceder a funcionalidades do agente do Foundry, como modelos e ferramentas de plataforma.

O padrão efémero e os agentes alojados são aditivos, não alternativos. O mesmo código de agente do Agent Framework também pode ser empacotado como agente alojado e exposto através da API de Agentes da Foundry — útil quando se pretende um endpoint gerido pela Foundry que outras aplicações, serviços ou agentes possam acedir. Pode fazer ambas as coisas a partir de uma única base de código: executar o agente no processo, integrado na sua aplicação, e publicar a mesma definição como um agente alojado para utilização por outros clientes quando necessário.

O que o endpoint de projeto do Foundry adiciona além da OpenAI Responses API

A API Responses num endpoint de projeto do Foundry é compatível com a API Responses da OpenAI, pelo que os clientes OpenAI existentes podem ser usados com ele com o mínimo de alterações. O endpoint do projeto Foundry inclui ainda o seguinte:

Dados ao nível do projeto: Os ficheiros, as bases de dados vetoriais e outros dados são armazenados ao nível do project, em vez de ao nível do recurso, o que assegura o isolamento dos dados por projeto e permite utilizar recursos próprios através da configuração padrão de agentes.
Foundry Models, além do OpenAI: Modelos Foundry vendidos diretamente por Azure (não apenas modelos OpenAI) estão disponíveis através da mesma API.
Ferramentas específicas da Foundry: Ferramentas de plataforma como SharePoint, WorkIQ e Fabric IQ estão disponíveis juntamente com as ferramentas padrão da OpenAI.
Autenticação em nome de (OBO) para ferramentas: As ferramentas podem invocar serviços a jusante em nome do utilizador com sessão iniciada, e não apenas em nome da identidade da aplicação.
Observabilidade e governação ao nível do projeto: As chamadas feitas através do endpoint do projeto passam pelo rastreio, monitorização, filtros de conteúdo e configuração de identidade do projeto sem configuração adicional (ver Observabilidade e capacidades empresariais).

Chamar o endpoint do projeto — e não um endpoint da OpenAI ao nível do recurso — é isso que desbloqueia estas capacidades no âmbito do projeto.

Pré-requisitos

Um modelo implementado no Microsoft Foundry. Se não tiver um modelo, complete primeiro o Quickstart: Configurar os recursos do Microsoft Foundry.
O CLI do Azure instalado e com sessão iniciada (az login).

Python 3.10 ou posterior instalado.

.NET 8 SDK ou posterior instalado.

Definir variáveis de ambiente

Armazene o endpoint do projeto e o nome do modelo implementado como variáveis de ambiente. Os exemplos abaixo indicam estes valores do ambiente.

FOUNDRY_PROJECT_ENDPOINT=<endpoint copied from welcome screen>
FOUNDRY_MODEL=<your deployed model name>

Instalar pacotes

Instale o pacote Agent Framework com o fornecedor Foundry:

pip install agent-framework-foundry aiohttp

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

Microsoft.Agents.AI.Foundry fornece o método de extensão AsAIAgent(...) em AIProjectClient e traz transitivamente Microsoft.Agents.AI.

Criar um agente

Crie um agente efémero que corra localmente no seu processo e chame a API Responses para inferência de modelos e orquestração de ferramentas.

Uso FoundryChatClient e a Agent classe.

import asyncio
import os

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

async def main() -> None:
    agent = Agent(
        client=FoundryChatClient(
            project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
            model=os.environ["FOUNDRY_MODEL"],
            credential=AzureCliCredential(),
        ),
        instructions="You are a helpful assistant.",
    )

    result = await agent.run("What is the capital of France?")
    print(f"Agent: {result}")

if __name__ == "__main__":
    asyncio.run(main())

A saída mostra a resposta do agente. Como o agente é efémero, nenhuma definição é mantida para o serviço — ele existe apenas durante a vida útil do processo Python.

Utilize AIProjectClient.AsAIAgent(...) da Microsoft Agent Framework para encapsular o endpoint do projeto Foundry como um AIAgent.

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

string endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
string deploymentName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL")
    ?? throw new InvalidOperationException("FOUNDRY_MODEL is not set.");

AIAgent agent =
    new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
    .AsAIAgent(
        model: deploymentName,
        instructions: "You are a helpful assistant.",
        name: "Assistant");

Console.WriteLine($"Agent: {await agent.RunAsync("What is the capital of France?")}");

A saída apresenta a resposta do agente. Como o agente é efémero, nenhuma definição é persistida no serviço — existe apenas durante o tempo de execução do processo.

Adicionar ferramentas funcionais

Define ferramentas de função local e passa-as ao agente. O agente chama automaticamente estas ferramentas quando necessário durante uma conversa.

Defina ferramentas de função local usando o @tool decorador.

import asyncio
import os
from random import randint
from typing import Annotated

from agent_framework import Agent, tool
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential
from pydantic import Field

@tool(approval_mode="never_require")
def get_weather(
    location: Annotated[str, Field(description="The location to get the weather for.")],
) -> str:
    """Get the weather for a given location."""
    conditions = ["sunny", "cloudy", "rainy", "stormy"]
    return f"The weather in {location} is {conditions[randint(0, 3)]} with a high of {randint(10, 30)}°C."

async def main() -> None:
    agent = Agent(
        client=FoundryChatClient(
            project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
            model=os.environ["FOUNDRY_MODEL"],
            credential=AzureCliCredential(),
        ),
        instructions="You are a helpful weather agent.",
        tools=get_weather,
    )

    result = await agent.run("What's the weather like in Seattle?")
    print(f"Agent: {result}")

if __name__ == "__main__":
    asyncio.run(main())

O agente utiliza a API Responses para determinar quando chamar a get_weather função, executa-a localmente e devolve o resultado em linguagem natural.

Defina um método local, decore-o com [Description] atributos e envolva-o com AIFunctionFactory.Create(...).

using System.ComponentModel;
using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;

[Description("Get the weather for a given location.")]
static string GetWeather(
    [Description("The location to get the weather for.")] string location)
{
    string[] conditions = ["sunny", "cloudy", "rainy", "stormy"];
    Random rng = Random.Shared;
    return $"The weather in {location} is {conditions[rng.Next(conditions.Length)]} with a high of {rng.Next(10, 31)}°C.";
}

AITool weatherTool = AIFunctionFactory.Create(GetWeather);

string endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
string deploymentName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL")
    ?? throw new InvalidOperationException("FOUNDRY_MODEL is not set.");

AIAgent agent =
    new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
    .AsAIAgent(
        model: deploymentName,
        instructions: "You are a helpful weather agent.",
        name: "WeatherAssistant",
        tools: [weatherTool]);

Console.WriteLine($"Agent: {await agent.RunAsync("What's the weather like in Seattle?")}");

O agente utiliza a API Responses para determinar quando chamar GetWeather, executa-o localmente e devolve o resultado em linguagem natural.

Use a ferramenta de pesquisa web

A API Responses no endpoint do projeto Foundry fornece ferramentas alojadas integradas, como pesquisa web. Dê ao seu agente acesso à pesquisa na web sem qualquer implementação local.

Utilize FoundryChatClient.get_web_search_tool():

import asyncio
import os

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

async def main() -> None:
    agent = Agent(
        client=FoundryChatClient(
            project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
            model=os.environ["FOUNDRY_MODEL"],
            credential=AzureCliCredential(),
        ),
        instructions="You are a research assistant. Use web search to find current information.",
        tools=[
            FoundryChatClient.get_web_search_tool(),
        ],
    )

    result = await agent.run("What are the latest updates to Microsoft Foundry?")
    print(f"Agent: {result}")

if __name__ == "__main__":
    asyncio.run(main())

A ferramenta de pesquisa web executa-se do lado do servidor através da API Answers do projeto Foundry. Pode combiná-lo com ferramentas de funções locais para dar ao seu agente tanto acesso web como capacidades de código personalizado:

agent = Agent(
    client=FoundryChatClient(
        project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
        model=os.environ["FOUNDRY_MODEL"],
        credential=AzureCliCredential(),
    ),
    instructions="You are a helpful assistant with web and weather capabilities.",
    tools=[
        FoundryChatClient.get_web_search_tool(),
        get_weather,  # Local function tool defined with @tool
    ],
)

Passe new HostedWebSearchTool() na lista tools:

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

string endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
string deploymentName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL")
    ?? throw new InvalidOperationException("FOUNDRY_MODEL is not set.");

AIAgent agent =
    new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
    .AsAIAgent(
        model: deploymentName,
        instructions: "You are a research assistant. Use web search to find current information.",
        name: "ResearchAssistant",
        tools: [new HostedWebSearchTool()]);

Console.WriteLine($"Agent: {await agent.RunAsync("What are the latest updates to Microsoft Foundry?")}");

AIAgent agent =
    new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
    .AsAIAgent(
        model: deploymentName,
        instructions: "You are a helpful assistant with web and weather capabilities.",
        name: "Assistant",
        tools: [new HostedWebSearchTool(), weatherTool]);

Respostas em fluxo

Receba as respostas à medida que forem geradas em vez de esperar pela mensagem completa.

Use o stream=True parâmetro:

import asyncio
import os

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

async def main() -> None:
    agent = Agent(
        client=FoundryChatClient(
            project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
            model=os.environ["FOUNDRY_MODEL"],
            credential=AzureCliCredential(),
        ),
        instructions="You are a helpful assistant.",
    )

    print("Agent: ", end="", flush=True)
    async for chunk in agent.run("Tell me a fun fact.", stream=True):
        if chunk.text:
            print(chunk.text, end="", flush=True)
    print()

if __name__ == "__main__":
    asyncio.run(main())

Chame RunStreamingAsync e itere o AgentResponseUpdate fluxo:

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

string endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
string deploymentName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL")
    ?? throw new InvalidOperationException("FOUNDRY_MODEL is not set.");

AIAgent agent =
    new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
    .AsAIAgent(
        model: deploymentName,
        instructions: "You are a helpful assistant.",
        name: "Assistant");

Console.Write("Agent: ");
await foreach (AgentResponseUpdate update in agent.RunStreamingAsync("Tell me a fun fact."))
{
    Console.Write(update);
}
Console.WriteLine();

A saída em streaming surge de forma incremental na consola à medida que o modelo gera cada token.

Observabilidade e capacidades empresariais

Efémero não significa sem controlo. Como as chamadas passam pelo endpoint do projeto, herdam a configuração empresarial do projeto sem cablagem adicional:

Rastreio e monitorização: As solicitações, as invocações de ferramentas e a utilização de tokens são encaminhadas para a observabilidade do Foundry do projeto.
Filtros de conteúdo e governação: Filtros de conteúdo ao nível de Project e políticas de IA responsável aplicam-se a todas as chamadas.
Identidade e acesso: As chamadas são autenticadas com base na configuração de identidade do projeto; as ferramentas com OBO ativado podem atuar em nome do utilizador com sessão iniciada.

O padrão efémero não é um nível de capacidade reduzida — obtém-se os mesmos modelos, ferramentas, observabilidade e governação do Foundry, quer execute o agente em processo ou empacote o mesmo código que um agente alojado. A escolha depende da forma de implementação, não do conjunto de funcionalidades.

Use diretamente o SDK OpenAI

Como a API Respostas do projeto Foundry é compatível com OpenAI, também pode chamá-la diretamente a partir do SDK OpenAI, apontando o cliente para o endpoint do projeto ({project_endpoint}/openai/v1/responses). Use este caminho apenas se já tiver código do SDK OpenAI ou precisar de controlo de nível inferior sobre as formas de pedido e resposta. O novo código deve dar preferência ao Agent Framework, que trata da autenticação, da integração das ferramentas e da orquestração por si.

Para exemplos de SDK, veja:

Exemplos do Foundry Responses (azure-ai-projects)

Exemplos do Azure.AI.OpenAI

Limpeza de recursos

Como os agentes do Agent Framework criados aqui são efémeros, não é necessária qualquer limpeza do lado do serviço. O agente existe apenas no seu processo local. Se criaste recursos da Foundry que já não precisas, apaga-os no portal da Foundry.

Aprofunda este padrão

Agent Framework em GitHub

Agentes com exemplos do Foundry (.NET)

Empacota o mesmo código de agente que um agente hospedado

Comentários

Esta página foi útil?

Last updated on 2026-06-03