Servicio Microsoft Foundry Agent

FoundryAgent conecta Agent Framework con una definición de agente administrada por Microsoft Foundry Agent Service. El modelo del agente, las instrucciones, las herramientas hospedadas y la versión se configuran en Foundry; La aplicación se conecta a esa definición y usa las API de ejecución, streaming y sesión estándar de Agent Framework.

Use esta integración para:

  • Agentes de prompt, que son definiciones de agentes en el lado del servidor con nombre y versión.
  • Agentes hospedados, aplicaciones de agente implementadas a las que se accede mediante un punto de conexión específico del agente.

Para la inferencia directa del modelo, si la definición del agente pertenece a su aplicación, consulte proveedor de modelos de Microsoft Foundry. Para implementar una aplicación de Agent Framework como agente hospedado, consulte Agentes hospedados de Foundry.

Instalación de los paquetes

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

Conéctate a Prompt Agent

Cree un AIProjectClient para el proyecto Foundry y envuelva un AgentReference como FoundryAgent. Fije la versión cuando la aplicación deba usar una definición 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?"));

También puede recuperar ProjectsAgentRecord para usar su versión más reciente o ProjectsAgentVersion para usar una versión recuperada explícitamente y, a continuación, pasar ese objeto a projectClient.AsAIAgent(...).

Obtener la versión más reciente de Prompt Agent

Use AgentAdministrationClient cuando la aplicación deba resolver la versión registrada más reciente por nombre.

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

Un FoundryAgent usa el modelo, las instrucciones y las herramientas alojadas almacenados en su definición de Foundry. Configure esas funcionalidades en Foundry; el cliente no puede reemplazarlos en tiempo de ejecución.

Warning

DefaultAzureCredential es conveniente para el desarrollo. En producción, prefiera una credencial específica, como ManagedIdentityCredential para evitar sondeos de credenciales no deseados.

Conexión a un agente hospedado

Los agentes hospedados exponen un punto de conexión de OpenAI específico del agente. Construya el punto de conexión a partir del punto de conexión del proyecto y del nombre del agente registrado y, a continuación, páselo a 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();

El selector de versiones controlada por el administrador del punto de conexión determina la versión activa del agente hospedado.

Instalación de los paquetes

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"

Usa FOUNDRY_AGENT_VERSION para agentes de entrada. Los agentes hospedados pueden omitirlo.

Conéctate a un Agente de Prompt

Proporcione el punto de conexión del proyecto, el nombre del agente y la versión del agente. El servicio proporciona el modelo almacenado, las instrucciones y la configuración de la herramienta 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()

Si un Prompt Agent declara una herramienta de función local, pase el elemento invocable correspondiente a través de tools= al construir FoundryAgent para que el cliente pueda ejecutarlo cuando se solicite. Consulte el ejemplo de publicación y conexión de Prompt Agent.

Conexión a un agente hospedado

Los agentes hospedados no requieren agent_version. Conéctese con el punto de conexión del proyecto y el nombre del 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}")

Lo que funciona y lo que no funciona con FoundryAgent

FoundryAgent se conecta a una definición de agente que ya existe en Foundry. Las instrucciones almacenadas y la configuración de herramientas son autoritativas, por lo que el comportamiento del lado cliente difiere de un propiedad de la aplicación Agent(client=FoundryChatClient(...)).

Tools

Tipo de herramienta pasado a FoundryAgent(...) Comportamiento
FunctionToolcon un Python local al que se puede llamar Solo se admite cuando la definición de función coincidente ya existe en el agente foundry. El invocable se ejecuta en el proceso de aplicación cuando Foundry lo solicita.
Herramientas hospedadas, como búsqueda web, intérprete de código, búsqueda de archivos, MCP, generación de imágenes y Microsoft Foundry Toolbox Configure estos elementos en la definición del agente de Foundry. Pasarlos desde el lado del cliente no los agrega al agente administrado por el servicio.

Para obtener información sobre la integración con Toolbox y la guía sobre el consumo directo de MCP, consulte Microsoft Foundry Toolbox.

No se puede registrar una nueva herramienta visible para el modelo en tiempo de construcción. Pasar una función invocable solo proporciona la implementación local para una función que el agente foundry ya declara.

Proveedores de contexto

Comportamiento del proveedor de contexto Funciona con FoundryAgent?
Agrega mensajes, como la memoria recuperada, fragmentos de código RAG o información de perfil de usuario. Yes. El contexto inyectado se reenvía con la solicitud.
Mantiene o observa la conversación Yes. El proveedor se ejecuta de forma local en torno a la solicitud y la respuesta.
Agrega herramientas dinámicamente No, salvo que esas herramientas ya estén declaradas en la definición del agente de Foundry.

Use Agent(client=FoundryChatClient(...)) cuando la aplicación necesite selección dinámica de herramientas, carga de aptitudes o cualquier comportamiento que cambie las herramientas visibles para el modelo en tiempo de ejecución.

Opciones de ejecución

Dado que la definición del agente de Foundry es la fuente autorizada, no todas las opciones pasadas mediante default_options o agent.run(...) se aplican.

Option Comportamiento del agente de prompt
model ignorado. El modelo proviene de la definición del agente Foundry.
tools, , tool_choice, parallel_tool_calls Se ha eliminado de la solicitud. Las herramientas deben declararse en la definición del agente Foundry.
instructions y mensajes del sistema o del desarrollador ignorado. Las instrucciones de Foundry almacenadas son autoritativas.
conversation_id Se usa y se vincula con la sesión del agente Foundry cuando corresponda.
extra_body Reenviado y fusionado con la referencia del agente proporcionada por el framework.
Parámetros de muestreo, metadatos, user, storey response_format Reenviadas, pero el agente de Foundry o la configuración del modelo pueden anularlas o restringirlas.

Los agentes hospedados reciben el mismo filtrado del lado cliente, pero el agente implementado puede aceptar, omitir o reinterpretar cualquier opción reenviada. Verifique el comportamiento respecto al Agente hospedado específico.

Tip

Use Agent(client=FoundryChatClient(...)) cuando necesite controlar por ejecución instrucciones, opciones de generación o herramientas.

Administración de una sesión de servicio del agente hospedado

Los agentes hospedados que utilizan sesiones del lado del servicio requieren la interfaz de Responses en vista previa:

Cree la sesión de servicio explícitamente cuando la aplicación debe enlazarla a un inquilino o usuario y, a continuación, encapsular su identificador como una sesión de 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 el using_deployed_agent.py ejemplo para obtener un ejemplo completo.

Establecimiento de un tiempo de espera HTTP personalizado

FoundryAgent hereda el tiempo de espera del SDK de OpenAI de forma predeterminada. Indique timeout= en segundos cuando las conversaciones de varios turnos o las condiciones de la red requieran un límite 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,
)

El tiempo de espera se aplica a una copia por agente del cliente HTTP y no afecta a otros agentes que comparten el mismo AIProjectClient.

Note

FoundryAgent La integración de Prompt y Hosted Agents no está disponible actualmente para Agent Framework Go. Consulte el repositorio de Agent Framework Go para obtener el estado más reciente.

Inicia, transmite y continúa las conversaciones

Después de conectarse, use las mismas API que otros agentes de Agent Framework:

  • Ejecute una solicitud con RunAsync o run.
  • Transmita actualizaciones con RunStreamingAsync o run(..., stream=True).
  • Reutilice un AgentSession para continuar una conversación.
  • Utilice las API de conversación del servidor de Foundry cuando la conversación deba ser visible y persistir en el proyecto de Foundry.

Mantener los nombres de los agentes de Foundry, las versiones, los extremos y los identificadores de conversación en un estado de confianza del lado del servidor. Autorice al autor de la llamada antes de reanudar cualquier conversación existente.

Pasos siguientes

Revisión del proveedor de modelos Microsoft Foundry

  • Last updated on