Примечание.
Для доступа к этой странице требуется авторизация. Вы можете попробовать войти или изменить каталоги.
Для доступа к этой странице требуется авторизация. Вы можете попробовать изменить каталоги.
Совет
Средство миграции доступно для автоматизации миграции из API Помощников в агенты.
Служба агента Foundry обеспечивает улучшенный интерфейс для разработчиков, позволяющий легко создавать, версионировать, эксплуатировать и контролировать интеллектуальных агентов. API новых агентов представляет обновленный пакет SDK, новые возможности корпоративного уровня и сохраняет возможности идентификации, управления и наблюдаемости, которые вы используете сегодня.
Необходимые условия
- Подписка Azure. Создайте его бесплатно.
- Проект Microsoft Foundry.
- Пакет SDK службы агента Foundry для вашего языка и соответствующий пакет удостоверений для проверки подлинности. Установите пакеты для вашего языка и войдите в систему с
az loginили используйтеDefaultAzureCredential:
pip install "azure-ai-projects>=2.0.0"
- Код существующих агентов или помощников, который необходимо перенести.
Следующий код инициализирует клиенты, используемые в этом руководстве:
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
# Format: "https://resource_name.services.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"
project = AIProjectClient(
endpoint=PROJECT_ENDPOINT,
credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()
Используется project для создания и управления версиями агента. Используйте openai (или эквивалент в вашем языке) для бесед и ответов.
Ключевые преимущества
Новые агенты предоставляют следующие преимущества:
Производительность разработчика
- ⭐ Больше моделей. Создавайте ответы, используя любую модель Foundry, как в агенте, так и непосредственно через вызов функции генерации ответа.
- Дополнительные возможности. Веб-поиск, поиск файлов, интерпретатор кода, вызов инструмента MCP, генерация изображений и резюмирование.
- Современный примитив API. Создан на основе API ответов вместо более старых API помощников.
- Фоновый режим. Поддержка инструментов, работающих длительное время (например, генерации изображений), и устойчивых потоков данных (поддерживающих сценарии отключения и повторного подключения)
- Защита на будущее Новые функции и поддержка моделей добавляются исключительно в новых агентов.
- Новые типы агентов. Создание агентов с использованием подсказок, агентов на основе рабочих процессов (предварительная версия), агентов на основе рабочих процессов и размещённых агентов (предварительная версия).
Готовность предприятия
- ⭐ Однотенантное хранилище. Используйте однотенантное хранилище с возможностью использования вашей собственной Azure Cosmos DB для хранения состояния и обеспечения безопасности ваших данных.
- Улучшенная безопасность. Управляйте доступом к запуску или изменению определений агентов.
- Разделение обязанностей. Определите агенты один раз и выполните их с различными входными данными.
- Развертываемые агенты. Агенты могут предоставляться в виде отдельных конечных точек.
Модернизация API
- Улучшено управление состоянием. Использует беседы вместо тредов и сообщений.
- Контекст с состоянием. Автоматически сохраняет контекст между вызовами.
- Супермножество API ответов. Расширяет возможности API ответов и добавляет дополнительные функции.
- Рабочие процессы с одним или несколькими агентами. Легко объединяйте агентов для сложных рабочих процессов.
Ключевые изменения
В следующей таблице перечислены основные изменения API между предыдущим и текущим интерфейсом агента.
| Перед | После | Детали |
|---|---|---|
| Потоки | Разговоры | Поддерживает потоки элементов, а не только сообщения. |
| Запуски | Ответы | Ответы отправляют входные элементы или используют объект беседы и получают выходные элементы. Циклы вызовов инструментов управляются явным образом. |
| Помощники и агенты | Агенты (новые) | Поддержка готовых к работе с предприятием запросов, рабочих процессов и размещенных агентов с контекстом с отслеживанием состояния по умолчанию для любой модели Foundry. |
Доступность инструмента агента
В следующей таблице сравниваются средства агента, доступные в классических агентах и новой службе агента Foundry. Используйте его, чтобы определить, какие средства переносятся напрямую, которые изменились, и которые являются эксклюзивными для нового интерфейса.
| Инструмент | Литейный (классический) | Литейный цех (новый) |
|---|---|---|
| Агент к агенту (A2A) | Нет | Да (общедоступная предварительная версия) |
| Поиск с использованием ИИ Azure | Да (GA) | Да (GA) |
| Функции Azure | Да (GA) | Нет |
| Автоматизация браузера | Да (общедоступная предварительная версия) | Да (общедоступная предварительная версия) |
| Интерпретатор кода | Да (GA) | Да (GA) |
| Использование компьютера | Да (общедоступная предварительная версия) | Да (общедоступная предварительная версия) |
| Подключенные агенты | Да (общедоступная предварительная версия) | Нет (рекомендация: рабочий процесс и средство A2A) |
| Глубокое исследование | Да (общедоступная предварительная версия) | Нет (рекомендация: модель глубокого исследования с помощью средства поиска в Интернете) |
| Агент данных Fabric | Да (общедоступная предварительная версия) | Да (общедоступная предварительная версия) |
| Поиск файлов | Да (GA) | Да (GA) |
| Функции | Да (GA) | Да (GA) |
| Ознакомление с поиском Bing | Да (GA) | Да (GA) |
| Интеграция с помощью пользовательского поиска Bing | Да (общедоступная предварительная версия) | Да (общедоступная предварительная версия) |
| Создание образа | Нет | Да (общедоступная предварительная версия) |
| MCP | Да (общедоступная предварительная версия) | Да (GA) |
| OpenAPI | Да (GA) | Да (GA) |
| Основы SharePoint | Да (общедоступная предварительная версия) | Да (общедоступная предварительная версия) |
| Поиск в Интернете | Нет | Да (GA) |
Важно
В новом API, API бесед и ответов используют клиент OpenAI (или эквивалент языка). В Python вызовите project.get_openai_client(). В C#используйте projectClient.ProjectOpenAIClient.GetProjectResponsesClientForAgent(). В JavaScript вызовите projectClient.getOpenAIClient(). В Java используйте AgentsClientBuilder для создания ResponsesClient. Создание агента и управление версиями остаются на клиенте проекта. В примерах в каждом разделе показано, какой клиент следует использовать.
Перенос потоков в беседы
Потоки хранимых сообщений на стороне сервера. Беседа может хранить элементы, включая сообщения, вызовы инструментов, выходные данные и другие данные.
Запросы
В следующих примерах сравнивается создание потока (предыдущий) с созданием беседы (текущий). Текущий подход использует клиент OpenAI, полученный из project.get_openai_client().
Предыдущий - потоки выполнения
thread = client.agents.threads.create(
messages=[{"role": "user", "content": "Tell me a one line funny story about unicorns"}],
metadata={"agent": "my-awesome-agent"},
)
Текущие — беседы
conversation = openai.conversations.create(
items=[
{
"type": "message",
"role": "user",
"content": "Tell me a one line funny "
"story about unicorns",
}
],
metadata={"agent": "my-awesome-agent"},
)
Ответы
Ответы JSON показывают структурные различия между объектами потоков и объектами беседы.
Предыдущий - потоки выполнения
{
"id": "thread_1234abcd",
"object": "thread",
"created_at": 1762217858,
"metadata": {"agent": "my-awesome-agent"},
"tool_resources": {}
}
Текущие — беседы
{
"id":"conv_1234abcd",
"created_at":1762217961,
"metadata":{"agent":"my-awesome-agent"},
"object":"conversation"
}
Добавление элементов в существующую беседу
После создания беседы используйте conversations.items.create() для добавления последующих сообщений. Этот шаблон заменяет добавление сообщений в потоки с помощью client.agents.messages.create().
Предыдущий: добавьте сообщение в поток
message = client.agents.messages.create(
thread_id=thread.id,
role="user",
content="Follow-up question about the same topic",
)
Current - добавление элементов в чат
openai.conversations.items.create(
conversation_id=conversation.id,
items=[
{
"type": "message",
"role": "user",
"content": "Follow-up question "
"about the same topic",
}
],
)
Перенос запусков в ответы
Запуски были асинхронными процессами, выполняемыми с использованием потоков. Ответы проще: предоставьте набор входных элементов для выполнения и получения списка выходных элементов обратно. Ответы можно использовать отдельно или с объектами беседы для хранения контекста. API ответов использует клиент OpenAI.
Запросы
В следующих примерах сравнивают, как вызывается логика агента. Предыдущий подход задействовал асинхронные запуски с использованием опроса. Текущий подход предусматривает вызов responses.create() на клиенте OpenAI.
Предыдущие — запуски
thread_id = "thread_abcd1234"
assistant_id = "asst_efgh5678"
run = project_client.agents.runs.create(
thread_id=thread_id,
agent_id=assistant_id,
additional_instructions="Please address the user as Jane Doe. The user has a premium account"
)
while run.status in ("queued", "in_progress"):
time.sleep(1)
run = project_client.agents.runs.get(thread_id=thread_id, run_id=run.id)
Текущие — ответы
conversation_id = "conv_11112222AAAABBBB"
response = openai.responses.create(
input="Hi, Agent! Draw a graph for a line "
"with a slope of 4 and "
"y-intercept of 9.",
conversation=conversation_id,
extra_body={
"agent_reference": {
"name": "my-agent",
"type": "agent_reference",
}
},
)
Ответы
Предыдущие — запуски
{
"id": "run_xyz",
"object": "thread.run",
"created_at": 1762218810,
"assistant_id": "asst_efgh5678",
"thread_id": "thread_abcd1234",
"status": "completed",
"started_at": 1762218810,
"expires_at": null,
"cancelled_at": null,
"failed_at": null,
"completed_at": 1762218812,
"required_action": null,
"last_error": null,
"model": "gpt-4.1",
"instructions": "You politely help with math questions. Use the Code Interpreter tool when asked to visualize numbers. Please address the user as Jane Doe. The user has a premium account",
"tools": [
{
"type": "code_interpreter"
}
],
"tool_resources": {},
"metadata": {},
"temperature": 1.0,
"top_p": 1.0,
"max_completion_tokens": null,
"max_prompt_tokens": null,
"truncation_strategy": {
"type": "auto",
"last_messages": null
},
"incomplete_details": null,
"usage": {
"prompt_tokens": 1216,
"completion_tokens": 76,
"total_tokens": 1292,
"prompt_token_details": {
"cached_tokens": 0
}
},
"response_format": "auto",
"tool_choice": "auto",
"parallel_tool_calls": true
}
Текущие — ответы
{
"id": "resp_3483e9c8dda4f165006909550333588190afc76a645a0e877a",
"created_at": 1762219267.0,
"error": null,
"incomplete_details": null,
"instructions": null,
"metadata": {
"x-ms-telemetry-agent-kind": "",
"x-ms-telemetry-user-agent": "OpenAI/Python 2.4.0",
"x-ms-telemetry-response-start-time": "2025-11-04T01:21:06.5346780+00:00"
},
"model": "gpt-4.1",
"object": "response",
"output": [
{
"id": "msg_3483e9c8dda4f1650069095503abf881909917865574cddf2c",
"content": [
{
"annotations": [],
"text": "Of course! Here's a simple plot for the line with a rate of change of 4 and a y-intercept of 9.\\n\\nThe equation of the line is:\\n\\n\\\\[ y = 4x + 9 \\\\]\\n\\nLet's draw a graph for it:\\n\\n---\\n\\n```plaintext\\n |\\n20| *\\n | *\\n | *\\n | *\\n10| *\\n | *\\n | *\\n |*\\n +---------------------------\\n -2 -1 0 1 2 3\\n```\\n\\n**Key points:**\\n- The y-intercept is **9**, so at \\\\(x = 0\\\\), \\\\(y = 9\\\\) (point: (0,9))\\n- For each step right (increase in x), y goes up 4 units (rate of change \\\\(m = 4\\\\))\\n - For \\\\(x = 1\\\\): \\\\(y = 4(1) + 9 = 13\\\\) (point: (1,13))\\n - For \\\\(x = -1\\\\): \\\\(y = 4(-1) + 9 = 5\\\\) (point: (-1,5))\\n\\nIf you'd like a precise graph or want to visualize it interactively, let me know!",
"type": "output_text",
"logprobs": []
}
],
"role": "assistant",
"status": "completed",
"type": "message"
}
],
"parallel_tool_calls": true,
"temperature": 1.0,
"tool_choice": "auto",
"tools": [],
"top_p": 1.0,
"background": false,
"conversation": {
"id": "conv_3483e9c8dda4f16500GwcAgtdWlSmbMPzYLjWvDjiSe6LSFcC6"
},
"max_output_tokens": null,
"max_tool_calls": null,
"previous_response_id": null,
"prompt": null,
"prompt_cache_key": null,
"reasoning": {
"effort": null,
"generate_summary": null,
"summary": null
},
"safety_identifier": null,
"service_tier": "default",
"status": "completed",
"text": {
"format": {
"type": "text"
},
"verbosity": "medium"
},
"top_logprobs": 0,
"truncation": "disabled",
"usage": {
"input_tokens": 45,
"input_tokens_details": {
"cached_tokens": 0
},
"output_tokens": 264,
"output_tokens_details": {
"reasoning_tokens": 0
},
"total_tokens": 309
},
"user": null,
"content_filters": null,
"store": true
}
Перенос классических агентов на новые агенты
Если вы используете client.agents.create_agent() метод из более ранних версий пакета SDK, перейдите в client.agents.create_version(). Новый метод вводит структурированные определения агента с явными полями kind, model и instructions.
Запросы
Предыдущей
agent = client.agents.create_agent(
model="gpt-4.1",
name="my-agent", # Name of the agent
instructions="You politely help with math questions. Use the Code Interpreter tool when asked to visualize numbers.", # Instructions for the agent
tools=code_interpreter.definitions, # Attach the tool
)
Текущий
from azure.ai.projects.models import (
CodeInterpreterTool,
PromptAgentDefinition,
)
agent = project.agents.create_version(
agent_name="my-agent",
definition=PromptAgentDefinition(
model="gpt-4.1",
instructions=(
"You politely help with math "
"questions. Use the Code "
"Interpreter tool when asked to "
"visualize numbers."
),
tools=[CodeInterpreterTool()],
),
)
Ответы
В следующих примерах JSON сравниваются объекты ответа, возвращаемые предыдущими и текущими методами создания агента.
Предыдущей
{
'id': 'asst_AVKrdr2KJthDnZiJ51nca1jy',
'object': 'assistant',
'created_at': 1762218496,
'name': 'my-agent',
'description': None,
'model': 'gpt-4.1',
'instructions': 'You politely help with math questions. Use the Code Interpreter tool when asked to visualize numbers.',
'tools': [
{
'type': 'code_interpreter'
}
],
'top_p': 1.0,
'temperature': 1.0,
'tool_resources': {
'code_interpreter': {
'file_ids': [
]
}
},
'metadata': {
},
'response_format': 'auto'
}
Текущий
{
"metadata": {},
"object": "agent.version",
"id": "code-agent:1",
"name": "code-agent",
"version": "1",
"description": "Agent with code interpreter",
"created_at": 1772045947,
"definition": {
"kind": "prompt",
"model": "gpt-4.1",
"instructions": "You politely help with math questions. Use the Code Interpreter tool when asked to visualize numbers.",
"tools": [
{
"type": "code_interpreter"
}
]
}
}
Перенос помощников на новые агенты
Если в коде используется API OpenAI Assistants (client.beta.assistants.create()), перейдите в службу агента Foundry с помощью client.agents.create_version(). В следующих примерах показаны структурные различия.
Предыдущие — помощники
assistant = client.beta.assistants.create(
model="gpt-4.1",
name="my-assistant",
instructions="You politely help with math questions. Use the Code Interpreter tool when asked to visualize numbers.", # Instructions for the agent
tools=[{"type": "code_interpreter"}],
)
Current — новые агенты
from azure.ai.projects.models import (
CodeInterpreterTool,
PromptAgentDefinition,
)
agent = project.agents.create_version(
agent_name="my-agent",
definition=PromptAgentDefinition(
model="gpt-4.1",
instructions=(
"You politely help with math "
"questions. Use the Code "
"Interpreter tool when asked to "
"visualize numbers."
),
tools=[CodeInterpreterTool()],
),
)
Запуск средства миграции
Средство migration доступно на GitHub для автоматизации миграции агентов и помощников. Средство переносит конструкции кода, такие как определения агента, создание потока, создание сообщения и создание запуска. Он не переносит данные о состоянии, такие как прошлые запуски, потоки или сообщения. После миграции можно запустить новый код, а все новые данные состояния создаются в обновленном формате.
В следующем примере показано полное сравнение до и после. Обратите внимание, что текущий код использует project для создания агента и openai для бесед и ответов.
Предыдущей
agent = project_client.agents.create_agent(
model="gpt-4.1",
name="my-agent",
instructions="You politely help with math questions. Use the Code Interpreter tool when asked to visualize numbers.", # Instructions for the agent
tools=[{"type": "code_interpreter"}]
)
thread = project_client.agents.threads.create()
message = project_client.agents.messages.create(
thread_id=thread.id,
role="user", # Role of the message sender
content="Hi, Agent! Draw a graph for a line with a rate of change of 4 and y-intercept of 9.", # Message content
)
run = project_client.agents.runs.create_and_process(
thread_id=thread.id,
agent_id=agent.id,
additional_instructions="Please address the user as Jane Doe. The user has a premium account",
)
messages = project_client.agents.messages.list(thread_id=thread.id)
for message in messages:
print(f"Role: {message.role}, Content: {message.content}")
Текущий
from azure.ai.projects.models import (
CodeInterpreterTool,
PromptAgentDefinition,
)
# Create the agent
agent = project.agents.create_version(
agent_name="my-agent",
definition=PromptAgentDefinition(
model="gpt-4.1",
instructions=(
"You politely help with math "
"questions. Use the Code "
"Interpreter tool when asked "
"to visualize numbers."
),
tools=[CodeInterpreterTool()],
),
)
# Create a conversation with initial message
conversation = openai.conversations.create(
items=[
{
"type": "message",
"role": "user",
"content": (
"Hi, Agent! Draw a graph "
"for a line with a rate "
"of change of 4 and "
"y-intercept of 9."
),
}
],
)
# Send a response with the agent
response = openai.responses.create(
conversation=conversation.id,
extra_body={
"agent_reference": {
"name": agent.name,
"type": "agent_reference",
}
},
input=(
"Please address the user as "
"Jane Doe. The user has a "
"premium account"
),
)
# Print the response output
for item in response.output:
if item.type == "message":
for block in item.content:
print(block.text)
Проверка миграции
После переноса кода убедитесь, что все работает правильно:
- Запустите обновленный код и убедитесь, что он выполняется без ошибок.
-
Проверьте создание агента, убедившись что
create_version()возвращает объект с полямиidиversion. - Проверьте беседу, создав её, отправив ответ и убедившись, что возвращаются результаты.
- Подтвердите хранение контекста , отправив несколько ответов в одну беседу и убедив, что агент запоминает предыдущие сообщения.
Устранение распространенных проблем
| Симптом | Причина | Разрешение |
|---|---|---|
Python: AttributeError: 'AIProjectClient' has no attribute 'conversations' |
Вы вызвали функцию conversations.create() на клиенте для проекта вместо клиента OpenAI. |
Используйте project.get_openai_client() для получения клиента OpenAI, а затем вызовите openai.conversations.create(). |
C#: Azure.AI.Extensions.OpenAI пространство имен не найдено |
Отсутствует пакет NuGet Azure.AI.Extensions.OpenAI. |
Установите Azure.AI.Projects (который включает Azure.AI.Extensions.OpenAI и Azure.AI.Projects.Agents в качестве зависимостей). |
JavaScript: getOpenAIClient is not a function |
Вы используете более раннюю версию @azure/ai-projects. |
Обновление до @azure/ai-projects@2.0.0 или более поздней версии: npm install @azure/ai-projects@2.0.0 |
Java: AgentsClientBuilder не удаётся определить |
azure-ai-agents Зависимость Maven отсутствует или устарела. |
Добавьте com.azure:azure-ai-agents:2.0.0 в зависимости для pom.xml. |
create_agent() удаляется |
Ранние версии SDK использовали create_agent(), который был удалён в версии 2.0.0. |
Замените create_version() (Python/JS) или CreateAgentVersionAsync() (C#) или createAgentVersion() (Java) и передайте объект PromptAgentDefinition. |
| Старые данные треда недоступны | Средство миграции не переносит данные о состоянии (прошлые запуски, потоки или сообщения). | Запустите новые беседы после миграции. Исторические данные остаются доступными через ранее используемый API до тех пор, пока он не будет выведен из эксплуатации. |
responses.create() Вызывает ошибку модели |
Имя модели может быть неверным или недоступным в вашем регионе. | Проверьте имя модели в проекте Foundry и проверьте доступность региона модели. |