Agentes de Azure AI Foundry

Introducción

Agregue los paquetes NuGet necesarios al proyecto.

dotnet add package Azure.Identity
dotnet add package Microsoft.Agents.AI.AzureAI.Persistent --prerelease

Creación de agentes de Azure AI Foundry

Como primer paso, debe crear un cliente para conectarse al servicio Azure AI Foundry Agents.

using System;
using Azure.AI.Agents.Persistent;
using Azure.Identity;
using Microsoft.Agents.AI;

var persistentAgentsClient = new PersistentAgentsClient(
    "https://<myresource>.services.ai.azure.com/api/projects/<myproject>",
    new AzureCliCredential());

Para usar el servicio Azure AI Foundry Agents, necesita crear un recurso de agente en el servicio. Esto se puede hacer mediante el SDK Azure.AI.Agents.Persistent o con los asistentes de Microsoft Agent Framework.

Uso del SDK persistente

Cree un agente persistente y recupérelo como un AIAgent mediante el PersistentAgentsClient.

// Create a persistent agent
var agentMetadata = await persistentAgentsClient.Administration.CreateAgentAsync(
    model: "gpt-4o-mini",
    name: "Joker",
    instructions: "You are good at telling jokes.");

// Retrieve the agent that was just created as an AIAgent using its ID
AIAgent agent1 = await persistentAgentsClient.GetAIAgentAsync(agentMetadata.Value.Id);

// Invoke the agent and output the text result.
Console.WriteLine(await agent1.RunAsync("Tell me a joke about a pirate."));

Uso de los asistentes de Agent Framework

También puede crear y devolver un AIAgent en un solo paso:

AIAgent agent2 = await persistentAgentsClient.CreateAIAgentAsync(
    model: "gpt-4o-mini",
    name: "Joker",
    instructions: "You are good at telling jokes.");

Reutilización de agentes de Azure AI Foundry

Puede reutilizar los agentes de Azure AI Foundry existentes mediante su recuperación mediante sus identificadores.

AIAgent agent3 = await persistentAgentsClient.GetAIAgentAsync("<agent-id>");

Uso del agente

El agente es un AIAgent estándar y admite todas las operaciones estándar AIAgent.

Consulte los tutoriales de introducción del agente para obtener más información sobre cómo ejecutar e interactuar con agentes.

Configuración

Variables de entorno

Antes de usar Azure AI Foundry Agents, debe configurar estas variables de entorno:

export AZURE_AI_PROJECT_ENDPOINT="https://<your-project>.services.ai.azure.com/api/projects/<project-id>"
export AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-4o-mini"

Como alternativa, puede proporcionar estos valores directamente en el código.

Installation

Agregue el paquete de Azure AI de Agent Framework al proyecto:

pip install agent-framework-azure-ai --pre

Introducción

Autenticación

Los agentes de Azure AI Foundry usan credenciales de Azure para la autenticación. El enfoque más sencillo es usar AzureCliCredential después de ejecutar az login:

from azure.identity.aio import AzureCliCredential

async with AzureCliCredential() as credential:
    # Use credential with Azure AI agent client

Creación de agentes de Azure AI Foundry

Creación básica del agente

La manera más sencilla de crear un agente es usar el AzureAIAgentClient con variables de entorno:

import asyncio
from agent_framework.azure import AzureAIAgentClient
from azure.identity.aio import AzureCliCredential

async def main():
    async with (
        AzureCliCredential() as credential,
        AzureAIAgentClient(async_credential=credential).create_agent(
            name="HelperAgent",
            instructions="You are a helpful assistant."
        ) as agent,
    ):
        result = await agent.run("Hello!")
        print(result.text)

asyncio.run(main())

Configuración explícita

También puede proporcionar la configuración explícitamente en lugar de usar variables de entorno:

import asyncio
from agent_framework.azure import AzureAIAgentClient
from azure.identity.aio import AzureCliCredential

async def main():
    async with (
        AzureCliCredential() as credential,
        AzureAIAgentClient(
            project_endpoint="https://<your-project>.services.ai.azure.com/api/projects/<project-id>",
            model_deployment_name="gpt-4o-mini",
            async_credential=credential,
            agent_name="HelperAgent"
        ).create_agent(
            instructions="You are a helpful assistant."
        ) as agent,
    ):
        result = await agent.run("Hello!")
        print(result.text)

asyncio.run(main())

Uso de agentes de Azure AI Foundry existentes

Uso de un agente existente mediante su identificación por ID

Si tiene un agente existente en Azure AI Foundry, puede usarlo proporcionando su identificador:

import asyncio
from agent_framework import ChatAgent
from agent_framework.azure import AzureAIAgentClient
from azure.identity.aio import AzureCliCredential

async def main():
    async with (
        AzureCliCredential() as credential,
        ChatAgent(
            chat_client=AzureAIAgentClient(
                async_credential=credential,
                agent_id="<existing-agent-id>"
            ),
            instructions="You are a helpful assistant."
        ) as agent,
    ):
        result = await agent.run("Hello!")
        print(result.text)

asyncio.run(main())

Creación y administración de agentes persistentes

Para obtener más control sobre el ciclo de vida del agente, puede crear agentes persistentes mediante el cliente de proyectos de Azure AI:

import asyncio
import os
from agent_framework import ChatAgent
from agent_framework.azure import AzureAIAgentClient
from azure.ai.projects.aio import AIProjectClient
from azure.identity.aio import AzureCliCredential

async def main():
    async with (
        AzureCliCredential() as credential,
        AIProjectClient(
            endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
            credential=credential
        ) as project_client,
    ):
        # Create a persistent agent
        created_agent = await project_client.agents.create_agent(
            model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
            name="PersistentAgent",
            instructions="You are a helpful assistant."
        )

        try:
            # Use the agent
            async with ChatAgent(
                chat_client=AzureAIAgentClient(
                    project_client=project_client,
                    agent_id=created_agent.id
                ),
                instructions="You are a helpful assistant."
            ) as agent:
                result = await agent.run("Hello!")
                print(result.text)
        finally:
            # Clean up the agent
            await project_client.agents.delete_agent(created_agent.id)

asyncio.run(main())

Características del agente

Herramientas de funciones

Puede proporcionar herramientas de función personalizadas a agentes de Azure AI Foundry:

import asyncio
from typing import Annotated
from agent_framework.azure import AzureAIAgentClient
from azure.identity.aio import AzureCliCredential
from pydantic import Field

def get_weather(
    location: Annotated[str, Field(description="The location to get the weather for.")],
) -> str:
    """Get the weather for a given location."""
    return f"The weather in {location} is sunny with a high of 25°C."

async def main():
    async with (
        AzureCliCredential() as credential,
        AzureAIAgentClient(async_credential=credential).create_agent(
            name="WeatherAgent",
            instructions="You are a helpful weather assistant.",
            tools=get_weather
        ) as agent,
    ):
        result = await agent.run("What's the weather like in Seattle?")
        print(result.text)

asyncio.run(main())

Intérprete de código

Los agentes de Azure AI Foundry admiten la ejecución de código mediante el intérprete de código hospedado:

import asyncio
from agent_framework import HostedCodeInterpreterTool
from agent_framework.azure import AzureAIAgentClient
from azure.identity.aio import AzureCliCredential

async def main():
    async with (
        AzureCliCredential() as credential,
        AzureAIAgentClient(async_credential=credential).create_agent(
            name="CodingAgent",
            instructions="You are a helpful assistant that can write and execute Python code.",
            tools=HostedCodeInterpreterTool()
        ) as agent,
    ):
        result = await agent.run("Calculate the factorial of 20 using Python code.")
        print(result.text)

asyncio.run(main())

Respuestas de streaming

Obtenga respuestas a medida que se generan mediante streaming:

import asyncio
from agent_framework.azure import AzureAIAgentClient
from azure.identity.aio import AzureCliCredential

async def main():
    async with (
        AzureCliCredential() as credential,
        AzureAIAgentClient(async_credential=credential).create_agent(
            name="StreamingAgent",
            instructions="You are a helpful assistant."
        ) as agent,
    ):
        print("Agent: ", end="", flush=True)
        async for chunk in agent.run_stream("Tell me a short story"):
            if chunk.text:
                print(chunk.text, end="", flush=True)
        print()

asyncio.run(main())

Uso del agente

El agente es un estándar BaseAgent y admite todas las operaciones estándar.

Consulte los tutoriales de introducción del agente para obtener más información sobre cómo ejecutar e interactuar con agentes.