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

Использование инструмента для работы с компьютером для агентов (бета-версия)

Это важно

Элементы, обозначенные в этой статье как (предварительная версия), сейчас предлагаются в общедоступной предварительной версии. Эта предварительная версия предоставляется без соглашения об уровне обслуживания, и мы не рекомендуем ее для рабочих нагрузок. Некоторые функции могут не поддерживаться или их возможности могут быть ограничены. Дополнительные сведения см. в разделе Supplemental Terms of Use for Microsoft Azure Previews.

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

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

Создайте агенты, которые интерпретируют снимки экрана и автоматизируют взаимодействие пользовательского интерфейса, например щелчки, ввод и прокрутку. Инструмент использования компьютера использует computer-use-preview модель, чтобы предлагать действия на основе визуального контента, что позволяет агентам взаимодействовать с приложениями для настольных компьютеров и браузеров через их пользовательские интерфейсы.

В этом руководстве показано, как интегрировать средство использования компьютера в цикл приложения (снимок экрана → действие → снимок экрана) с помощью последних пакетов SDK.

Поддержка использования

В следующей таблице показана поддержка пакета SDK и настройки.

Поддержка Microsoft Foundry пакет SDK Python Пакет SDK для C# Пакет SDK для JavaScript пакет SDK Java REST API Базовая настройка агента Настройка стандартного агента
✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️

Предпосылки

Фрагменты кода, приведенные в этой статье, сосредоточены на интеграции с API агента и ответов. Для комплексного запускаемого примера, включающего вспомогательный код и примеры снимок экрана, используйте примеры пакета SDK в GitHub.

Подсказка

Примеры пакета SDK включают вспомогательные служебные программы для записи снимка экрана, выполнения действий и кодирования изображений. Клонируйте репозиторий или скопируйте эти файлы в проект перед выполнением примеров.

Запрос на доступ

Чтобы получить доступ к computer-use-preview модели, необходимо зарегистрировать. Корпорация Майкрософт предоставляет доступ на основе критериев соответствия требованиям. Если у вас есть доступ к другим моделям ограниченного доступа, вам по-прежнему нужно запросить доступ к этой модели.

Чтобы запросить доступ, ознакомьтесь с формой приложения.

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

Примеры кода

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

Используйте средство использования компьютера на виртуальных машинах без доступа к конфиденциальным данным или критически важным ресурсам. Дополнительные сведения о предполагаемых вариантах использования, возможностях, ограничениях, рисках и рекомендациях при выборе варианта использования см. в заметке о прозрачности Azure OpenAI.

Вам нужен последний пакет SDK. Пакет SDK для .NET в настоящее время находится в предварительной версии.

Скриншот инициализации для выполнения инструмента на компьютере

В следующем примере кода показано, как создать версию агента с помощью средства использования компьютера, отправить начальный запрос с снимок экрана и выполнить несколько итераций для выполнения задачи.

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition, ComputerUsePreviewTool

# Import shared helper functions
from computer_use_util import (
    SearchState,
    load_screenshot_assets,
    handle_computer_action_and_take_screenshot,
    print_final_output,
)

"""Main function to demonstrate Computer Use Agent functionality."""
# Initialize state machine
current_state = SearchState.INITIAL

# Load screenshot assets
try:
    screenshots = load_screenshot_assets()
    print("Successfully loaded screenshot assets")
except FileNotFoundError:
    print("Failed to load required screenshot assets. Use the maintained SDK sample on GitHub to get the helper file and images.")
    exit(1)

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

# Format: "https://resource_name.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"

project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)

computer_use_tool = ComputerUsePreviewTool(display_width=1026, display_height=769, environment="windows")

agent = project.agents.create_version(
    agent_name="ComputerUseAgent",
    definition=PromptAgentDefinition(
        model="computer-use-preview",
        instructions="""
        You are a computer automation assistant. 

        Be direct and efficient. When you reach the search results page, read and describe the actual search result titles and descriptions you can see.
        """,
        tools=[computer_use_tool],
    ),
    description="Computer automation agent with screen interaction capabilities.",
)
print(f"Agent created (id: {agent.id}, name: {agent.name})")

Одна итерация для инструмента для обработки снимка экрана и выполнения следующего шага

openai = project.get_openai_client()

# Initial request with screenshot - start with Bing search page
response = openai.responses.create(
    input=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "I need you to help me search for 'OpenAI news'. Please type 'OpenAI news' and submit the search. Once you see search results, the task is complete.",
                },
                {
                    "type": "input_image",
                    "image_url": screenshots["browser_search"]["url"],
                    "detail": "high",
                },  # Start with Bing search page
            ],
        }
    ],
    extra_body={"agent_reference": {"name": agent.name, "type": "agent_reference"}},
    truncation="auto",
)

print(f"Initial response received (ID: {response.id})")

Выполнение нескольких итераций

Убедитесь, что вы просматриваете каждую итерацию и действие. В следующем примере кода показан базовый запрос API. После отправки начального запроса API выполните цикл, в котором код приложения выполняет указанное действие. Отправьте снимок экрана с каждым поворотом, чтобы модель может оценить обновленное состояние среды. В примере содержится максимальное количество итераций, чтобы предотвратить бесконечные циклы, но это можно изменить по мере необходимости.


max_iterations = 10  # Allow enough iterations for completion
iteration = 0

while True:
    if iteration >= max_iterations:
        print(f"\nReached maximum iterations ({max_iterations}). Stopping.")
        break

    iteration += 1
    print(f"\n--- Iteration {iteration} ---")

    # Check for computer calls in the response
    computer_calls = [item for item in response.output if item.type == "computer_call"]

    if not computer_calls:
        print_final_output(response)
        break

    # Process the first computer call
    computer_call = computer_calls[0]
    action = computer_call.action
    call_id = computer_call.call_id

    # Handle the action and get the screenshot info
    screenshot_info, current_state = handle_computer_action_and_take_screenshot(action, current_state, screenshots)

    # Regular response with just the screenshot
    response = openai.responses.create(
        previous_response_id=response.id,
        input=[
            {
                "call_id": call_id,
                "type": "computer_call_output",
                "output": {
                    "type": "computer_screenshot",
                    "image_url": screenshot_info["url"],
                },
            }
        ],
        extra_body={"agent_reference": {"name": agent.name, "type": "agent_reference"}},
        truncation="auto",
    )

    print(f"Iteration {iteration}: response received (ID: {response.id})")

Очистка

project.agents.delete_version(agent_name=agent.name, agent_version=agent.version)
print("Agent deleted")

Ожидаемые выходные данные

В следующем примере показаны ожидаемые выходные данные при выполнении предыдущего примера кода:

Successfully loaded screenshot assets
Agent created (id: ..., name: ComputerUseAgent, version: 1)
Starting computer automation session (initial screenshot: cua_browser_search.png)...
Initial response received (ID: ...)
--- Iteration 1 ---
Processing computer call (ID: ...)
  Typing text "OpenAI news" - Simulating keyboard input
  -> Action processed: type
Sending action result back to agent (using cua_search_typed.png)...
Follow-up response received (ID: ...)
--- Iteration 2 ---
Processing computer call (ID: ...)
    Click at (512, 384) - Simulating click on UI element
    -> Assuming click on Search button when search field was populated, displaying results.
    -> Action processed: click
Sending action result back to agent (using cua_search_results.png)...
Follow-up response received (ID: ...)
OpenAI news - Latest Updates
Agent deleted

Пример использования агента с инструментом "Использование компьютера"

В следующем примере кода C# показано, как создать версию агента с помощью средства использования компьютера, отправить первоначальный запрос с снимок экрана и выполнить несколько итераций для выполнения задачи. Чтобы разрешить агенту использовать средство использования компьютера, используйте ResponseTool.CreateComputerTool() при настройке средств агента. В этом примере используется синхронный код. Сведения об асинхронном использовании см. в примере кода sample в Azure SDK для репозитория .NET в GitHub.

using System;
using System.Runtime.CompilerServices;
using Azure.AI.Projects;
using Azure.AI.Extensions.OpenAI;
using Azure.Identity;

class ComputerUseDemo
{
    // Format: "https://resource_name.ai.azure.com/api/projects/project_name"
    private const string ProjectEndpoint = "your_project_endpoint";

    // Read image files using `ReadImageFile` method.
    private static BinaryData ReadImageFile(string name, [CallerFilePath] string pth = "")
    {
        var dirName = Path.GetDirectoryName(pth) ?? "";
        return new BinaryData(File.ReadAllBytes(Path.Combine(dirName, name)));
    }

    // Create a helper method to parse the ComputerTool outputs and to respond
    // to Agents queries with new screenshots. Note that throughout
    // this sample the media type for image is set. Agents support `image/jpeg`,
    // `image/png`, `image/gif` and `image/webp` media types.
    private static string ProcessComputerUseCall(ComputerCallResponseItem item, string oldScreenshot)
    {
        string currentScreenshot = "browser_search";
        switch (item.Action.Kind)
        {
            case ComputerCallActionKind.Type:
                Console.WriteLine($"  Typing text \"{item.Action.TypeText}\" - Simulating keyboard input");
                currentScreenshot = "search_typed";
                break;
            case ComputerCallActionKind.KeyPress:
                HashSet<string> codes = new(item.Action.KeyPressKeyCodes);
                if (codes.Contains("Return") || codes.Contains("ENTER"))
                {
                    // If we have typed the value to the search field, go to search results.
                    if (string.Equals(oldScreenshot, "search_typed"))
                    {
                        Console.WriteLine("  -> Detected ENTER key press, when search field was populated, displaying results.");
                        currentScreenshot = "search_results";
                    }
                    else
                    {
                        Console.WriteLine("  -> Detected ENTER key press, on results or unpopulated search, do nothing.");
                        currentScreenshot = oldScreenshot;
                    }
                }
                else
                {
                    Console.WriteLine($"  Key press: {item.Action.KeyPressKeyCodes.Aggregate("", (agg, next) => agg + "+" + next)} - Simulating key combination");
                }
                break;
            case ComputerCallActionKind.Click:
                Console.WriteLine($"  Click at ({item.Action.ClickCoordinates.Value.X}, {item.Action.ClickCoordinates.Value.Y}) - Simulating click on UI element");
                if (string.Equals(oldScreenshot, "search_typed"))
                {
                    Console.WriteLine("  -> Assuming click on Search button when search field was populated, displaying results.");
                    currentScreenshot = "search_results";
                }
                else
                {
                    Console.WriteLine("  -> Assuming click on Search on results or when search was not populated, do nothing.");
                    currentScreenshot = oldScreenshot;
                }
                break;
            case ComputerCallActionKind.Drag:
                string pathStr = item.Action.DragPath.ToArray().Select(p => $"{p.X}, {p.Y}").Aggregate("", (agg, next) => $"{agg} -> {next}");
                Console.WriteLine($"  Drag path: {pathStr} - Simulating drag operation");
                break;
            case ComputerCallActionKind.Scroll:
                Console.WriteLine($"  Scroll at ({item.Action.ScrollCoordinates.Value.X}, {item.Action.ScrollCoordinates.Value.Y}) - Simulating scroll action");
                break;
            case ComputerCallActionKind.Screenshot:
                Console.WriteLine("  Taking screenshot - Capturing current screen state");
                break;
            default:
                break;
        }
        Console.WriteLine($"  -> Action processed: {item.Action.Kind}");

        return currentScreenshot;
    }

    public static void Main()
    {
        // Create project client
        AIProjectClient projectClient = new(endpoint: new Uri(ProjectEndpoint), tokenProvider: new DefaultAzureCredential());

        // Read in three example screenshots and place them into a dictionary.
        Dictionary<string, BinaryData> screenshots = new() {
            { "browser_search", ReadImageFile("Assets/cua_browser_search.png")},
            { "search_typed", ReadImageFile("Assets/cua_search_typed.png")},
            { "search_results", ReadImageFile("Assets/cua_search_results.png")},
        };

        // Create a PromptAgentDefinition with ComputerTool.
        DeclarativeAgentDefinition agentDefinition = new(model: "computer-use-preview")
        {
            Instructions = "You are a computer automation assistant.\n\n" +
                            "Be direct and efficient. When you reach the search results page, read and describe the actual search result titles and descriptions you can see.",
            Tools = {
                ResponseTool.CreateComputerTool(
                    environment: new ComputerToolEnvironment("windows"),
                    displayWidth: 1026,
                    displayHeight: 769
                ),
            }
        };
        AgentVersion agentVersion = projectClient.AgentAdministrationClient.CreateAgentVersion(
            agentName: "myAgent",
            options: new(agentDefinition)
        );
        // Create an `ResponseResult` using `ResponseItem`, containing two `ResponseContentPart`:
        // one with the image and another with the text. In the loop, request Agent
        // while it is continuing to browse web. Finally, print the tool output message.
        ProjectResponsesClient responseClient = projectClient.ProjectOpenAIClient.GetProjectResponsesClientForAgent(agentVersion.Name);
        CreateResponseOptions responseOptions = new()
        {
            TruncationMode = ResponseTruncationMode.Auto,
            InputItems =
            {
                ResponseItem.CreateUserMessageItem(
                [
                    ResponseContentPart.CreateInputTextPart("I need you to help me search for 'OpenAI news'. Please type 'OpenAI news' and submit the search. Once you see search results, the task is complete."),
                    ResponseContentPart.CreateInputImagePart(imageBytes: screenshots["browser_search"], imageBytesMediaType: "image/png", imageDetailLevel: ResponseImageDetailLevel.High)
                ]),
            },
        };
        bool computerUseCalled = false;
        string currentScreenshot = "browser_search";
        int limitIteration = 10;
        ResponseResult response;
        do
        {
            response = responseClient.CreateResponse(responseOptions);
            computerUseCalled = false;
            responseOptions.InputItems.Clear();
            responseOptions.PreviousResponseId = response.Id;
            foreach (ResponseItem responseItem in response.OutputItems)
            {
                responseOptions.InputItems.Add(responseItem);
                if (responseItem is ComputerCallResponseItem computerCall)
                {
                    currentScreenshot = ProcessComputerUseCall(computerCall, currentScreenshot);
                    responseOptions.InputItems.Add(ResponseItem.CreateComputerCallOutputItem(callId: computerCall.CallId, output: ComputerCallOutput.CreateScreenshotOutput(screenshotImageBytes: screenshots[currentScreenshot], screenshotImageBytesMediaType: "image/png")));
                    computerUseCalled = true;
                }
            }
            limitIteration--;
        } while (computerUseCalled && limitIteration > 0);
        Console.WriteLine(response.GetOutputText());

        // Clean up resources by deleting Agent.
        projectClient.AgentAdministrationClient.DeleteAgentVersion(agentName: agentVersion.Name, agentVersion: agentVersion.Version);
    }
}

Ожидаемые выходные данные

В следующем примере показаны ожидаемые выходные данные при выполнении предыдущего примера кода:

Agent created (id: ..., name: myAgent, version: 1)
Starting computer automation session (initial screenshot: cua_browser_search.png)...
Initial response received (ID: ...)
--- Iteration 1 ---
Processing computer call (ID: ...)
  Typing text "OpenAI news" - Simulating keyboard input
  -> Action processed: Type
Sending action result back to agent (using cua_search_typed.png)...
Follow-up response received (ID: ...)
--- Iteration 2 ---
Processing computer call (ID: ...)
  Click at (512, 384) - Simulating click on UI element
  -> Assuming click on Search button when search field was populated, displaying results.
  -> Action processed: Click
Sending action result back to agent (using cua_search_results.png)...
Follow-up response received (ID: ...)
OpenAI news - Latest Updates
Agent deleted

Пример использования агента с инструментом "Использование компьютера"

В следующем примере кода TypeScript показано, как создать версию агента с помощью средства использования компьютера, отправить начальный запрос с снимок экрана и выполнить несколько итераций для выполнения задачи. Пример JavaScript см. в коде sample в репозитории JavaScript Azure SDK на GitHub.

import { DefaultAzureCredential } from "@azure/identity";
import { AIProjectClient } from "@azure/ai-projects";
import {
  SearchState,
  loadScreenshotAssets,
  handleComputerActionAndTakeScreenshot,
  printFinalOutput,
  type ComputerAction,
} from "./computerUseUtil.js";

// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
const PROJECT_ENDPOINT = "your_project_endpoint";

export async function main(): Promise<void> {
  // Initialize state machine
  let currentState = SearchState.INITIAL;

  // Load screenshot assets
  const screenshots = loadScreenshotAssets();
  console.log("Successfully loaded screenshot assets");

  // Create AI Project client
  const project = new AIProjectClient(PROJECT_ENDPOINT, new DefaultAzureCredential());
  const openai = project.getOpenAIClient();

  console.log("Creating Computer Use Agent...");
  const agent = await project.agents.createVersion("ComputerUseAgent", {
    kind: "prompt" as const,
    model: "computer-use-preview",
    instructions: `
You are a computer automation assistant.

Be direct and efficient. When you reach the search results page, read and describe the actual search result titles and descriptions you can see.
    `.trim(),
    tools: [
      {
        type: "computer_use_preview",
        display_width: 1026,
        display_height: 769,
        environment: "windows" as const,
      },
    ],
  });
  console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);

  // Initial request with screenshot - start with Bing search page
  console.log(
    "Starting computer automation session (initial screenshot: cua_browser_search.png)...",
  );
  let response = await openai.responses.create(
    {
      input: [
        {
          role: "user" as const,
          content: [
            {
              type: "input_text",
              text: "I need you to help me search for 'OpenAI news'. Please type 'OpenAI news' and submit the search. Once you see search results, the task is complete.",
            },
            {
              type: "input_image",
              image_url: screenshots.browser_search.url,
              detail: "high",
            },
          ],
        },
      ],
      truncation: "auto",
    },
    {
      body: { agent: { name: agent.name, type: "agent_reference" } },
    },
  );

  console.log(`Initial response received (ID: ${response.id})`);

  // Main interaction loop with deterministic completion
  const maxIterations = 10; // Allow enough iterations for completion
  let iteration = 0;

  while (iteration < maxIterations) {
    iteration++;
    console.log(`\n--- Iteration ${iteration} ---`);

    // Check for computer calls in the response
    const computerCalls = response.output.filter((item) => item.type === "computer_call");

    if (computerCalls.length === 0) {
      printFinalOutput({
        output: response.output,
        status: response.status ?? "",
      });
      break;
    }

    // Process the first computer call
    const computerCall = computerCalls[0];
    const action: ComputerAction = computerCall.action;
    const callId: string = computerCall.call_id;

    console.log(`Processing computer call (ID: ${callId})`);

    // Handle the action and get the screenshot info
    const [screenshotInfo, updatedState] = handleComputerActionAndTakeScreenshot(
      action,
      currentState,
      screenshots,
    );
    currentState = updatedState;

    console.log(`Sending action result back to agent (using ${screenshotInfo.filename})...`);
    // Regular response with just the screenshot
    response = await openai.responses.create(
      {
        previous_response_id: response.id,
        input: [
          {
            call_id: callId,
            type: "computer_call_output",
            output: {
              type: "computer_screenshot",
              image_url: screenshotInfo.url,
            },
          },
        ],
        truncation: "auto",
      },
      {
        body: { agent: { name: agent.name, type: "agent_reference" } },
      },
    );

    console.log(`Follow-up response received (ID: ${response.id})`);
  }

  if (iteration >= maxIterations) {
    console.log(`\nReached maximum iterations (${maxIterations}). Stopping.`);
  }

  // Clean up resources
  console.log("\nCleaning up...");
  await project.agents.deleteVersion(agent.name, agent.version);
  console.log("Agent deleted");

  console.log("\nComputer Use Agent sample completed!");
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
});

Ожидаемые выходные данные

В следующем примере показаны ожидаемые выходные данные при выполнении предыдущего примера кода:

Successfully loaded screenshot assets
Creating Computer Use Agent...
Agent created (id: ..., name: ComputerUseAgent, version: 1)
Starting computer automation session (initial screenshot: cua_browser_search.png)...
Initial response received (ID: ...)
--- Iteration 1 ---
Processing computer call (ID: ...)
  Typing text "OpenAI news" - Simulating keyboard input
  -> Action processed: type
Sending action result back to agent (using cua_search_typed.png)...
Follow-up response received (ID: ...)
--- Iteration 2 ---
Processing computer call (ID: ...)
    Click at (512, 384) - Simulating click on UI element
    -> Assuming click on Search button when search field was populated, displaying results.
    -> Action processed: click
Sending action result back to agent (using cua_search_results.png)...
Follow-up response received (ID: ...)
OpenAI news - Latest Updates
Cleaning up...
Agent deleted
Computer Use Agent sample completed!

Использование компьютерных ресурсов в Java-агенте

Добавьте зависимость в вашу pom.xml:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-ai-agents</artifactId>
    <version>2.0.0</version>
</dependency>

Создание агента использования компьютера

import com.azure.ai.agents.AgentsClient;
import com.azure.ai.agents.AgentsClientBuilder;
import com.azure.ai.agents.ResponsesClient;
import com.azure.ai.agents.models.*;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.openai.models.responses.Response;
import com.openai.models.responses.ResponseCreateParams;

import java.util.Collections;

public class ComputerUseExample {
    // Format: "https://resource_name.ai.azure.com/api/projects/project_name"
    private static final String PROJECT_ENDPOINT = "your_project_endpoint";

    public static void main(String[] args) {

        AgentsClientBuilder builder = new AgentsClientBuilder()
            .credential(new DefaultAzureCredentialBuilder().build())
            .endpoint(PROJECT_ENDPOINT);

        AgentsClient agentsClient = builder.buildAgentsClient();
        ResponsesClient responsesClient = builder.buildResponsesClient();

        // Create computer use tool
        ComputerUsePreviewTool tool = new ComputerUsePreviewTool(
            ComputerEnvironment.WINDOWS,
            1024,
            768
        );

        // Create agent with computer use tool
        PromptAgentDefinition agentDefinition = new PromptAgentDefinition("computer-use-preview")
            .setInstructions("You are a computer automation assistant.")
            .setTools(Collections.singletonList(tool));

        AgentVersionDetails agent = agentsClient.createAgentVersion("computer-use-agent", agentDefinition);
        System.out.printf("Agent created: %s (version %s)%n", agent.getName(), agent.getVersion());

        // Create a response with initial screenshot
        AgentReference agentReference = new AgentReference(agent.getName())
            .setVersion(agent.getVersion());

        Response response = responsesClient.createAzureResponse(
            new AzureCreateResponseOptions().setAgentReference(agentReference),
            ResponseCreateParams.builder()
                .input("Open the browser and navigate to microsoft.com"));

        System.out.println("Response: " + response.output());

        // The response will contain computer_call items with actions
        // to execute. Process each action, take screenshots, and
        // send results back using responsesClient.createAzureResponse()
        // with the previousResponseId and computer call output.

        // Clean up
        agentsClient.deleteAgentVersion(agent.getName(), agent.getVersion());
    }
}

Полный цикл использования компьютера с обработкой снимка экрана см. в примере ComputerUseSync.java.

Использование компьютера для работы с REST API

Получение токена доступа:

export AGENT_TOKEN=$(az account get-access-token --scope "https://ai.azure.com/.default" --query accessToken -o tsv)

Создание агента с использованием компьютера

curl -X POST "$FOUNDRY_PROJECT_ENDPOINT/agents?api-version=v1" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -d '{
    "name": "computer-use-agent",
    "definition": {
      "kind": "prompt",
      "model": "computer-use-preview",
      "instructions": "You are a computer automation assistant.",
      "tools": [
        {
          "type": "computer_use_preview",
          "environment": "windows",
          "display_width": 1024,
          "display_height": 768
        }
      ]
    }
  }'

Создание ответа

curl -X POST "$FOUNDRY_PROJECT_ENDPOINT/openai/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -d '{
    "agent_reference": {"type": "agent_reference", "name": "computer-use-agent"},
    "input": "Open the browser and navigate to microsoft.com"
  }'

Ответ включает computer_call выходные элементы с действиями, которые нужно выполнить. Обработайте каждое действие, захватите снимки экрана и отправьте результаты обратно через конечную точку previous_response_id ответов.

Отправка результатов действия с снимка экрана

После выполнения действия компьютера (например, щелкните или введите), запишите снимок экрана и отправьте его обратно:

curl -X POST "$FOUNDRY_PROJECT_ENDPOINT/openai/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -d '{
    "agent_reference": {"type": "agent_reference", "name": "computer-use-agent"},
    "previous_response_id": "<RESPONSE_ID>",
    "input": [
      {
        "type": "computer_call_output",
        "call_id": "<CALL_ID>",
        "output": {
          "type": "computer_screenshot",
          "image_url": "data:image/png;base64,<BASE64_SCREENSHOT>"
        }
      }
    ]
  }'

Замените <RESPONSE_ID>, <CALL_ID>а <BASE64_SCREENSHOT> также значениями из предыдущего ответа. Повторяйте этот цикл, пока модель не возвратит текстовый ответ вместо computer_call.

Очистка

curl -X DELETE "$FOUNDRY_PROJECT_ENDPOINT/agents/computer-use-agent?api-version=v1" \
  -H "Authorization: Bearer $AGENT_TOKEN"

Что можно сделать с помощью средства использования компьютера

После интеграции цикла запроса и ответа (снимок экрана —> действие —> снимок экрана), средство использования компьютера может помочь агенту:

  • Предложение действий пользовательского интерфейса, таких как щелчки, ввод, прокрутка и запрос нового снимка экрана.
  • Адаптация к изменениям пользовательского интерфейса путем повторной оценки последнего снимка экрана после каждого действия.
  • Работа с браузером и интерфейсом рабочего стола в зависимости от способа размещения вашей песочницы.

Средство не управляет устройством напрямую. Приложение выполняет каждое запрошенное действие и возвращает обновленный снимок экрана.

Различия между автоматизацией браузера и использованием компьютера

В следующей таблице перечислены некоторые различия между средством использования компьютера и средством автоматизации браузера .

Функция Автоматизация браузера Инструмент использования компьютера
Поддержка модели Все модели GPT Computer-use-preview только модель
Можно ли визуализировать то, что происходит? нет Да
Как он понимает экран Анализирует HTML-страницы или XML-страницы в документы DOM Необработанные данные пикселей на снимках экрана
Как он действует Список действий, предоставляемых моделью Виртуальная клавиатура и мышь
Это многоэтапный? Да Да
Интерфейсы Browser Компьютер и браузер
Нужно ли принести собственный ресурс? Собственный ресурс Playwright с ключами, хранящимися в качестве подключения. Дополнительный ресурс не требуется, но настоятельно рекомендуется запускать это средство в изолированной среде.

Когда следует использовать каждое средство

Выберите компьютер, используемый при необходимости:

  • Взаимодействие с классическими приложениями за пределами браузера
  • Визуализация того, что агент видит с помощью снимка экрана
  • Работа в средах, где синтаксический анализ DOM недоступен

Выберите автоматизацию браузера, когда необходимо:

  • Выполнение взаимодействия только в Интернете без требований к доступу
  • Используйте любую модель GPT (не ограничено computer-use-preview)
  • Избегайте управления снимками экрана и циклами выполнения действий

Региональная поддержка

Чтобы использовать инструмент работы с компьютером, вам потребуется развертывание модели работы с компьютером. Модель использования компьютера доступна в следующих регионах:

Регион Состояние
eastus2 В наличии
swedencentral В наличии
southindia В наличии

Понимание интеграции использования компьютера

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

  1. Отправьте запрос к модели, включающий вызов инструмента использования компьютера, размер дисплея и среду. Вы также можете включить снимок экрана начального состояния среды в первом запросе API.

  2. Получите ответ от модели. Если ответ содержит элементы действия, эти элементы содержат предлагаемые действия для достижения прогресса в достижении указанной цели. Например, действие может быть screenshot таким, чтобы модель могла оценить текущее состояние с обновленным снимком экрана или click координатами X/Y, указывающими, где нужно переместить мышь.

  3. Выполните действие с помощью кода приложения на компьютере или в браузере.

  4. После выполнения действия зафиксировать обновленное состояние среды в виде снимка экрана.

  5. Отправьте новый запрос с обновленным состоянием в виде tool_call_outputи повторите этот цикл, пока модель не перестанет запрашивать действия или вы решили остановиться.

    Замечание

    Перед использованием средства настройте среду, которая может записывать снимки экрана и выполнять рекомендуемые действия агента. По соображениям безопасности используйте песочницу, например Playwright.

Управление журналом бесед

previous_response_id Используйте параметр, чтобы связать текущий запрос с предыдущим ответом. Используйте этот параметр, если вы не хотите отправлять полный журнал бесед с каждым вызовом.

Если этот параметр не используется, обязательно включите все элементы, возвращенные в выходные данные ответа предыдущего запроса в массиве входных данных. Это требование включает элементы обоснования, если они присутствуют.

Вопросы безопасности и проверки безопасности

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

Использование компьютера несет существенные риски безопасности и конфиденциальности и ответственность за пользователя. Обе ошибки в решении ИИ и наличие вредоносных или запутанных инструкций на веб-страницах, настольных компьютерах или других операционных средах, с которыми сталкивается ИИ, могут привести к выполнению команд, которые вы или другие не намерены. Эти риски могут угрожать безопасности ваших или других пользователей, браузеров, компьютеров и любых учетных записей, к которым ИИ имеет доступ, включая персональные, финансовые или корпоративные системы.

Используйте средство использования компьютера на виртуальных машинах без доступа к конфиденциальным данным или критически важным ресурсам. Дополнительные сведения о предполагаемых вариантах использования, возможностях, ограничениях, рисках и рекомендациях при выборе варианта использования см. в заметке о прозрачности Azure OpenAI.

API имеет проверки безопасности для защиты от внедрения команд и ошибок моделей. К таким проверкам относятся:

Обнаружение вредоносных инструкций: система оценивает изображение снимка экрана и проверяет, содержит ли он состязательный контент, который может изменить поведение модели.

Обнаружение нерелевантных доменов: система оценивает current_url параметр (если он указан) и проверяет, актуален ли текущий домен с учетом истории беседы.

Обнаружение конфиденциальногоcurrent_url домена: система проверяет параметр (если указано) и вызывает предупреждение при обнаружении пользователя в конфиденциальном домене.

Если одна или несколько предшествующих проверок активируются, модель инициирует проверку безопасности при возврате следующего computer_call, используя параметр pending_safety_checks.

"output": [ 
    { 
        "type": "reasoning", 
        "id": "rs_67cb...", 
        "summary": [ 
            { 
                "type": "summary_text", 
                "text": "Exploring 'File' menu option." 
            } 
        ] 
    }, 
    { 
        "type": "computer_call", 
        "id": "cu_67cb...", 
        "call_id": "call_nEJ...", 
        "action": { 
            "type": "click", 
            "button": "left", 
            "x": 135, 
            "y": 193 
        }, 
        "pending_safety_checks": [ 
            { 
                "id": "cu_sc_67cb...", 
                "code": "malicious_instructions", 
                "message": "We've detected instructions that may cause your application to perform malicious or unauthorized actions. Please acknowledge this warning if you'd like to proceed." 
            } 
        ], 
        "status": "completed" 
    } 
]

Необходимо пройти проверку безопасности, как acknowledged_safety_checks в следующем запросе, чтобы продолжить.

"input":[ 
        { 
            "type": "computer_call_output", 
            "call_id": "<call_id>", 
            "acknowledged_safety_checks": [ 
                { 
                    "id": "<safety_check_id>", 
                    "code": "malicious_instructions", 
                    "message": "We've detected instructions that may cause your application to perform malicious or unauthorized actions. Please acknowledge this warning if you'd like to proceed." 
                } 
            ], 
            "output": { 
                "type": "computer_screenshot", 
                "image_url": "<image_url>" 
            } 
        } 
    ]

Обработка проверки безопасности

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

malicious_instructions и irrelevant_domain: конечные пользователи должны просматривать действия модели и проверять, что модель ведет себя должным образом.

sensitive_domain: убедитесь, что конечный пользователь активно отслеживает действия модели на этих сайтах. Точная реализация этого "режима наблюдения" может, в зависимости от приложения, быть различной, но потенциальный пример может, например, заключаться в сборе данных о впечатлениях пользователей на сайте, чтобы убедиться, что имеется активное взаимодействие пользователей с приложением.

Устранение неполадок

Проблема Причина Резолюция
В ответе нет computer_call. Агент не настроен с помощью средства использования компьютера, развертывание не является моделью использования компьютера или запрос не требует взаимодействия с пользовательским интерфейсом. Убедитесь, что агент имеет computer_use_preview инструмент, развертывание выполняется по модели computer-use-preview, и запрос требует действия пользовательского интерфейса (ввод, щелчок или снимок экрана).
Пример кода не работает из-за отсутствия вспомогательных файлов или скриншотов. Вспомогательные утилиты и образцы изображений, которые не являются частью этого репозитория документации. Запустите поддерживаемые примеры пакета SDK в разделе "Запуск поддерживаемых примеров пакета SDK" или скопируйте вспомогательный файл и образы из репозитория SDK в проект.
Цикл останавливается в пределе итерации. Задача нуждается в дополнительных итерациях, или приложение не выполняет действия, запрашиваемые моделью. Увеличьте ограничение итерации и убедитесь, что код выполняет запрошенное действие и отправляет новый снимок экрана после каждой очереди.
Вы получаете pending_safety_checks. Служба обнаружила потенциальный риск безопасности (например, инжекция запросов или конфиденциальный домен). Приостанавливайте автоматизацию, требуется, чтобы конечный пользователь проверял запрос и продолжал только после отправки acknowledged_safety_checks следующего computer_call_output.
Модель повторяет "снимок экрана", но без какого-либо прогресса. Снимок экрана не обновляется, имеет низкое качество или не отображает нужное состояние интерфейса. При необходимости отправьте свежий снимок экрана после каждого действия и используйте более подробное изображение. Убедитесь, что снимок экрана содержит соответствующий пользовательский интерфейс.
Доступ запрещен при запросе модели computer-use-preview. Вы не зарегистрированы для доступа или доступ не был предоставлен. Отправьте форму приложения и дождитесь утверждения. Проверьте сообщение электронной почты для подтверждения.
Ошибки кодирования снимок экрана. Не поддерживается формат изображения или проблема с кодировкой Base64. Используйте формат PNG или JPEG. Убедитесь, что кодировка base64 выполняется правильно и без ошибок. Проверьте, соответствуют ли размеры изображения display_width и display_height.
Действия выполняются по неправильным координатам. Несоответствие разрешения экрана между снимка экрана и фактическим отображением. Убедитесь, что display_width и display_height в ComputerUsePreviewTool соответствуют фактическому разрешению экрана.
Модель галлюцинирует элементы пользовательского интерфейса. Снимок экрана слишком низкого качества, или пользовательский интерфейс изменился между сеансами. Используйте снимки экрана с более высоким разрешением. Отправлять свежие снимки экрана сразу после каждого действия. Уменьшите задержку между действием и скриншотом.

Связанный контент

  • Last updated on