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

FoundryAgent подключает Agent Framework к определению агента, которым управляет Microsoft Foundry Agent Service. Модель агента, инструкции, размещённые инструменты и версия настраиваются в Foundry; ваше приложение подключается к этому определению и использует стандартные API Agent Framework для запуска, потоковой передачи и сессий.

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

  • Промпт-агенты, которые представляют собой серверные определения агентов, имеющие имя и версию.
  • Размещённые агенты — это развёрнутые агентские приложения, доступные через конечную точку конкретного агента.

Если ваше приложение содержит определение агента и требуется прямой вывод модели, см. поставщик моделей 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(...).

Получить последнюю версию Prompt Agent

Используйте 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?"));

Это важно

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 для агентов подсказок. Размещенные агенты могут опустить его.

Подключиться к Prompt Agent

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

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

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

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

Для размещенных агентов не требуется 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 Toolbox Настройте их в определении агента в Foundry. Передача их на стороне клиента не добавляет их в управляемый службой агент.

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

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

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

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

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

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

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

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

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

Tip

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

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

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

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