Serviço de Agente da Microsoft Foundry

FoundryAgentliga o Agent Framework a uma definição de agente gerida pelo Microsoft Foundry Agent Service. O modelo, as instruções, as ferramentas alojadas e a versão do agente são configurados no Foundry; a sua aplicação liga-se a essa definição e utiliza as APIs padrão de execução, streaming e sessão do Agent Framework.

Use esta integração para:

• Prompt Agents, que são definições de agentes do lado do servidor nomeadas e versionadas.
• Agentes Hospedados, que são aplicações de agente implementadas acessadas através de um endpoint específico de cada agente.

Para inferência direta de modelos onde a sua aplicação detém a definição do agente, consulte Microsoft Foundry model provider. Para implementar uma aplicação Agent Framework como Agente Hospedado, consulte Foundry Hosted Agents.

Instale os pacotes

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

Liga-te a um Agente de Prompts

Crie um AIProjectClient para o projeto Foundry e envolva um AgentReference como um FoundryAgent. Fixe a versão quando a aplicação tiver de usar uma definição específica de 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?"));

Também pode recuperar um ProjectsAgentRecord para usar a sua versão mais recente ou para ProjectsAgentVersion usar uma versão explicitamente recuperada, e depois passar esse objeto para projectClient.AsAIAgent(...).

Recuperar a versão mais recente do Prompt Agent

Use AgentAdministrationClient quando a aplicação deve resolver a versão registada mais recente pelo 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?"));

Importante

A FoundryAgent utiliza o modelo, as instruções e as ferramentas alojadas armazenadas na sua definição Foundry. Configure essas capacidades no Foundry; O cliente não pode substituí-los em tempo de execução.

Warning

DefaultAzureCredential é conveniente para o desenvolvimento. Na produção, prefira uma credencial específica, como ManagedIdentityCredential evitar sondagens não intencionais da credencial.

Liga-te a um Agente Alojado

Os Agentes Alojados expõem um endpoint OpenAI específico para agente. Constrói o endpoint a partir do endpoint do projeto e do nome do agente registado, depois passa-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ões controlado pelo administrador do endpoint determina a versão ativa do Agente Hospedado.

Instale 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"

Utilize FOUNDRY_AGENT_VERSION para os Agentes de Prompt. Os Agentes Alojados podem omitir isso.

Liga-te a um Agente de Prompts

Forneça o endpoint do projeto, nome do agente e 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 chamada tools= correspondente ao construir FoundryAgent para que o cliente a possa executar quando solicitado. Consulte o exemplo do Prompt Agent, publique e conecte.

Liga-te a um Agente Alojado

Os Agentes Hospedados não exigem agent_version. Liga-te ao endpoint do projeto e ao nome do agente registado.

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 liga-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, pelo que o comportamento do lado do cliente difere de um Agent(client=FoundryChatClient(...)).

Tools

Tipo de ferramenta transmitido a FoundryAgent(...)	Comportamento
FunctionToolcom um chamável local em Python	Suportado apenas quando a definição da função de correspondência já existe no agente Foundry. O chamável é executado no processo de candidatura quando o Foundry o solicita.
Ferramentas alojadas, incluindo pesquisa web, interpretador de código, pesquisa de ficheiros, MCP, geração de imagens e Microsoft Foundry Toolbox	Configure-os na definição de agente Foundry. Passá-los do lado do cliente não os adiciona ao agente de serviço gerido.

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

Não podes registar uma nova ferramenta visível ao modelo na altura da construção. Passar uma função chamável apenas fornece a implementação local para uma função que o agente Foundry já declara.

Fornecedores de contexto

Comportamento do fornecedor de contexto	Funciona com FoundryAgent?
Adiciona mensagens, como memória recuperada, excertos RAG ou informações de perfil de utilizador	Yes. O contexto injetado é encaminhado juntamente com o pedido.
Persiste ou observa a conversa	Yes. O prestador gere-se localmente em torno do pedido e da resposta.
Adiciona ferramentas dinamicamente	Não, a menos que essas ferramentas já estejam declaradas na definição de agente da Foundry.

Use Agent(client=FoundryChatClient(...)) quando a aplicação precisa de seleção dinâmica de ferramentas, carregamento de competências ou qualquer comportamento que altere ferramentas visíveis ao modelo em tempo de execução.

Opções de execução

Como a definição de agente da Foundry é a fonte da verdade, nem todas as opções passam ou default_optionsagent.run(...) são respeitadas.

Option	Comportamento do Prompt Agent
model	Ignorado. O modelo deriva da definição de agente Foundry.
tools, tool_choice, parallel_tool_calls	Removido do pedido. As ferramentas devem ser declaradas na definição de agente da Foundry.
instructions e mensagens do sistema ou do programador	Ignorado. As instruções armazenadas do Foundry são autoritativas.
conversation_id	Usado e mapeado para a sessão do agente Foundry quando aplicável.
extra_body	Encaminhado e fundido com a referência do agente fornecida pelo framework.
Parâmetros de amostragem, metadados, user, store, e response_format	Encaminhados, mas o agente Foundry ou a configuração do modelo podem sobrepê-los ou restringi-los.

Os Agentes Alojados recebem a mesma filtragem do lado do cliente, mas o agente implementado pode aceitar, ignorar ou reinterpretar qualquer opção encaminhada. Verifica o comportamento em relação ao Agente Alojado específico.

Tip

Usa Agent(client=FoundryChatClient(...)) quando precisares de controlo por execução sobre instruções, opções de geração ou ferramentas.

Gerir uma sessão de serviço de Agente Alojado

Os Agentes Alojados que utilizam sessões do lado do serviço requerem a superfície de pré-visualização:

Crie explicitamente a sessão de serviço quando a aplicação tiver de a vincular a um inquilino ou utilizador, e depois envolva o 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

Veja o using_deployed_agent.py exemplo para um exemplo completo.

Defina um timeout HTTP personalizado

FoundryAgent herda o timeout do SDK OpenAI por defeito. Passa timeout= em segundos quando conversas com múltiplas curvas 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 timeout é aplicado a uma cópia por agente do cliente HTTP e não afeta outros agentes que partilhem o AIProjectClientmesmo.

Observação

FoundryAgent a integração para Prompt e Agentes Hospedados não está atualmente disponível para o Agent Framework Go. Consulte o repositório Agent Framework Go para o estado mais recente.

Corre, transmite e continua conversas

Após a ligação, use as mesmas APIs que outros agentes do Agent Framework:

• Execute um pedido com RunAsync ou run.
• Atualizações de stream com RunStreamingAsync ou run(..., stream=True).
• Reutilizar e AgentSession continuar uma conversa.
• Use as APIs de conversa do lado do servidor do Foundry quando a conversa tiver de ser visível e persistir no projeto Foundry.

Mantenha os nomes dos agentes Foundry, versões, endpoints e identificadores de conversa no estado confiável do lado do servidor. Autorize o interlocutor antes de retomar qualquer conversa existente.

Passos seguintes

Analisar o fornecedor de modelos Microsoft Foundry