Início Rápido: Criar agentes usando a API de Respostas

Neste guia de início rápido, você chama a Responses API em um endpoint de projeto do Foundry a partir do seu próprio código para criar um agente efêmero — um agente cuja definição (instruções, ferramentas, modelo) fica no código do seu aplicativo, em vez de existir como um recurso persistente no Foundry Agent Service. Cada chamada constrói o agente em seu processo e invoca a API de Respostas para inferência de modelo e orquestração de ferramentas.

Esse padrão é adequado para desenvolvedores, ISVs e empresas nativas digitais que querem que suas definições de agente sejam distribuídas e versionadas junto com o restante do código do aplicativo, em vez de ficarem em um recurso separado que alguém precise manter sincronizado com o aplicativo. Ao contrário dos agentes de prompt, não há nenhum recurso de agente para criar, atualizar ou excluir no Foundry — o gerenciamento do ciclo de vida é feito diretamente por meio de chamadas à API Responses.

A API de Respostas é o único modelo e ponto de entrada de ferramentas para o Foundry. Você pode fazer chamadas para dois endpoints diferentes:

  • Endpoint do projeto Foundry (este guia de início rápido, recomendado) — suporte completo do Foundry. Expõe modelos do Foundry das ferramentas de catálogo e plataforma (pesquisa de arquivos, interpretador de código, memória, pesquisa na Web, MCP, SharePoint, WorkIQ, Fabric IQ e muito mais) por meio de uma única superfície de API com escopo de projeto, acessada em {project_endpoint}/openai/v1/responses.
  • endpoint do Azure OpenAI — melhor latência e compatibilidade máxima com os clientes OpenAI existentes. Use isso quando precisar apenas de modelos OpenAI e ferramentas OpenAI padrão e não precisar de recursos específicos do Foundry.

O caminho recomendado é o Agent Framework, que cuida da autenticação, da integração das ferramentas e da orquestração de mensagens para você. Em Python isso é FoundryChatClient; em .NET é AIProjectClient.AsAIAgent(...). O SDK da OpenAI também funciona neste endpoint e também é apresentado como alternativa em Usar o SDK da OpenAI diretamente.

Caso não tenha uma assinatura do Azure, crie uma conta gratuita.

Quando usar o padrão de agente efêmero

Use esse padrão quando estiver hospedando o código do agente fora do Foundry , potencialmente inserido em seu próprio aplicativo, mas quiser acessar os recursos do agente do Foundry, como modelos e ferramentas de plataforma.

O padrão efêmero e os agentes hospedados são aditivos, não alternativas. O mesmo código de agente do Agent Framework também pode ser empacotado como um agente hospedado e exposto por meio da API de Agentes do Foundry — o que é útil quando você deseja um ponto de extremidade gerenciado pelo Foundry que outros aplicativos, serviços ou agentes podem acessar. Você pode fazer as duas coisas a partir de uma única base de código: executar o agente no próprio processo, em que ele é distribuído com seu aplicativo, e publicar a mesma definição como um agente hospedado, quando outros chamadores precisarem dele.

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

A API Responses no endpoint de um projeto do Foundry é compatível com a API Responses da OpenAI, portanto os clientes OpenAI existentes funcionam com ela com alterações mínimas. O endpoint do projeto Foundry adiciona o seguinte além disso:

  • Dados no escopo do projeto: arquivos, armazenamentos vetoriais e outros dados são armazenados no nível do projeto, em vez do nível do recurso, o que garante o isolamento de dados por projeto e permite usar recursos próprios por meio da configuração padrão do agente.
  • Foundry Models além dos da OpenAI: Foundry Models vendidos diretamente pelo Azure (não apenas modelos da OpenAI) estão disponíveis por meio da mesma API.
  • Ferramentas específicas do Foundry: ferramentas de plataforma como SharePoint, WorkIQ e Fabric IQ estão disponíveis além das ferramentas padrão da OpenAI.
  • Autenticação em nome de (OBO) para ferramentas: as ferramentas podem chamar serviços downstream como o usuário conectado, não apenas como a identidade do aplicativo.
  • Observabilidade e governança no nível do projeto: As chamadas feitas por meio do endpoint do projeto passam pelo rastreamento, monitoramento, filtros de conteúdo e configuração de identidade do projeto sem configuração adicional (consulte Observabilidade e recursos empresariais).

Chamar o endpoint do projeto — e não um endpoint da OpenAI no nível do recurso — é o que habilita essas capacidades com escopo de projeto.

Pré-requisitos

  • Python 3.10 ou posterior instalado.

Definir variáveis de ambiente

Armazene o ponto de extremidade do projeto e o nome do modelo implantado como variáveis de ambiente. Os exemplos abaixo leem esses valores do ambiente.

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

Instalar pacotes

Instale o pacote do Agent Framework com o provedor 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 Microsoft.Agents.AI transitivamente.

Criar um agente

Crie um agente efêmero que seja executado localmente em seu processo e chame a API de Respostas para inferência de modelo e orquestração de ferramentas.

Use FoundryChatClient e a classe Agent.

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 exibe a resposta do agente. Como o agente é efêmero, nenhuma definição é persistida no serviço — ela existe apenas durante o ciclo de vida do processo Python.

Use AIProjectClient.AsAIAgent(...) da Microsoft Agent Framework para encapsular o endpoint do projeto do 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 exibe a resposta do agente. Como o agente é efêmero, nenhuma definição é persistida no serviço — ela existe apenas durante o tempo de vida do processo.

Adicionar ferramentas de funções

Defina as ferramentas de função local e passe-as para o agente. O agente chama automaticamente essas ferramentas quando necessário durante uma conversa.

Defina as 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 usa a API de Respostas para determinar quando chamar a get_weather função, executá-la localmente e retorna o resultado em linguagem natural.

Defina um método local, decore-o com [Description] atributos e embrulhe-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 usa a API de Respostas para determinar quando chamar GetWeather, executa-a localmente e retorna o resultado em linguagem natural.

Usar a ferramenta de pesquisa na Web

A API de Respostas no endpoint do projeto Foundry fornece ferramentas hospedadas integradas, como pesquisa na web. Dê ao agente acesso à pesquisa na Web sem nenhuma implementação local.

Use 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 busca na Web é executada no servidor por meio da API de Respostas do projeto Foundry. Você pode combiná-lo com ferramentas de função locais para fornecer ao agente acesso à Web e recursos 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?")}");

A ferramenta de busca na Web é executada no servidor por meio da API Responses do projeto Foundry. Você pode combiná-lo com ferramentas de função locais para fornecer ao agente acesso à Web e recursos de código personalizado:

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 respostas conforme elas geram em vez de aguardar a 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 fluxo AgentResponseUpdate:

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 de streaming é exibida incrementalmente no console à medida que o modelo gera cada token.

Capacidade de observação e funcionalidades empresariais

Efêmero não significa não gerenciado. Como as chamadas passam pelo ponto de extremidade do projeto, elas herdam a configuração corporativa do projeto sem fiação extra:

  • Rastreamento e monitoramento: solicitações, invocações de ferramenta e fluxo de uso de token na observabilidade do Foundry para o projeto.
  • Filtros de conteúdo e governança: filtros de conteúdo no nível do projeto e políticas de IA responsável se aplicam a todas as chamadas.
  • Identidade e acesso: as chamadas são autenticadas com base na configuração de identidade do projeto; as ferramentas habilitadas para OBO podem atuar como o usuário conectado.

O padrão efêmero não é uma camada de capacidade reduzida– você obtém os mesmos modelos, ferramentas, observabilidade e governança do Foundry, seja executando o agente em processo ou empacotando o mesmo código que um agente hospedado. A escolha é sobre a forma de implantação, não o conjunto de recursos.

Usar o SDK do OpenAI diretamente

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

Para obter exemplos de SDK, consulte:

exemplos de respostas Foundry (azure-ai-projects)

Exemplos do Azure.AI.OpenAI

Limpar os recursos

Como os agentes do Agent Framework criados aqui são efêmeros, nenhuma limpeza do lado do serviço é necessária. O agente existe somente em seu processo local. Se você criou recursos do Foundry que não precisa mais, exclua-os no portal do Foundry.

Conteúdo relacionado

Vá mais fundo nesse padrão

Empacote o mesmo código do agente como um agente hospedado

  • Last updated on