Переход на новый интерфейс разработчика агентов

Совет

Средство миграции доступно для автоматизации миграции из 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)

Проверка миграции

После переноса кода убедитесь, что все работает правильно:

  1. Запустите обновленный код и убедитесь, что он выполняется без ошибок.
  2. Проверьте создание агента, убедившись что create_version() возвращает объект с полями id и version.
  3. Проверьте беседу, создав её, отправив ответ и убедившись, что возвращаются результаты.
  4. Подтвердите хранение контекста , отправив несколько ответов в одну беседу и убедив, что агент запоминает предыдущие сообщения.

Устранение распространенных проблем

Симптом Причина Разрешение
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 и проверьте доступность региона модели.