Service d'agent Microsoft Foundry

Installer les packages

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

Se connecter à un agent d’invite

Créez un AIProjectClient fichier pour le projet Foundry et encapsulez-en tant AgentReference que FoundryAgent. Épinglez la version lorsque l’application doit utiliser une définition d’Agent d’invite spécifique.

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

Vous pouvez également récupérer un ProjectsAgentRecord pour utiliser sa dernière version ou pour ProjectsAgentVersion utiliser une version récupérée explicitement, puis passer cet objet à projectClient.AsAIAgent(...).

Récupérer la dernière version de l’agent d’invite

Utilisez AgentAdministrationClient cette option lorsque l’application doit résoudre la dernière version inscrite par nom.

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

Se connecter à un agent hébergé

Les agents hébergés exposent un point de terminaison OpenAI spécifique à un agent. Générez le point de terminaison à partir du point de terminaison du projet et du nom de l’agent inscrit, puis passez-le à 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();

Le sélecteur de version contrôlé par l’administrateur du point de terminaison détermine la version active de l’agent hébergé.

Installer les packages

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"

Utiliser FOUNDRY_AGENT_VERSION pour les agents d’invite. Les agents hébergés peuvent l’omettre.

Se connecter à un agent d’invite

Fournissez le point de terminaison du projet, le nom de l’agent et la version de l’agent. Le service fournit le modèle stocké, les instructions et la configuration de l’outil hébergé.

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 agent d’invite déclare un outil de fonction local, transmettez l’appelant tools= correspondant lors de la construction FoundryAgent afin que le client puisse l’exécuter quand il est demandé. Consultez l’exemple de publication et de connexion de l’agent d’invite.

Se connecter à un agent hébergé

Les agents hébergés ne nécessitent agent_versionpas . Connectez-vous avec le point de terminaison du projet et le nom de l’agent inscrit.

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}")

Ce qui fonctionne et ce qui ne fonctionne pas avec FoundryAgent

FoundryAgent se connecte à une définition d’agent qui existe déjà dans Foundry. Les instructions stockées et la configuration de l’outil font autorité, de sorte que le comportement côté client diffère d’une application appartenant à Agent(client=FoundryChatClient(...))une application.

Tools

Pour obtenir des instructions sur la pièce jointe de la boîte à outils et la consommation directe de MCP, consultez Microsoft Boîte à outils Foundry.

Vous ne pouvez pas inscrire un nouvel outil visible par modèle au moment de la construction. Le passage d’une fonction pouvant être appelée fournit uniquement l’implémentation locale d’une fonction que l’agent Foundry déclare déjà.

Fournisseurs de contexte

Utilisez Agent(client=FoundryChatClient(...)) quand l’application a besoin d’une sélection d’outils dynamiques, d’un chargement de compétences ou d’un comportement qui modifie les outils visibles par le modèle au moment de l’exécution.

Options d’exécution

Étant donné que la définition de l’agent Foundry est la source de la vérité, toutes les options transmises default_options ou agent.run(...) sont respectées.

Les agents hébergés reçoivent le même filtrage côté client, mais l’agent déployé peut accepter, ignorer ou réinterpreter n’importe quelle option transférée. Vérifiez le comportement par rapport à l’agent hébergé spécifique.

Gérer une session de service Agent hébergé

Les agents hébergés qui utilisent des sessions côté service nécessitent l’aire d’aperçu des réponses :

Créez explicitement la session de service lorsque l’application doit la lier à un locataire ou à un utilisateur, puis encapsulez son identificateur en tant que session 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(

Définir un délai d’expiration HTTP personnalisé

FoundryAgent hérite du délai d’expiration du Kit de développement logiciel (SDK) OpenAI par défaut. Passez en secondes timeout= lorsque les conversations multitours ou les conditions réseau nécessitent une limite différente.

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,
)

Le délai d’expiration est appliqué à une copie par agent du client HTTP et n’affecte pas les autres agents qui partagent le même AIProjectClient.