Serviço do Microsoft Foundry Agent

FoundryAgentconecta o Agent Framework a uma definição de agente gerenciada por Microsoft Serviço do Foundry Agent. 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 de agente do lado do servidor nomeadas e com controle de versão.
• Agentes hospedados, que são aplicativos de agente implantados acessados por meio de um ponto de extremidade específico do agente.

Para obter inferência de modelo direto em que seu aplicativo é proprietário da definição do agente, consulte Microsoft provedor de modelos do 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 embrulhe 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 mais recente registrada 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

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.

Warning

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

Conectar-se a um agente hospedado

Os Agentes Hospedados expõem um ponto de extremidade OpenAI específico do agente. Crie o ponto de extremidade do ponto de extremidade do projeto e o 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 ponto de extremidade 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 o callable correspondente ao tools= construir FoundryAgent para que o cliente possa executá-lo 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 com o ponto de extremidade do projeto e o nome do agente registrado.

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	Compatível somente quando a definição de função correspondente já existir 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-os na definição do agente foundry. Passá-los do lado do cliente não os adiciona ao agente gerenciado pelo serviço.

Para obter o anexo da Caixa de Ferramentas e as diretrizes diretas de consumo do MCP, consulte Microsoft Caixa de Ferramentas do Foundry.

Não é possível registrar uma nova ferramenta visível para modelo no momento da construção. Passar uma função que pode ser chamada apenas fornece a implementação local para 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.
Persiste ou observe a conversa	Sim. O provedor é executado localmente em torno da solicitação e da 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 default_options ou agent.run(...) são respeitadas.

Opção	Comportamento do Prompt Agent
model	Ignorado. O modelo vem da definição do agente foundry.
tools, , tool_choiceparallel_tool_calls	Removido da solicitação. As ferramentas devem ser declaradas na definição do agente foundry.
instructions e mensagens do sistema ou do desenvolvedor	Ignorado. As instruções armazenadas da Foundry são autoritativas.
conversation_id	Usado e mapeado para a sessão do agente foundry quando aplicável.
extra_body	Encaminhado e mesclado com a referência de agente fornecida pela estrutura.
Parâmetros de amostragem, metadados e userstoreresponse_format	Encaminhado, mas a configuração de modelo ou agente do 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.

Dica

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

Os Agentes Hospedados que usam sessões do lado do serviço exigem a superfície de respostas de visualização:

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(

Dica

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 do 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.

Executar, 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 do lado do servidor do Foundry quando a conversa deve estar visível e persistida no projeto Foundry.

Mantenha os nomes, versões, pontos de extremidade e identificadores de conversa do agente do Foundry no estado do servidor confiável. Autorize o chamador antes de retomar qualquer conversa existente.

Próximas Etapas 

Examinar o provedor de modelos do Microsoft Foundry