Служба агента Microsoft Foundry

FoundryAgentподключает агент платформу к определению агента, управляемому службой агента Foundry Microsoft. Модель агента, инструкции, размещенные средства и версия настроены в Foundry; приложение подключается к определению и использует стандартные API-интерфейсы запуска, потоковой передачи и сеанса.

Используйте эту интеграцию для:

Агенты запроса, которые являются определениями агентов на стороне сервера с именем и версиями.
Размещенные агенты, которые развернуты приложения агента, доступные через конечную точку для конкретного агента.

Сведения о прямом выводе модели, в которой ваше приложение владеет определением агента, см. в разделе Microsoft Поставщик модели Foundry. Сведения о развертывании приложения Agent Framework в качестве размещенного агента см. в разделе "Размещенные агенты Foundry".

Установка пакетов

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

Подключение к агенту запроса

AIProjectClient Создайте проект Foundry и заключите его AgentReference в видеFoundryAgent. Закрепите версию, когда приложение должно использовать определенное определение агента запроса.

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

Можно также получить ProjectsAgentRecord последнюю версию или ProjectsAgentVersion использовать явно полученную версию, а затем передать этот объект projectClient.AsAIAgent(...)в .

Получение последней версии агента запроса

Используется AgentAdministrationClient , когда приложение должно разрешать последнюю зарегистрированную версию по имени.

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

Использует FoundryAgent модель, инструкции и размещенные средства, хранящиеся в определении Foundry. Настройте эти возможности в Foundry; Клиент не может заменить их во время выполнения.

Предупреждение

DefaultAzureCredential удобно для разработки. В рабочей среде предпочитайте определенные учетные данные, например ManagedIdentityCredential , чтобы избежать непреднамеренного проверки учетных данных.

Подключение к размещенном агенту

Размещенные агенты предоставляют конечную точку OpenAI для конкретного агента. Создайте конечную точку из конечной точки проекта и имени зарегистрированного агента, а затем передайте ее 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();

Селектор версий, управляемый администратором конечной точки, определяет активную версию размещенного агента.

Установка пакетов

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"

Используйте FOUNDRY_AGENT_VERSION для агентов подсказок. Размещенные агенты могут опустить его.

Подключение к агенту запроса

Укажите конечную точку проекта, имя агента и версию агента. Служба предоставляет хранимую модель, инструкции и конфигурацию размещенного средства.

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

Если агент запроса объявляет локальную функцию, передайте соответствующий вызов tools= при создании FoundryAgent , чтобы клиент смог выполнить его при запросе. См. пример публикации и подключения агента запроса.

Подключение к размещенном агенту

Размещенные агенты не требуются agent_version. Подключитесь к конечной точке проекта и имени зарегистрированного агента.

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

Что работает и что не работает с `FoundryAgent`

FoundryAgent подключается к определению агента, которое уже существует в Foundry. Хранимые инструкции и конфигурация инструментов являются достоверными, поэтому поведение на стороне клиента отличается от собственного Agent(client=FoundryChatClient(...))приложения.

Tools

Тип инструмента, переданный в `FoundryAgent(...)`	Behavior
`FunctionTool`с вызываемым локальным Python	Поддерживается только в том случае, если определение соответствующей функции уже существует в агенте Foundry. Вызываемый выполняется в процессе приложения, когда Foundry запрашивает его.
Размещенные средства, включая веб-поиск, интерпретатор кода, поиск файлов, MCP, создание изображений и Microsoft панели элементов Foundry	Настройте их в определении агента Foundry. Передача их на стороне клиента не добавляет их в управляемый службой агент.

Сведения о вложении панели элементов и руководстве по использованию MCP см. в разделе Microsoft Панели элементов Foundry.

Вы не можете зарегистрировать новое видимое для модели средство во время строительства. Передача вызываемой функции предоставляет только локальную реализацию для функции, которую агент Foundry уже объявляет.

Поставщики контекстов

Поведение поставщика контекста	Работает с `FoundryAgent`?
Добавляет сообщения, такие как полученная память, фрагменты фрагментов RAG или сведения о профиле пользователя	Yes. Внедрённый контекст передаётся вместе с запросом.
Сохраняется или наблюдается беседа	Yes. Поставщик выполняется локально вокруг запроса и ответа.
Динамически добавляет средства	Нет, если эти средства уже объявлены в определении агента Foundry.

Используйте, когда приложению требуется Agent(client=FoundryChatClient(...)) динамический выбор инструментов, загрузка навыков или любое поведение, которое изменяет видимые моделью средства во время выполнения.

Параметры выполнения

Поскольку определение агента Foundry является источником истины, а не каждый вариант, передаваемый default_options или agent.run(...) учитывается.

Опция	Поведение агента запроса
`model`	Проигнорировано. Модель основана на определении агента Foundry.
`tools`, , `tool_choiceparallel_tool_calls`	Удален из запроса. Средства должны быть объявлены в определении агента Foundry.
`instructions` и системные сообщения или сообщения разработчика	Проигнорировано. Хранимые инструкции Foundry являются достоверными.
`conversation_id`	Используется и сопоставляются с сеансом агента Foundry при необходимости.
`extra_body`	Переадресованный и объединенный с ссылкой на агент, предоставленный платформой.
Параметры выборки, метаданные, `user`и `storeresponse_format`	Перенаправляется, но агент Foundry или конфигурация модели может переопределить или ограничить их.

Размещенные агенты получают ту же фильтрацию на стороне клиента, но развернутый агент может принимать, игнорировать или переосмыслить любой переадресованный параметр. Проверьте поведение для конкретного размещенного агента.

Tip

Используйте Agent(client=FoundryChatClient(...)) при необходимости контроля за выполнением инструкций, параметров создания или инструментов.

Управление сеансом службы размещенного агента

Размещенные агенты, использующие сеансы на стороне службы, требуют области предварительного просмотра ответов:

Создайте сеанс службы явным образом, когда приложение должно привязать его к клиенту или пользователю, а затем упаковать его идентификатор в сеанс 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

Полный пример см. в using_deployed_agent.py примере .

Настройка пользовательского времени ожидания HTTP

FoundryAgent по умолчанию наследует время ожидания пакета SDK OpenAI. Передача timeout= в секундах, когда для многоэтапных бесед или сетевых условий требуется другое ограничение.

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

Время ожидания применяется к копии HTTP-клиента для каждого агента и не влияет на другие агенты, которые используют те же AIProjectClient.

Замечание

FoundryAgent Интеграция с агентами с запросами и размещенными агентами в настоящее время недоступна для Agent Framework Go. Сведения о последнем состоянии см. в репозитории Agent Framework Go .

Выполнение, потоковая передача и продолжение бесед

После подключения используйте те же API, что и другие агенты Agent Framework:

Выполнение запроса с RunAsync помощью или run.
Потоковая передача обновлений с RunStreamingAsync помощью или run(..., stream=True).
Повторное использование AgentSession беседы.
Используйте API бесед на стороне сервера Foundry, если беседа должна быть видна и сохранена в проекте Foundry.

Сохраняйте имена агентов Foundry, версии, конечные точки и идентификаторы бесед в состоянии доверенного сервера. Авторизуйте вызывающий объект перед возобновлением любой существующей беседы.

Дальнейшие действия

Проверка поставщика моделей Microsoft Foundry

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-08-13

Служба агента Microsoft Foundry

Установка пакетов

Подключение к агенту запроса

Получение последней версии агента запроса

Подключение к размещенном агенту

Установка пакетов

Configuration

Подключение к агенту запроса

Подключение к размещенном агенту

Что работает и что не работает с FoundryAgent

Tools

Поставщики контекстов

Параметры выполнения

Управление сеансом службы размещенного агента

Настройка пользовательского времени ожидания HTTP

Выполнение, потоковая передача и продолжение бесед

Дальнейшие действия

Обратная связь

Дополнительные ресурсы

Что работает и что не работает с `FoundryAgent`