Microsoft Foundry Agentendienst

De pakketten installeren

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

Verbinding maken met een promptagent

Maak een AIProjectClient voor het Foundry-project en verpakt een AgentReference als een FoundryAgent. Maak de versie vast wanneer de toepassing een specifieke promptagentdefinitie moet gebruiken.

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

U kunt ook een ProjectsAgentRecord bestand ophalen om de nieuwste versie te gebruiken of een ProjectsAgentVersion om een expliciet opgehaalde versie te gebruiken en dat object vervolgens door te geven aan projectClient.AsAIAgent(...).

De meest recente promptagentversie ophalen

Gebruik AgentAdministrationClient deze opdracht wanneer de toepassing de meest recente geregistreerde versie op naam moet oplossen.

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

Verbinding maken met een gehoste agent

Gehoste agents maken een agentspecifiek OpenAI-eindpunt beschikbaar. Bouw het eindpunt op basis van het projecteindpunt en de naam van de geregistreerde agent en geef het vervolgens door aan 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();

De door de beheerder beheerde versiekiezer van het eindpunt bepaalt de actieve versie van de gehoste agent.

De pakketten installeren

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"

Gebruik FOUNDRY_AGENT_VERSION voor promptagents. Gehoste agents kunnen deze weglaten.

Verbinding maken met een promptagent

Geef het projecteindpunt, de naam van de agent en de agentversie op. De service levert het opgeslagen model, de instructies en de configuratie van het gehoste hulpprogramma.

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

Als een promptagent een lokaal functiehulpprogramma declareert, geeft u de overeenkomende functie door die kan tools= worden aangeroepen bij het samenstellen FoundryAgent , zodat de client deze kan uitvoeren wanneer dit wordt aangevraagd. Zie het voorbeeld promptagent publiceren en verbinden.

Verbinding maken met een gehoste agent

Gehoste agents hebben geen behoefte agent_version. Maak verbinding met het projecteindpunt en de naam van de geregistreerde agent.

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

Wat werkt en wat niet met FoundryAgent

FoundryAgent maakt verbinding met een agentdefinitie die al bestaat in Foundry. De opgeslagen instructies en configuratie van hulpprogramma's zijn gezaghebbend, dus gedrag aan de clientzijde verschilt van een toepassingseigendom Agent(client=FoundryChatClient(...)).

Gereedschappen

Zie Microsoft Foundry Toolbox voor hulp bij bijlage en directe MCP-verbruiksrichtlijnen.

U kunt geen nieuw model zichtbaar gereedschap registreren tijdens de bouw. Het doorgeven van een functie die kan worden aangeroepen, levert alleen de lokale implementatie voor een functie die de Foundry-agent al declareert.

Contextproviders

Gebruik Agent(client=FoundryChatClient(...)) wanneer de toepassing dynamische hulpprogramma's moet selecteren, laden van vaardigheden of gedrag dat model zichtbare hulpprogramma's tijdens runtime wijzigt.

Uitvoeringsopties

Omdat de definitie van de Foundry-agent de bron van waarheid is, wordt niet elke optie doorgegeven default_options of agent.run(...) gehonoreerd.

Gehoste agents ontvangen hetzelfde filter aan de clientzijde, maar de geïmplementeerde agent kan elke doorgestuurde optie accepteren, negeren of opnieuw interpreteren. Controleer het gedrag van de specifieke gehoste agent.

Een gehoste agentservicesessie beheren

Gehoste agents die gebruik maken van sessies aan de servicezijde, vereisen het surface voor preview-antwoorden:

Maak de servicesessie expliciet wanneer de toepassing deze moet binden aan een tenant of gebruiker, en verpakt de id vervolgens als een Agent Framework-sessie.

    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(

Een aangepaste HTTP-time-out instellen

FoundryAgent neemt standaard de time-out van de OpenAI SDK over. Geef timeout= in seconden door wanneer gesprekken met meerdere paden of netwerkvoorwaarden een andere limiet vereisen.

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

De time-out wordt toegepast op een kopie per agent van de HTTP-client en heeft geen invloed op andere agents die hetzelfde AIProjectClientdelen.