Поделиться через

Microsoft Foundry

Microsoft Agent Framework поддерживает как прямую аппроксимацию модели из конечных точек проекта Microsoft Foundry, так и агентов, управляемых службой агента Foundry.

Начало работы

Добавьте необходимые пакеты NuGet в проект.

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

Два типа агента

Интеграция Microsoft Foundry предоставляет два различных шаблона использования:

Тип Созданный тип Описание Используйте, когда
Агент ответов ChatClientAgent Приложение программно предоставляет модель, инструкции и средства во время выполнения AIProjectClient.AsAIAgent(...). Ресурс агента на стороне сервера не создается. Вы владеете определением агента и хотите простой гибкой настройки. Это шаблон, используемый в большинстве примеров.
Агент Foundry (версия) FoundryAgent Управляемый сервером — определения агента создаются и версионируются на портале Foundry или программным способом.AIProjectClient.AgentAdministrationClient Передайте ProjectsAgentVersion или ProjectsAgentRecord или AgentReference в AIProjectClient.AsAIAgent(...). Вам нужны строгие определения агентов с версиями, управляемые на портале Foundry, с помощью API службы

Агент откликов (прямое заключение)

Используйте AsAIAgent на AIProjectClient непосредственно с моделью и инструкциями. Это рекомендуемая отправная точка для большинства сценариев.

using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;

AIAgent agent = new AIProjectClient(
    new Uri("<your-foundry-project-endpoint>"),
    new DefaultAzureCredential())
        .AsAIAgent(
            model: "gpt-4o-mini",
            name: "Joker",
            instructions: "You are good at telling jokes.");

Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate."));

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

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

Этот путь ориентирован на изначальное использование кода и не создает ресурс агента, под управлением сервера.

Агент Foundry (версионируемый)

Используйте собственные AIProjectClient.AgentAdministrationClient API из SDK для проектов ИИ, чтобы получить версионные ресурсы агентов, затем оберните их с помощью AsAIAgent. Агенты можно создавать и настраивать непосредственно на портале Foundry или программным способом.AIProjectClient.AgentAdministrationClient

using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Foundry;

var aiProjectClient = new AIProjectClient(
    new Uri("<your-foundry-project-endpoint>"),
    new DefaultAzureCredential());

// Retrieve an existing agent by name (uses the latest version automatically)
ProjectsAgentRecord jokerRecord = await aiProjectClient.AgentAdministrationClient.GetAgentAsync("Joker");
FoundryAgent agent = aiProjectClient.AsAIAgent(jokerRecord);

Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate."));

Это важно

Средства и инструкции для Foundry Agents строго соответствуют исходным параметрам, с которыми они были созданы; изменение средств или инструкций во время выполнения не поддерживается.

Использование агента

ChatClientAgent Оба типа (ответы) и FoundryAgent (версия) являются стандартными AIAgent экземплярами и поддерживают все стандартные операции, включая сеансы, инструменты, ПО промежуточного слоя и потоковую передачу.

AgentSession session = await agent.CreateSessionAsync();
Console.WriteLine(await agent.RunAsync("Tell me a joke.", session));
Console.WriteLine(await agent.RunAsync("Now make it funnier.", session));

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

Лаборатория в Python

В Python все клиенты, относящиеся к Foundry, теперь живут под agent_framework.foundry.

  • agent-framework-foundry предоставляет облачные соединители Foundry: FoundryChatClient, FoundryAgent, FoundryEmbeddingClientи FoundryMemoryProvider.
  • agent-framework-foundry-local обеспечивает FoundryLocalClient выполнение модели на локальном уровне.

Это важно

На этой странице рассматриваются текущие клиенты Python для конечных точек проекта Microsoft Foundry, конечных точек моделей и службы агента Foundry. Если у вас есть автономная конечная точка ресурса Azure OpenAI (https://<your-resource>.openai.azure.com), используйте руководство по Python на странице поставщика OpenAI. Если вы хотите локально запускать поддерживаемые модели, см. страницу "Локальный поставщик Foundry".

Шаблоны чата и агента Foundry в Python

Сценарий Фигура Python Используйте, когда
Простое вывод с конечной точкой "Ответы Foundry" Agent(client=FoundryChatClient(...)) Ваше приложение владеет определением агента, инструментами и циклом беседы, и вам нужна модель, развернутая в проекте Foundry.
Управляемые службой агенты в службе агента Foundry FoundryAgent(...) Вы хотите подключиться к объекту PromptAgent или HostedAgent, который создается и настраивается на портале Foundry или через API службы.

Installation

pip install agent-framework-foundry
pip install azure-identity

Тот же agent-framework-foundry пакет также включает в себя FoundryEmbeddingClient встраивания моделей Foundry для конечных точек.

Конфигурация

FoundryChatClient

FOUNDRY_PROJECT_ENDPOINT="https://<your-project>.services.ai.azure.com"
FOUNDRY_MODEL="gpt-4o-mini"

FoundryAgent

FOUNDRY_PROJECT_ENDPOINT="https://<your-project>.services.ai.azure.com"
FOUNDRY_AGENT_NAME="my-agent"
FOUNDRY_AGENT_VERSION="1.0"

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

FoundryEmbeddingClient

FOUNDRY_MODELS_ENDPOINT="https://<apim-instance>.azure-api.net/<foundry-instance>/models"
FOUNDRY_MODELS_API_KEY="<api-key>"
FOUNDRY_EMBEDDING_MODEL="text-embedding-3-small"
FOUNDRY_IMAGE_EMBEDDING_MODEL="Cohere-embed-v3-english"  # optional

FoundryChatClient и FoundryAgent используют конечную точку проекта. FoundryEmbeddingClient использует отдельную конечную точку моделей.

Выбор правильного клиента Python

Сценарий Предпочтительный клиент Примечания
Ресурс Azure OpenAI OpenAIChatCompletionClient / OpenAIChatClient Используйте страницу поставщика OpenAI.
Вывод проекта Microsoft Foundry Agent(client=FoundryChatClient(...)) Использует конечную точку "Foundry Responses".
Агент, управляемый службой Microsoft Foundry FoundryAgent Рекомендуется для оперативных агентов и хостед-агентов.
Внедрение моделей Microsoft Foundry для конечных точек FoundryEmbeddingClient Использует FOUNDRY_MODELS_ENDPOINT плюс FOUNDRY_EMBEDDING_MODEL / FOUNDRY_IMAGE_EMBEDDING_MODEL.
Локальная среда выполнения Foundry Agent(client=FoundryLocalClient(...)) См. Foundry Local.

Создание агента с помощью FoundryChatClient

FoundryChatClient подключается к развернутой модели в проекте Foundry и использует конечную точку ответов. Совместите его со стандартом Agent, когда приложение должно полностью управлять инструкциями, средствами и сессиями.

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential

agent = Agent(
    client=FoundryChatClient(
        project_endpoint="https://your-project.services.ai.azure.com",
        model="gpt-4o-mini",
        credential=AzureCliCredential(),
    ),
    name="FoundryWeatherAgent",
    instructions="You are a helpful assistant.",
)

FoundryChatClient — это путь Python с приоритетом Foundry для прямого рассуждения и поддерживает инструменты, структурированный вывод и потоковую передачу.

Создание внедренных модулей с помощью FoundryEmbeddingClient

Используйте FoundryEmbeddingClient, когда требуется встраивание текста или изображения из конечной точки Foundry models.

from agent_framework.foundry import FoundryEmbeddingClient

async with FoundryEmbeddingClient() as client:
    result = await client.get_embeddings(["hello from Agent Framework"])
    print(result[0].dimensions)

Подключение к агенту, управляемому службой, с помощью FoundryAgent

Используйте FoundryAgent, когда определение агента находится в Foundry. Это рекомендуемый API Python для агентов Prompt и HostedAgents.

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",
    agent_version="1.0",
    credential=AzureCliCredential(),
)

Для HostedAgent не укажите agent_version и используйте вместо него имя размещенного агента.

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

Из текущего пространства имен были удалены старые поверхности совместимости для встраивания Python AzureAIClient, AzureAIProjectAgentProvider, AzureAIAgentClient, AzureAIAgentsProvider и Azure AI. Для текущего кода Python используйте FoundryChatClient, когда ваше приложение владеет инструкциями и инструментами, FoundryAgent, когда определение агента находится в Foundry, и FoundryEmbeddingClient для внедрения конечных точек моделей Foundry.

Использование агента

Как FoundryChatClient и FoundryAgent интегрируются со стандартным опытом работы Python Agent, включая вызовы инструментов, сеансы и стриминговые ответы. Для локальных сред выполнения используйте отдельную страницу локального поставщика Foundry.

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

Foundry Local

  • Last updated on