Usługa agenta Microsoft Foundry

FoundryAgentłączy platformę Agent Framework z definicją agenta zarządzaną przez usługę agenta Microsoft Foundry. Model agenta, instrukcje, hostowane narzędzia i wersja są konfigurowane w Foundry; aplikacja łączy się z tą definicją i używa standardowych interfejsów API platformy Agent Framework do uruchamiania, strumieniowania i obsługi sesji.

Użyj tej integracji dla:

Agenci promptów, czyli nazwane i wersjonowane definicje agentów po stronie serwera.
Agenci hostowani, czyli wdrożone aplikacje agentów dostępne za pośrednictwem punktu końcowego specyficznego dla danego agenta.

Aby uzyskać bezpośrednie wnioskowanie przy użyciu modelu, gdy aplikacja zawiera definicję agenta, zobacz dostawca modeli Microsoft 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

Połącz z Prompt Agent

Utwórz AIProjectClient dla projektu Foundry i opakuj AgentReference jako FoundryAgent. Przypnij tę wersję, jeśli aplikacja musi używać określonej definicji Prompt Agent.

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ć element ProjectsAgentRecord, aby użyć jego najnowszej wersji, lub element ProjectsAgentVersion, aby użyć wersji pobranej jawnie, a następnie przekazać ten obiekt do projectClient.AsAIAgent(...).

Pobierz najnowszą wersję Prompt Agent

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

Important

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 używaj określonego poświadczenia, takiego jak ManagedIdentityCredential, aby uniknąć niezamierzonego sprawdzania poświadczeń.

Nawiązywanie połączenia z hostowanym agentem

Agenci hostowani udostępniają specyficzny dla agenta punkt końcowy OpenAI. Utwórz punkt końcowy na podstawie punktu końcowego projektu i nazwy 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ąć.

Połącz z agentem Prompt

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 Prompt deklaruje lokalne narzędzie funkcyjne, podczas konstruowania FoundryAgent przekaż odpowiadający obiekt wywoływalny przez tools=, aby klient mógł je wykonać na żądanie. Zobacz przykład publikowania i łączenia Prompt Agent.

Nawiązywanie połączenia z hostowanym agentem

Agenci hostowani 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 mają charakter nadrzędny, więc działanie po stronie klienta różni się od należącego do aplikacji Agent(client=FoundryChatClient(...)).

Tools

Typ narzędzia przekazany do `FoundryAgent(...)`	Behavior
`FunctionTool` z lokalnym obiektem wywoływalnym Pythona	Obsługiwane tylko wtedy, gdy zgodna definicja funkcji już istnieje w agencie foundry. Wywoływalny obiekt jest wykonywany w procesie aplikacji, gdy Foundry tego zażąda.
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 Foundry. Przekazywanie ich po stronie klienta nie powoduje dodania ich do agenta zarządzanego przez usługę.

Informacje o integracji Toolbox oraz wskazówki dotyczące bezpośredniego użycia MCP można znaleźć w artykule Microsoft Foundry Toolbox.

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 podczas obsługi żą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 dowolnego działania, które zmienia narzędzia widoczne dla modelu w czasie wykonywania.

Opcje uruchamiania

Ponieważ definicja agenta Foundry stanowi źródło prawdy, nie każda opcja przekazywana przez default_options lub agent.run(...) jest uwzględniana.

Option	Zachowanie agenta Prompt
`model`	Ignorowane. Model pochodzi z definicji agenta Foundry.
`tools`, `tool_choice`, `parallel_tool_calls`	Usunięto z żądania. Narzędzia muszą być zadeklarowane w definicji agenta 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`	Przekazano i scalono z odnośnikiem do agenta dostarczonym przez framework.
Parametry próbkowania, metadane, `user`, `store`i `response_format`	Są przekazywane dalej, ale konfiguracja agenta lub modelu Foundry może je nadpisać 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.

Tip

Użyj Agent(client=FoundryChatClient(...)), gdy potrzebujesz kontroli dla poszczególnych uruchomień nad instrukcjami, opcjami generowania lub narzędziami.

Zarządzanie sesją usługi hostowanego agenta

Agenci hostowani korzystający z sesji po stronie usługi wymagają interfejsu Responses w wersji zapoznawczej:

Jawnie utwórz sesję usługi, gdy aplikacja musi powiązać ją z dzierżawcą lub użytkownikiem, a następnie opakuj jej identyfikator jako sesję struktury 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(

Tip

Zobacz using_deployed_agent.pyprzykład, aby zobaczyć pełny przykład.

Ustawianie niestandardowego limitu czasu HTTP

FoundryAgent domyślnie dziedziczy limit czasu z pakietu OpenAI SDK. Przekaż timeout= w sekundach, gdy wieloturowe rozmowy 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 ustawiany dla indywidualnej kopii klienta HTTP dla każdego agenta i nie wpływa na innych agentów, którzy współużytkują ten sam AIProjectClient.

Uwaga / Notatka

FoundryAgent integracja z agentami Prompt i Hosted nie jest obecnie dostępna w 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 lub run.
Przesyłaj aktualizacje strumieniowo za pomocą RunStreamingAsync lub run(..., stream=True).
Użyj ponownie elementu AgentSession , aby kontynuować konwersację.
Użyj interfejsów API rozmów po stronie serwera w Foundry, gdy rozmowa musi być widoczna i zapisywana w projekcie Foundry.

Przechowuj nazwy agentów Foundry, wersje, punkty końcowe i identyfikatory rozmów 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-25

Usługa agenta Microsoft Foundry

Instalowanie pakietów

Połącz z Prompt Agent

Pobierz najnowszą wersję Prompt Agent

Nawiązywanie połączenia z hostowanym agentem

Instalowanie pakietów

Configuration

Połącz z agentem Prompt

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`