azure-ai-projects-dotnet

Azure.AI.Projects для .NET — высокоуровневый навык для управления проектами Azure AI Foundry через AIProjectClient. В официальной карточке проект описан как единая точка доступа к агентам, connections, datasets, deployments, evaluations и indexes, а также к телеметрии и интеграции OpenAI. Типичный клиент создаётся из URI project endpoint и Azure credential; для локальной разработки и production в примере показан DefaultAzureCredential, а конкретная production credential может быть выбрана отдельно. Endpoint, имя deployment и необязательные имена connections должны приходить из переменных окружения или другой защищённой конфигурации, а не быть зашиты в исходники. Иерархия клиента разделяет операции по назначению. AIProjectClient предоставляет коллекции Agents, Connections, Datasets, Deployments, Evaluations, Evaluators и Indexes; для низкоуровневых persistent agents можно получить PersistentAgentsClient. Через него создаются агент, thread и сообщения, затем создаётся run, состояние которого опрашивается до выхода из queued или in-progress, после чего читаются текстовые элементы сообщений. Для versioned agents официальная карточка показывает отдельный preview-путь Azure.AI.Projects.OpenAI: создаётся PromptAgentDefinition, добавляются инструменты, публикуется AgentVersion и получается ProjectResponsesClient для ответов агента. Это позволяет отличать обычного persistent agent от версионируемого определения, а preview-поверхность не следует принимать за тот же стабильный API. Connections используются для перечисления и получения project connections, включая default connection. Получение credentials предлагается включать только когда они действительно нужны. Deployments можно перечислять, фильтровать по publisher и читать детали конкретной model deployment. Datasets поддерживают загрузку одного файла или каталога с версией и connection name, чтение dataset по имени и версии и удаление. Indexes предназначены, в частности, для Azure AI Search: в примере создаётся или обновляется версия индекса, затем его можно перечислить или удалить. Эти действия образуют практический контур Foundry-проекта: настроить подключение, выбрать deployment, загрузить данные и зарегистрировать индекс, не смешивая идентификаторы ресурсов с секретами подключения. Для evaluations карточка показывает конфигурацию evaluator, входной InputDataset, создание Evaluation и чтение результата или списка evaluations. В качестве инструмента доступен evaluator релевантности; конкретные deployment name и параметры должны соответствовать среде проекта. Отдельно показан мост к Azure OpenAI: из project connection извлекается URI, создаётся AzureOpenAIClient и берётся ChatClient для выбранной модели deployment. Среди поддерживаемых инструментов перечислены Code Interpreter, File Search, Function Calling, Bing Grounding, Azure AI Search, OpenAPI, Azure Functions и MCP. Это помогает выбрать поверхность API по задаче: выполнение кода, поиск по файлам, вызов функций, grounding или внешняя интеграция — вместо одного универсального вызова. Практические ограничения источника также важны. Для I/O рекомендуется использовать async-методы и ожидать run с задержкой, а для списков учитывать AsyncPageable<T> и пагинацию. Временные threads, agents и files следует удалять после завершения сценария, если они больше не нужны. Операции Azure должны обрабатывать RequestFailedException с HTTP status, error code и сообщением, не выводя секреты. Пакеты Azure.AI.Projects и Azure.Identity обязательны для базового сценария, а расширения OpenAI и Persistent Agents подключаются отдельно по необходимости. Конкретные версии SDK, preview-контракты, доступные evaluator и поддерживаемые возможности нужно сверять с актуальной документацией Microsoft перед production-обновлением: эта карточка объясняет структуру и рабочие сценарии SDK, но не заменяет versioned API reference.