Servicio Microsoft Foundry Agent

FoundryAgentconecta Agent Framework a una definición de agente administrada por Microsoft servicio de agente foundry. 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:

• Preguntar agentes, que se denominan y tienen versiones de definiciones de agente del lado servidor.
• Agentes hospedados, que se implementan aplicaciones de agente a través de un punto de conexión específico del agente.

Para obtener inferencia directa del modelo donde su aplicación posee la definición del agente, consulte Microsoft proveedor de modelos 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

Conexión a un agente de solicitud

Cree un AIProjectClient para el proyecto Foundry y encapsula un AgentReference como .FoundryAgent Ancle la versión cuando la aplicación debe usar una definición específica del Agente de solicitud.

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(...).

Recuperación de la versión más reciente del agente del símbolo del sistema

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?"));

Importante

Usa FoundryAgent el modelo, las instrucciones y las herramientas hospedadas almacenadas 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. Compile el punto de conexión desde el punto de conexión del proyecto y el 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.

Conexión a un agente de solicitud

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 Agente de solicitud declara una herramienta de función local, pase la coincidencia invocable a través tools= de al construir FoundryAgent para que el cliente pueda ejecutarla cuando se solicite. Consulte el ejemplo de publicación y conexión del agente de solicitud.

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 foundry. Pasarles el lado cliente no los agrega al agente administrado por el servicio.

Para obtener información sobre los datos adjuntos del cuadro de herramientas y la guía de 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.
Conserva o observa la conversación	Yes. El proveedor se ejecuta localmente alrededor de la solicitud y la respuesta.
Agrega herramientas dinámicamente	No, a menos que esas herramientas ya estén declaradas en la definición del agente 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 foundry es la fuente de la verdad, no todas las opciones pasadas default_options o agent.run(...) se respetan.

Option	Comportamiento del agente de solicitud
model	ignorado. El modelo procede de la definición del agente foundry.
tools, , tool_choice, parallel_tool_calls	Se ha quitado 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 asigna a la sesión del agente foundry cuando procede.
extra_body	Reenviado y combinado con la referencia del agente proporcionado por el marco.
Parámetros de muestreo, metadatos, user, storey response_format	Reenviado, pero la configuración del agente o modelo de Foundry puede invalidarlas 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. Compruebe el comportamiento con el 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 usan sesiones del lado del servicio requieren la superficie de respuestas en versión preliminar:

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. Pase timeout= segundos cuando las conversaciones multiturno o las condiciones de 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.

Ejecutar, transmitir y continuar 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).
• Vuelva a usar para AgentSession continuar una conversación.
• Use las API de conversación del lado servidor foundry cuando la conversación debe estar visible y persistente en el proyecto Foundry.

Mantenga los nombres, las versiones, los puntos de conexión y los identificadores de conversación de Foundry en estado de servidor de confianza. Autorice al autor de la llamada antes de reanudar cualquier conversación existente.

Pasos siguientes

Revisión del proveedor de modelos Microsoft Foundry