Servizio Microsoft Foundry Agent

FoundryAgentconnette Agent Framework a una definizione dell'agente gestita da Microsoft servizio agente Foundry. Il modello, le istruzioni, gli strumenti ospitati e la versione dell'agente sono configurati in Foundry; l'applicazione si connette a tale definizione e usa le API di esecuzione, streaming e sessione standard di Agent Framework.

Usare questa integrazione per:

• Agenti prompt, denominati e con controllo delle versioni delle definizioni degli agenti lato server.
• Agenti ospitati, che vengono distribuite applicazioni agente raggiunte tramite un endpoint specifico dell'agente.

Per l'inferenza del modello diretto in cui l'applicazione è proprietaria della definizione dell'agente, vedere Microsoft provider di modelli Foundry. Per distribuire un'applicazione Agent Framework come agente ospitato, vedere Foundry Hosted Agents.To deploy an Agent Framework application as a Hosted Agent, see Foundry Hosted Agents.

Installare i pacchetti

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

Connettersi a un agente di richiesta

Creare un AIProjectClient oggetto per il progetto Foundry ed eseguire il wrapping di come AgentReference .FoundryAgent Aggiungere la versione quando l'applicazione deve usare una definizione specifica dell'agente di richiesta.

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

È anche possibile recuperare un ProjectsAgentRecord oggetto per usare la versione più recente o per ProjectsAgentVersion usare una versione recuperata in modo esplicito, quindi passare tale oggetto a projectClient.AsAIAgent(...).

Recuperare la versione più recente dell'agente di richiesta

Usare AgentAdministrationClient quando l'applicazione deve risolvere la versione registrata più recente in base al nome.

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

Un FoundryAgent usa il modello, le istruzioni e gli strumenti ospitati archiviati nella relativa definizione foundry. Configurare tali funzionalità in Foundry; il client non può sostituirli in fase di esecuzione.

Avvertimento

DefaultAzureCredential è utile per lo sviluppo. Nell'ambiente di produzione preferisce credenziali specifiche, ManagedIdentityCredential ad esempio per evitare il probe delle credenziali indesiderate.

Connettersi a un agente ospitato

Gli agenti ospitati espongono un endpoint OpenAI specifico dell'agente. Compilare l'endpoint dall'endpoint del progetto e dal nome dell'agente registrato, quindi passarlo 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();

Il selettore della versione controllata dall'amministratore dell'endpoint determina la versione attiva dell'agente ospitato.

Installare i pacchetti

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"

Usare FOUNDRY_AGENT_VERSION per gli agenti di prompt. Gli agenti ospitati possono ometterlo.

Connettersi a un agente di richiesta

Specificare l'endpoint del progetto, il nome dell'agente e la versione dell'agente. Il servizio fornisce il modello archiviato, le istruzioni e la configurazione dello strumento ospitato.

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

Se un agente prompt dichiara uno strumento di funzione locale, passare il chiamabile corrispondente tramite tools= durante la costruzione FoundryAgent in modo che il client possa eseguirlo quando richiesto. Vedere l'esempio di pubblicazione e connessione dell'agente di richiesta.

Connettersi a un agente ospitato

Gli agenti ospitati non richiedono agent_version. Connettersi con l'endpoint del progetto e il nome dell'agente registrato.

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

Cosa funziona e cosa non accade con FoundryAgent

FoundryAgent si connette a una definizione di agente già esistente in Foundry. Le istruzioni archiviate e la configurazione degli strumenti sono autorevoli, pertanto il comportamento lato client è diverso da quello di proprietà dell'applicazione Agent(client=FoundryChatClient(...)).

Tools

Tipo di strumento passato a FoundryAgent(...)	Behavior
FunctionToolcon un Python locale chiamabile	Supportato solo quando la definizione di funzione corrispondente esiste già nell'agente Foundry. Il chiamabile viene eseguito nel processo dell'applicazione quando Foundry lo richiede.
Strumenti ospitati, tra cui ricerca Web, interprete del codice, ricerca di file, MCP, generazione di immagini e Microsoft Casella degli strumenti Foundry	Configurare questi elementi nella definizione dell'agente Foundry. Passandoli sul lato client non li aggiunge all'agente gestito dal servizio.

Per informazioni sugli allegati della casella degli strumenti e indicazioni dirette sul consumo mcp, vedere Microsoft Casella degli strumenti Foundry.

Non è possibile registrare un nuovo strumento visibile al modello in fase di costruzione. Il passaggio di una funzione chiamabile fornisce solo l'implementazione locale per una funzione già dichiarata dall'agente Foundry.

Provider di contesto

Comportamento del fornitore di contesto	Funziona con FoundryAgent?
Aggiunge messaggi, ad esempio memoria recuperata, frammenti di rag o informazioni sul profilo utente	Yes. Il contesto inserito viene inoltrato con la richiesta.
Mantiene o osserva la conversazione	Yes. Il provider viene eseguito localmente intorno alla richiesta e alla risposta.
Aggiunge strumenti in modo dinamico	No, a meno che tali strumenti non siano già dichiarati nella definizione dell'agente Foundry.

Usare Agent(client=FoundryChatClient(...)) quando l'applicazione richiede la selezione dinamica degli strumenti, il caricamento delle competenze o qualsiasi comportamento che modifica gli strumenti visibili al modello in fase di esecuzione.

Opzioni di esecuzione

Poiché la definizione dell'agente Foundry è l'origine della verità, non tutte le opzioni passate o default_optionsagent.run(...) vengono rispettate.

Option	Comportamento dell'agente prompt
model	Ignorato. Il modello deriva dalla definizione dell'agente Foundry.
tools, tool_choice, parallel_tool_calls	Rimosso dalla richiesta. Gli strumenti devono essere dichiarati nella definizione dell'agente Foundry.
instructions messaggi di sistema o di sviluppo	Ignorato. Le istruzioni archiviate di Foundry sono autorevoli.
conversation_id	Usato e mappato alla sessione dell'agente Foundry, se applicabile.
extra_body	Inoltrato e unito al riferimento dell'agente fornito dal framework.
Parametri di campionamento, metadati, user, storee response_format	Inoltrato, ma la configurazione dell'agente Foundry o del modello può eseguire l'override o vincolare le configurazioni.

Gli agenti ospitati ricevono lo stesso filtro lato client, ma l'agente distribuito può accettare, ignorare o reinterpretare qualsiasi opzione inoltrata. Verificare il comportamento rispetto all'agente ospitato specifico.

Suggerimento

Usare Agent(client=FoundryChatClient(...)) quando è necessario il controllo per esecuzione sulle istruzioni, sulle opzioni di generazione o sugli strumenti.

Gestire una sessione del servizio Agente ospitato

Gli agenti ospitati che usano sessioni sul lato servizio richiedono la superficie delle risposte di anteprima:

Creare la sessione del servizio in modo esplicito quando l'applicazione deve associarla a un tenant o a un utente, quindi eseguirne il wrapping dell'identificatore come sessione di 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(

Suggerimento

Per un esempio completo, vedere l'esempiousing_deployed_agent.py.

Impostare un timeout HTTP personalizzato

FoundryAgent eredita il timeout di OpenAI SDK per impostazione predefinita. Passare timeout= in secondi quando le conversazioni a più turni o le condizioni di rete richiedono un limite diverso.

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

Il timeout viene applicato a una copia per agente del client HTTP e non influisce sugli altri agenti che condividono lo stesso AIProjectClient.

Annotazioni

FoundryAgent l'integrazione per Prompt e Agenti ospitati non è attualmente disponibile per Agent Framework Go. Vedere il repository di Agent Framework Go per lo stato più aggiornato.

Eseguire, trasmettere e continuare le conversazioni

Dopo la connessione, usare le stesse API degli altri agenti di Agent Framework:

• Eseguire una richiesta con RunAsync o run.
• Trasmettere gli aggiornamenti con RunStreamingAsync o run(..., stream=True).
• Riutilizzare un oggetto AgentSession per continuare una conversazione.
• Usare le API di conversazione lato server Foundry quando la conversazione deve essere visibile e persistente nel progetto Foundry.

Mantenere i nomi degli agenti Foundry, le versioni, gli endpoint e gli identificatori di conversazione nello stato lato server attendibile. Autorizzare il chiamante prima di riprendere qualsiasi conversazione esistente.

Passaggi successivi

Esaminare Microsoft provider di modelli Foundry