Usługa agenta Microsoft Foundry

FoundryAgentłączy platformę Agent Framework z definicją agenta zarządzaną przez usługę agenta Microsoft Foundry. Model, instrukcje, hostowane narzędzia i wersja agenta są konfigurowane w narzędziu Foundry; Aplikacja łączy się z definicją i używa standardowych interfejsów API uruchamiania, przesyłania strumieniowego i sesji platformy Agent Framework.

Użyj tej integracji dla:

Monituj agentów, które są nazwane i wersjonowane definicje agenta po stronie serwera.
Hostowani agenci, które są wdrażane aplikacje agentów osiągane za pośrednictwem punktu końcowego specyficznego dla agenta.

Aby uzyskać bezpośrednie wnioskowanie modelu, w którym aplikacja jest właścicielem definicji agenta, zobacz Microsoft dostawca modelu usługi Foundry. Aby wdrożyć aplikację platformy Agent Framework jako hostowanego agenta, zobacz Foundry Hosted Agents (Hostowani agenci programu Foundry).

Instalowanie pakietów

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

Nawiązywanie połączenia z agentem monitu

Utwórz element AIProjectClient dla projektu Foundry i opakuj FoundryAgentelement AgentReference jako . Przypnij wersję, gdy aplikacja musi używać określonej definicji agenta monitu.

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

Możesz również pobrać obiekt , ProjectsAgentRecord aby użyć najnowszej wersji lub elementu ProjectsAgentVersion , aby użyć jawnie pobranej wersji, a następnie przekazać ten obiekt do projectClient.AsAIAgent(...).

Pobieranie najnowszej wersji agenta monitu

Użyj AgentAdministrationClient polecenia , gdy aplikacja powinna rozpoznać najnowszą zarejestrowaną wersję według nazwy.

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

Ważna

Obiekt FoundryAgent używa modelu, instrukcji i hostowanych narzędzi przechowywanych w definicji biblioteki Foundry. Skonfiguruj te możliwości w narzędziu Foundry; klient nie może zastąpić ich w czasie wykonywania.

Warning

DefaultAzureCredential jest wygodny dla programowania. W środowisku produkcyjnym preferuj określone poświadczenia, takie jak ManagedIdentityCredential unikanie niezamierzonego sondowania poświadczeń.

Nawiązywanie połączenia z hostowanym agentem

Hostowani agenci uwidaczniają punkt końcowy openAI specyficzny dla agenta. Skompiluj punkt końcowy z punktu końcowego projektu i nazwę zarejestrowanego agenta, a następnie przekaż go do 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();

Selektor wersji kontrolowanej przez administratora punktu końcowego określa aktywną wersję hostowanego agenta.

Instalowanie pakietów

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"

Użyj polecenia FOUNDRY_AGENT_VERSION dla agentów monitów. Hostowani agenci mogą go pominąć.

Nawiązywanie połączenia z agentem monitu

Podaj punkt końcowy projektu, nazwę agenta i wersję agenta. Usługa dostarcza przechowywany model, instrukcje i konfigurację narzędzia hostowanego.

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

Jeśli agent monitu deklaruje narzędzie funkcji lokalnej, przekaż pasujące wywołanie za pośrednictwem tools= podczas konstruowania FoundryAgent , aby klient mógł go wykonać po żądaniu. Zobacz przykład Publikowanie i łączenie agenta monitu.

Nawiązywanie połączenia z hostowanym agentem

Hostowani agenci nie wymagają agent_version. Połącz się z punktem końcowym projektu i nazwą zarejestrowanego agenta.

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

Co działa, a co nie działa w przypadku `FoundryAgent`

FoundryAgent nawiązuje połączenie z definicją agenta, która już istnieje w narzędziu Foundry. Przechowywane instrukcje i konfiguracja narzędzia są autorytatywne, więc zachowanie po stronie klienta różni się od aplikacji należącej do Agent(client=FoundryChatClient(...))aplikacji .

Tools

Typ narzędzia przekazany do `FoundryAgent(...)`	Behavior
`FunctionTool`z lokalną Python wywoływaną	Obsługiwane tylko wtedy, gdy zgodna definicja funkcji już istnieje w agencie foundry. Obiekt wywołujący jest uruchamiany w procesie aplikacji, gdy usługa Foundry żąda jej.
Narzędzia hostowane, w tym wyszukiwanie w Internecie, interpreter kodu, wyszukiwanie plików, MCP, generowanie obrazów i przybornik Microsoft Foundry	Skonfiguruj je w definicji agenta usługi Foundry. Przekazywanie ich po stronie klienta nie powoduje dodania ich do agenta zarządzanego przez usługę.

Aby zapoznać się z załącznikiem przybornika i bezpośrednimi wskazówkami dotyczącymi użycia mcp, zobacz Microsoft Przybornik usługi Foundry.

W czasie budowy nie można zarejestrować nowego narzędzia widocznego dla modelu. Przekazywanie funkcji, którą można wywołać, dostarcza tylko lokalną implementację dla funkcji, którą już deklaruje agent Foundry.

Dostawcy kontekstu

Zachowanie dostawcy kontekstu	Działa z `FoundryAgent`?
Dodaje komunikaty, takie jak pobrane pamięci, fragmenty kodu RAG lub informacje o profilu użytkownika	Yes. Wstrzykiwany kontekst jest przekazywany wraz z żądaniem.
Utrwala lub obserwuje konwersację	Yes. Dostawca działa lokalnie wokół żądania i odpowiedzi.
Dynamicznie dodaje narzędzia	Nie, chyba że te narzędzia zostały już zadeklarowane w definicji agenta Foundry.

Użyj Agent(client=FoundryChatClient(...)) , gdy aplikacja wymaga dynamicznego wyboru narzędzi, ładowania umiejętności lub jakiegokolwiek zachowania, które zmienia narzędzia widoczne dla modelu w czasie wykonywania.

Opcje uruchamiania

Ponieważ definicja agenta Foundry jest źródłem prawdy, nie każda opcja przekazywana lub agent.run(...) jest honorowanadefault_options.

Option	Zachowanie agenta monitu
`model`	Ignorowane. Model pochodzi z definicji agenta Foundry.
`tools`, , `tool_choiceparallel_tool_calls`	Usunięto z żądania. Narzędzia muszą być zadeklarowane w definicji agenta usługi Foundry.
`instructions` i komunikaty systemowe lub deweloperskie	Ignorowane. Przechowywane instrukcje usługi Foundry są autorytatywne.
`conversation_id`	Używane i mapowane na sesję agenta usługi Foundry, jeśli ma to zastosowanie.
`extra_body`	Przekazane i scalone z dokumentacją agenta dostarczonego przez platformę.
Parametry próbkowania, metadane, `user`, `store`i `response_format`	Przekazano dalej, ale konfiguracja agenta lub modelu foundry może je zastąpić lub ograniczyć.

Agenci hostowani otrzymują takie same filtrowanie po stronie klienta, ale wdrożony agent może zaakceptować, zignorować lub ponownie zinterpretować dowolną przekazaną opcję. Zweryfikuj zachowanie względem określonego hostowanego agenta.

Wskazówka

Użyj Agent(client=FoundryChatClient(...)) polecenia , jeśli potrzebujesz kontroli nad instrukcjami, opcjami generowania lub narzędziami.

Zarządzanie sesją usługi hostowanego agenta

Hostowani agenci korzystający z sesji po stronie usługi wymagają powierzchni odpowiedzi w wersji zapoznawczej:

Utwórz sesję usługi jawnie, gdy aplikacja musi powiązać ją z dzierżawą lub użytkownikiem, a następnie opakuj jej identyfikator jako sesję platformy agenta.

    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(

Wskazówka

Zobacz przykład, using_deployed_agent.py aby zapoznać się z kompletnym przykładem.

Ustawianie niestandardowego limitu czasu HTTP

FoundryAgent domyślnie dziedziczy limit czasu zestawu OpenAI SDK. Przekazywanie timeout= w sekundach, gdy konwersacje wieloełowe lub warunki sieciowe wymagają innego limitu.

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

Limit czasu jest stosowany do kopii klienta HTTP dla poszczególnych agentów i nie ma wpływu na innych agentów, którzy współużytkujący ten sam AIProjectClientelement .

Note

FoundryAgent integracja dla agentów monitowanych i hostowanych nie jest obecnie dostępna w środowisku Agent Framework Go. Aktualny status znajdziesz w repozytorium Agent Framework dla Go.

Uruchamianie, przesyłanie strumieniowe i kontynuowanie konwersacji

Po nawiązaniu połączenia użyj tych samych interfejsów API co inni agenci programu Agent Framework:

Uruchom żądanie za pomocą RunAsync polecenia lub run.
Przesyłanie strumieniowe aktualizacji za pomocą polecenia RunStreamingAsync lub run(..., stream=True).
Użyj ponownie elementu AgentSession , aby kontynuować konwersację.
Użyj interfejsów API konwersacji po stronie serwera Po stronie serwera, gdy konwersacja musi być widoczna i utrwalone w projekcie Foundry.

Zachowaj nazwy, wersje, punkty końcowe i identyfikatory konwersacji w zaufanym stanie po stronie serwera. Autoryzuj obiekt wywołujący przed wznowieniem dowolnej istniejącej konwersacji.

Następne kroki

Przejrzyj dostawcę modelu Microsoft Foundry

Opinia

Czy ta strona była pomocna?

Last updated on 2026-08-13

Usługa agenta Microsoft Foundry

Instalowanie pakietów

Nawiązywanie połączenia z agentem monitu

Pobieranie najnowszej wersji agenta monitu

Nawiązywanie połączenia z hostowanym agentem

Instalowanie pakietów

Configuration

Nawiązywanie połączenia z agentem monitu

Nawiązywanie połączenia z hostowanym agentem

Co działa, a co nie działa w przypadku FoundryAgent

Tools

Dostawcy kontekstu

Opcje uruchamiania

Zarządzanie sesją usługi hostowanego agenta

Ustawianie niestandardowego limitu czasu HTTP

Uruchamianie, przesyłanie strumieniowe i kontynuowanie konwersacji

Następne kroki

Opinia

Dodatkowe zasoby

Co działa, a co nie działa w przypadku `FoundryAgent`