Serviço do Microsoft Foundry Agent

FoundryAgent conecta o Agent Framework a uma definição de agente gerenciada pelo Microsoft Foundry Agent Service. O modelo, as instruções, as ferramentas hospedadas e a versão do agente são configurados na Foundry; seu aplicativo se conecta a essa definição e usa as APIs de execução, streaming e sessão padrão do Agent Framework.

Use essa integração para:

  • Prompt Agents, que são definições nomeadas e versionadas de agentes no servidor.
  • Agentes hospedados, que são aplicações de agente implantadas acessadas por meio de um endpoint específico do agente.

Para inferência direta de modelo, em que seu aplicativo é o proprietário da definição do agente, consulte provedor de modelos do Microsoft Foundry. Para implantar um aplicativo do Agent Framework como um agente hospedado, consulte Os Agentes Hospedados do Foundry.

Instalar os pacotes

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

Conectar-se a um Agente de Prompt

Crie um AIProjectClient para o projeto Foundry e envolva um AgentReference como um FoundryAgent. Fixe a versão quando o aplicativo precisar usar uma definição específica do Prompt Agent.

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

var projectClient = new AIProjectClient(
    new Uri(Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")!),
    new DefaultAzureCredential());

FoundryAgent agent = projectClient.AsAIAgent(
    new AgentReference(
        Environment.GetEnvironmentVariable("FOUNDRY_AGENT_NAME")!,
        Environment.GetEnvironmentVariable("FOUNDRY_AGENT_VERSION")!));

Console.WriteLine(await agent.RunAsync("What can you help me with?"));

Você também pode recuperar um ProjectsAgentRecord para usar sua versão mais recente ou uma ProjectsAgentVersion para usar uma versão explicitamente recuperada e, em seguida, passar esse objeto para projectClient.AsAIAgent(...).

Recuperar a versão mais recente do Prompt Agent

Use AgentAdministrationClient quando o aplicativo deve resolver a versão registrada mais recente com base no nome.

ProjectsAgentRecord agentRecord =
    await projectClient.AgentAdministrationClient.GetAgentAsync(
        Environment.GetEnvironmentVariable("FOUNDRY_AGENT_NAME")!);

FoundryAgent latestAgent = projectClient.AsAIAgent(agentRecord);
Console.WriteLine(await latestAgent.RunAsync("What can you help me with?"));

Important

Um FoundryAgent usa o modelo, as instruções e as ferramentas hospedadas armazenadas em sua definição de Foundry. Configure esses recursos na Foundry; o cliente não pode substituí-los em tempo de execução.

Aviso

DefaultAzureCredential é conveniente para o desenvolvimento. Em produção, prefira uma credencial específica como ManagedIdentityCredential para evitar a sondagem indesejada de credenciais.

Conectar-se a um agente hospedado

Os Agentes Hospedados expõem um endpoint OpenAI específico para cada agente. Crie o endpoint a partir do endpoint do projeto e do nome do agente registrado e, em seguida, passe-o para AIProjectClient.AsAIAgent(...).

Env.TraversePath().Load();

// Port the Hosted-* samples listen on when run locally with `dotnet run`.
const int LocalAgentPort = 8088;

// AZURE_AI_AGENT_NAME is the registered server-side agent name.
string agentName = Environment.GetEnvironmentVariable("AZURE_AI_AGENT_NAME")
    ?? throw new InvalidOperationException("AZURE_AI_AGENT_NAME is not set.");

// Pick the server to talk to. `--local` and `--remote` mirror the flag `azd ai agent invoke`
// exposes; with neither, ask at startup.
    ══════════════════════════════════════════════════════════
    """);
Console.ResetColor();
Console.WriteLine();

O seletor de versão controlado pelo administrador do ponto de extremidade determina a versão ativa do Agente Hospedado.

Instalar os pacotes

pip install agent-framework-foundry

Configuration

FOUNDRY_PROJECT_ENDPOINT="https://<your-project>.services.ai.azure.com"
FOUNDRY_AGENT_NAME="my-agent"
FOUNDRY_AGENT_VERSION="1.0"

Use FOUNDRY_AGENT_VERSION para agentes de prompt. Os Agentes Hospedados podem omitê-lo.

Conectar-se a um Agente de Prompt

Forneça o endpoint do projeto, o nome do agente e a versão do agente. O serviço fornece o modelo armazenado, as instruções e a configuração da ferramenta hospedada.

async def main() -> None:
    agent = FoundryAgent(
        project_endpoint="https://your-project.services.ai.azure.com",
        agent_name="my-prompt-agent",
        agent_version="1.0",
        credential=AzureCliCredential(),
    )

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

    # Streaming
    print("Agent (streaming): ", 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()

Se um Prompt Agent declarar uma ferramenta de função local, passe a função chamável correspondente por meio de tools= ao construir FoundryAgent para que o cliente possa executá-la quando solicitado. Consulte o exemplo de publicação e conexão do Prompt Agent.

Conectar-se a um agente hospedado

Os agentes hospedados não exigem agent_version. Conecte-se ao endpoint do projeto e ao nome do agente cadastrado.

async def main() -> None:
    # HostedAgents don't need agent_version
    agent = FoundryAgent(
        project_endpoint=os.getenv("FOUNDRY_PROJECT_ENDPOINT"),
        agent_name=os.getenv("FOUNDRY_AGENT_NAME"),
        credential=AzureCliCredential(),
    )

    result = await agent.run("Summarize the latest news about AI.")
    print(f"Agent: {result}")

O que funciona e o que não funciona com FoundryAgent

FoundryAgent conecta-se a uma definição de agente que já existe no Foundry. As instruções armazenadas e a configuração da ferramenta são autoritativas, portanto, o comportamento do lado do cliente é diferente de um aplicativo de propriedade Agent(client=FoundryChatClient(...)).

Tools

Tipo de ferramenta passado para FoundryAgent(...) Behavior
FunctionToolcom um Python local que pode ser chamado Suportado somente quando a definição de função correspondente já existe no agente Foundry. O callable é executado no processo do aplicativo quando o Foundry o solicita.
Ferramentas hospedadas, incluindo pesquisa na Web, interpretador de código, pesquisa de arquivos, MCP, geração de imagem e caixa de ferramentas Microsoft Foundry Configure isso na definição do agente do Foundry. Passá-los do lado do cliente não os adiciona ao agente gerenciado pelo serviço.

Para obter orientações sobre o anexo do Toolbox e o consumo direto de MCP, consulte Microsoft Foundry Toolbox.

Não é possível registrar uma nova ferramenta visível ao modelo durante a construção. Passar uma função chamável apenas fornece a implementação local de uma função que o agente Foundry já declara.

Provedores de contexto

Comportamento do provedor de contexto Funciona com FoundryAgent?
Adiciona mensagens, como memória recuperada, snippets de RAG ou informações de perfil do usuário Sim. O contexto injetado é encaminhado com a solicitação.
Continua ou observa a conversa Sim. O provedor atua localmente no ciclo de requisição e resposta.
Adiciona ferramentas dinamicamente Não, a menos que essas ferramentas já estejam declaradas na definição do agente Foundry.

Use Agent(client=FoundryChatClient(...)) quando o aplicativo precisar de seleção dinâmica de ferramentas, carregamento de habilidades ou qualquer comportamento que altere as ferramentas visíveis do modelo em tempo de execução.

Opções de execução

Como a definição do agente Foundry é a fonte da verdade, nem todas as opções passadas por default_options ou agent.run(...) são consideradas.

Opção Comportamento do Prompt Agent
model Ignorado. O modelo provém da definição de agente do Foundry.
tools, tool_choice, parallel_tool_calls Removido da solicitação. As ferramentas devem ser declaradas na definição de agente do Foundry.
instructions e mensagens do sistema ou do desenvolvedor Ignorado. As instruções da Foundry armazenadas são as oficiais.
conversation_id Usado e associado à sessão do agente Foundry, quando aplicável.
extra_body Encaminhado e mesclado com a referência de agente fornecida pelo framework.
Parâmetros de amostragem, metadados, user, store e response_format São encaminhados, mas a configuração do agente ou do modelo no Foundry pode substituí-los ou restringi-los.

Os Agentes Hospedados recebem a mesma filtragem do lado do cliente, mas o agente implantado pode aceitar, ignorar ou reinterpretar qualquer opção encaminhada. Verifique o comportamento em relação ao agente hospedado específico.

Tip

Use Agent(client=FoundryChatClient(...)) quando precisar de controle por execução sobre instruções, opções de geração ou ferramentas.

Gerenciar uma sessão de serviço do Agente Hospedado

Agentes hospedados que usam sessões no lado do serviço exigem a interface Responses em versão prévia:

Crie a sessão de serviço explicitamente quando o aplicativo deve associá-la a um locatário ou usuário e, em seguida, encapsular seu identificador como uma sessão do Agent Framework.

    queries = [
        "Hi!",
        "Your name is Javis. What can you do?",
        "What is your name?",
    ]
    for query in queries:
        print(f"\nUser: {query}")
        print("Agent: ", end="", flush=True)
        async for chunk in agent.run(query, session=session, stream=True):
            if chunk.text:
                print(chunk.text, end="", flush=True)
    print()


async def run_service_managed_session(
    *,
    agent: FoundryAgent,
    project_client: AIProjectClient,
    agent_name: str,
) -> None:
    """Let Foundry create the hosted-agent session, then delete it when finished."""
    session = AgentSession()
    print("\nService-managed hosted-agent session")
    print(f"Before first request: {session.state.get(FOUNDRY_HOSTED_AGENT_SESSION_ID_KEY)}")
    try:
        await run_conversation(agent, session)
        print(f"After conversation: {session.state.get(FOUNDRY_HOSTED_AGENT_SESSION_ID_KEY)}")
    finally:
        hosted_session_id = session.state.get(FOUNDRY_HOSTED_AGENT_SESSION_ID_KEY)
        if isinstance(hosted_session_id, str) and hosted_session_id:
            await project_client.agents.delete_session(agent_name, hosted_session_id)
            print(f"Deleted session: {hosted_session_id}")


async def run_user_managed_session(
    *,
    agent: FoundryAgent,
    project_client: AIProjectClient,
    agent_name: str,
    agent_version: str | None,
) -> None:
    """Create, attach, and delete a hosted-agent session explicitly."""
    resolved_agent_version = agent_version
    if resolved_agent_version is None:
        agent_details = await project_client.agents.get(agent_name)
        resolved_agent_version = agent_details.versions.latest.version

    hosted_session = await project_client.agents.create_session(
        agent_name,
        version_indicator=VersionRefIndicator(agent_version=resolved_agent_version),
    )
    session = AgentSession()
    session.state[FOUNDRY_HOSTED_AGENT_SESSION_ID_KEY] = hosted_session.agent_session_id

    print("\nUser-managed hosted-agent session")
    print(f"Created session: {hosted_session.agent_session_id}")
    try:
        await run_conversation(agent, session)
    finally:
        await project_client.agents.delete_session(agent_name, hosted_session.agent_session_id)
        print(f"Deleted session: {hosted_session.agent_session_id}")


async def main() -> None:
    credential = AzureCliCredential()
    project_endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
    agent_name = os.environ["FOUNDRY_AGENT_NAME"]
    agent_version = os.getenv("FOUNDRY_AGENT_VERSION")

    project_client = AIProjectClient(

Tip

Consulte o using_deployed_agent.py exemplo para obter um exemplo completo.

Definir um tempo limite HTTP personalizado

FoundryAgent herda o tempo limite do SDK da OpenAI por padrão. Passe timeout= em segundos quando conversas de vários turnos ou condições de rede exigem um limite diferente.

from agent_framework.foundry import FoundryAgent
from azure.identity import AzureCliCredential

agent = FoundryAgent(
    project_endpoint="https://your-project.services.ai.azure.com",
    agent_name="my-prompt-agent",
    credential=AzureCliCredential(),
    timeout=120.0,
)

O tempo limite é aplicado a uma cópia por agente do cliente HTTP e não afeta outros agentes que compartilham o mesmo AIProjectClient.

Note

FoundryAgent no momento, a integração de Prompt e Agentes Hospedados não está disponível para o Agent Framework Go. Consulte o repositório Agent Framework Go para obter o status mais recente.

Iniciar, transmitir e continuar conversas

Depois de se conectar, use as mesmas APIs que outros agentes do Agent Framework:

  • Executar uma solicitação com RunAsync ou run.
  • Transmitir atualizações com RunStreamingAsync ou run(..., stream=True).
  • Reutilize um AgentSession para continuar uma conversa.
  • Use as APIs de conversação do servidor do Foundry quando a conversa precisar estar visível e persistida no projeto Foundry.

Mantenha os nomes dos agentes do Foundry, as versões, os endpoints e os identificadores de conversação em um estado confiável no servidor. Autorize o chamador antes de retomar qualquer conversa existente.

Próximas Etapas 

Examinar o provedor de modelos do Microsoft Foundry

  • Last updated on