Použijte nástroj pro práci s počítačem pro agenty (Preview)

Důležité

Položky označené (Preview) v tomto článku jsou aktuálně ve verzi Public Preview. Tato verze Preview je poskytována bez smlouvy o úrovni služeb a nedoporučujeme ji pro produkční úlohy. Některé funkce nemusí být podporované nebo můžou mít omezené možnosti. Další informace najdete v tématu Supplementální podmínky použití pro Microsoft Azure Verze Preview.

Upozornění

Nástroj pro práci s počítačem přináší významná rizika zabezpečení a ochrany osobních údajů, včetně útoků pomocí injektování dotazů. Další informace o zamýšlených použitích, možnostech, omezeních, rizicích a důležitých aspektech při volbě případu použití najdete v Azure poznámce k transparentnosti OpenAI.

Vytvořte agenty, kteří interpretují snímky obrazovky a automatizují interakce uživatelského rozhraní, jako je kliknutí, psaní a posouvání. Nástroj pro použití počítače pomocí computer-use-preview modelu Foundry navrhuje akce založené na vizuálním obsahu a umožňuje agentům pracovat s desktopovými a prohlížečovými aplikacemi prostřednictvím jejich uživatelských rozhraní.

Tento průvodce ukazuje, jak integrovat nástroj pro práci s počítačem do smyčky aplikace (snímek obrazovky → akce → snímek obrazovky) pomocí nejnovějších SDK.

Podpora využití

Následující tabulka ukazuje podporu sady SDK a nastavení.

podpora Microsoft Foundry Python SDK C# SDK JavaScript SDK Java SDK REST API Základní nastavení agenta Nastavení standardního agenta
✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️

Požadavky

  • Předplatné Azure. Vytvořte si ho zdarma.
  • Základní nebo standardní prostředí agenta.
  • Nejnovější balíček sady SDK:
    • Python:azure-ai-projects
    • C#/.NET:Azure.AI.Extensions.OpenAI
    • TypeScript: @azure/ai-projects
    • Java:azure-ai-agents
  • Přístup k computer-use-preview modelu. Viz žádost o přístup níže.
  • Virtuální počítač nebo prostředí v izolovaném prostoru (sandbox) pro bezpečné testování Nespouští se na počítačích s přístupem k citlivým datům.

Fragmenty kódu v tomto článku se zaměřují na integraci rozhraní API pro agenty a odpovědi. Pro kompletní spustitelnou ukázku, která obsahuje pomocný kód a ukázkové snímky obrazovky, použijte ukázky sady SDK na GitHub.

Tip

Ukázky sady SDK zahrnují pomocné nástroje pro zachytávání snímků obrazovky, provádění akcí a kódování obrázků. Před spuštěním ukázek naklonujte úložiště nebo zkopírujte tyto soubory do projektu.

Žádost o přístup

Pokud chcete získat přístup k computer-use-preview modelu, musíte se zaregistrovat. Microsoft uděluje přístup na základě kritérií způsobilosti. Pokud máte přístup k jiným modelům s omezeným přístupem, musíte pro tento model požádat o přístup.

Pokud chcete požádat o přístup, podívejte se na formulář aplikace.

Jakmile vám Microsoft poskytne přístup, musíte vytvořit nasazení pro model.

Ukázky kódu

Upozornění

Použijte nástroj pro použití počítače na virtuálních počítačích bez přístupu k citlivým datům nebo kritickým prostředkům. Další informace o zamýšlených použitích, možnostech, omezeních, rizicích a důležitých aspektech při výběru případu použití najdete v Azure poznámce k transparentnosti OpenAI.

Potřebujete nejnovější balíček sady SDK. Sada .NET SDK je aktuálně ve verzi Preview.

Inicializace snímku obrazovky pro spuštění nástroje pro použití počítače

Následující ukázka kódu ukazuje, jak vytvořit verzi agenta pomocí nástroje pro použití počítače, odeslat počáteční požadavek se snímkem obrazovky a provést několik iterací pro dokončení úlohy. Vyberte Prompt Agents, chcete-li použít SDK Azure AI Projects k vytvoření serverového agenta promptů, nebo Hosted Agents, chcete-li použít Agent Framework FoundryChatClient k vytvoření dočasného agenta v rámci procesu.

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)

Vytvoření verze agenta pomocí nástroje

# 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})")

Jedna iterace pro nástroj pro zpracování snímku obrazovky a provedení dalšího kroku

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})")

Provádění několika iterací

Nezapomeňte zkontrolovat každou iteraci a akci. Následující ukázka kódu ukazuje základní požadavek rozhraní API. Po odeslání počátečního požadavku rozhraní API proveďte smyčku, ve které kód aplikace provede zadanou akci. Posílejte snímek obrazovky s jednotlivými turny, aby model mohl vyhodnotit aktualizovaný stav prostředí. Ukázka obsahuje maximální počet iterací, aby se zabránilo nekonečné smyčce, ale podle potřeby to můžete upravit.


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})")

Vyčištění

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

Očekávaný výstup

Následující příklad ukazuje očekávaný výstup při spuštění předchozí ukázky kódu:

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

Ukázka použití agenta s nástrojem pro používání počítače

Následující ukázka kódu jazyka C# ukazuje, jak vytvořit agenta pomocí nástroje pro použití počítače, odeslat počáteční požadavek se snímkem obrazovky a provést několik iterací pro dokončení úlohy. Vyberte Prompt Agents, chcete-li pomocí sady Azure AI Projects SDK vytvořit serverového agenta pro prompty, nebo Hosted Agents, chcete-li pomocí Microsoft Agent Framework vytvořit dočasného agenta v procesu.

Pokud chcete agentovi povolit používání nástroje pro použití počítače, použijte ResponseTool.CreateComputerTool() při konfiguraci nástrojů agenta. Tento příklad používá synchronní kód. K asynchronnímu použití viz příklad ukázkového kódu v úložišti Azure SDK pro .NET na GitHubu.

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);
    }
}

Očekávaný výstup

Následující příklad ukazuje očekávaný výstup při spuštění předchozí ukázky kódu:

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

Ukázka použití agenta s nástrojem pro používání počítače

Následující ukázka kódu TypeScriptu ukazuje, jak vytvořit verzi agenta pomocí nástroje pro použití počítače, odeslat počáteční požadavek se snímkem obrazovky a provést několik iterací k dokončení úlohy. Příklad JavaScriptu najdete v kódu sample v Azure SDK pro javascriptové úložiště na 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);
});

Očekávaný výstup

Následující příklad ukazuje očekávaný výstup při spuštění předchozí ukázky kódu:

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!

Využití počítačových prostředků v Java agentovi

Přidejte závislost do svého pom.xml:

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

Vytvoření agenta použití počítače

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());
    }
}

Úplnou smyčku použití počítače se zpracováním snímků obrazovky najdete v ukázce ComputerUseSync.java.

Používání počítače pomocí rozhraní REST API

Získání přístupového tokenu:

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

Vytvoření agenta s použitím počítače

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
        }
      ]
    }
  }'

Vygenerování odpovědi

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"
  }'

Odpověď obsahuje computer_call výstupní položky s akcemi, které se mají provést. Zpracovat každou akci, zachytit snímky obrazovky a odeslat výsledky zpět pomocí koncového bodu odpovědí s previous_response_id.

Odeslání výsledků akce se snímkem obrazovky

Po spuštění akce počítače (například kliknutí nebo typ) zachyťte snímek obrazovky a odešlete ho zpět:

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>"
        }
      }
    ]
  }'

Nahraďte <RESPONSE_ID>, <CALL_ID> a <BASE64_SCREENSHOT> hodnotami z předchozí odpovědi. Tento cyklus opakujte, dokud model nevrátí textovou odpověď místo computer_call.

Vyčištění

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

Co můžete dělat s nástrojem pro použití počítače

Po integraci smyčky požadavku a odpovědi (snímek obrazovky –> akce –> snímek obrazovky) může nástroj pro použití počítače pomoct agentu:

  • Navrhněte akce uživatelského rozhraní, jako je kliknutí, psaní, posouvání a vyžádání nového snímku obrazovky.
  • Přizpůsobte se změnám uživatelského rozhraní opětovným vyhodnocením nejnovějšího snímku obrazovky po každé akci.
  • V závislosti na tom, jak hostujete prostředí v izolovaném prostoru (sandbox), můžete pracovat v prohlížeči a v desktopovém uživatelském rozhraní.

Nástroj neřídí přímo zařízení. Vaše aplikace spustí každou požadovanou akci a vrátí aktualizovaný snímek obrazovky.

Rozdíly mezi automatizací prohlížeče a používáním počítače

Následující tabulka uvádí některé rozdíly mezi nástrojem pro použití počítače a nástrojem pro automatizaci prohlížeče .

Funkce Automatizace prohlížeče Nástroj použití počítače
Podpora modelů Všechny modely GPT Computer-use-preview pouze model
Můžu vizualizovat, co se děje? Ne Ano
Jak rozumí obrazovce Parsuje stránky HTML nebo XML do dokumentů DOM. Surová data pixelů ze snímků obrazovky
Jak funguje Seznam akcí poskytovaných modelem Virtuální klávesnice a myš
Je to vícekrokový? Ano Ano
Rozhraní Prohlížeče Počítač a prohlížeč
Musím si přinést vlastní prostředek? Váš vlastní prostředek Playwright s klíči uloženými jako připojení. Nevyžaduje se žádný další prostředek, ale důrazně doporučujeme tento nástroj spustit v prostředí s izolovaným prostorem (sandbox).

Kdy použít jednotlivé nástroje

Vyberte počítač, který chcete použít, když potřebujete:

  • Interakce s desktopovými aplikacemi mimo prohlížeč
  • Vizualizace toho, co agent vidí prostřednictvím snímků obrazovky
  • Práce v prostředích, kde není analýza DOM dostupná

Pokud potřebujete, zvolte automatizaci prohlížeče:

  • Provádění interakcí jenom s webem bez omezených požadavků na přístup
  • Použití libovolného modelu GPT (bez omezení computer-use-preview)
  • Vyhněte se správě zachytávání snímků obrazovky a smyček provádění akcí

Regionální podpora

Pokud chcete použít nástroj pro využití počítače, potřebujete nasazení modelu pro použití počítače. Model použití počítače je k dispozici v následujících oblastech:

Oblasti Stav
eastus2 K dispozici
swedencentral K dispozici
southindia K dispozici

Principy integrace použití počítače

Při práci s nástrojem pro použití počítače ho integrujte do aplikace provedením následujících kroků:

  1. Odešlete do modelu požadavek, který zahrnuje volání nástroje pro použití počítače, velikost zobrazení a prostředí. Do prvního požadavku rozhraní API můžete zahrnout také snímek obrazovky s počátečním stavem prostředí.

  2. Obdrží odpověď z modelu. Pokud odpověď obsahuje položky akcí, obsahují tyto položky navrhované akce, které budou pokračovat směrem k zadanému cíli. Akce může být screenshot například proto, aby model mohl vyhodnotit aktuální stav pomocí aktualizovaného snímku obrazovky nebo click pomocí souřadnic X/Y označujících, kam se má myš přesunout.

  3. Akci spusťte pomocí kódu aplikace v počítači nebo v prostředí prohlížeče.

  4. Po provedení akce zachyťte aktualizovaný stav prostředí jako snímek obrazovky.

  5. Odešlete nový požadavek s aktualizovaným stavem jako tool_call_output, a opakujte tuto smyčku, dokud model neukončí žádosti o akce nebo se rozhodnete přestat.

    Poznámka

    Před použitím nástroje nastavte prostředí, které může zachytit snímky obrazovky a spouštět doporučené akce agentem. Z bezpečnostních důvodů použijte prostředí v izolovaném prostoru (sandbox), například Playwright.

Správa historie konverzací

Pomocí parametru previous_response_id propojte aktuální požadavek s předchozí odpovědí. Tento parametr použijte, pokud nechcete posílat celou historii konverzací s každým voláním.

Pokud tento parametr nepoužíváte, nezapomeňte do pole vstupů zahrnout všechny položky vrácené ve výstupu odpovědi předchozího požadavku. Tento požadavek zahrnuje odůvodnění položek, pokud jsou k dispozici.

Bezpečnostní kontroly a aspekty zabezpečení

Upozornění

Používání počítače nese značné riziko zabezpečení a ochranu osobních údajů a odpovědnost uživatelů. Obě chyby v rozsudku umělé inteligence a přítomnost škodlivých nebo matoucích pokynů na webových stránkách, desktopech nebo jiných operačních prostředích, na kterých se AI setká, můžou způsobit, že spustí příkazy, které vy nebo jiní uživatelé nemají v úmyslu. Tato rizika můžou ohrozit zabezpečení prohlížečů, počítačů a účtů, ke kterým má umělá inteligence přístup, včetně osobních, finančních nebo podnikových systémů.

Použijte nástroj pro použití počítače na virtuálních počítačích bez přístupu k citlivým datům nebo kritickým prostředkům. Další informace o zamýšlených použitích, možnostech, omezeních, rizicích a důležitých aspektech při výběru případu použití najdete v Azure poznámce k transparentnosti OpenAI.

Rozhraní API má bezpečnostní kontroly, které pomáhají chránit před injekcí výzev a chybami modelu. Mezi tyto kontroly patří:

Detekce škodlivých instrukcí: Systém vyhodnotí obrázek snímku obrazovky a zkontroluje, jestli obsahuje nežádoucí obsah, který by mohl změnit chování modelu.

Irelevantní detekce domény: Systém vyhodnotí current_url parametr (pokud je zadaný) a zkontroluje, jestli je aktuální doména relevantní vzhledem k historii konverzací.

Detekce citlivých domén: Systém zkontroluje current_url parametr (pokud je k dispozici) a při zjištění uživatele v citlivé doméně vyvolá upozornění.

Pokud se aktivuje jedna nebo více předchozích kontrol, model vyvolá bezpečnostní kontrolu při vrácení dalšího computer_call pomocí parametru 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" 
    } 
]

Abyste mohli pokračovat, musíte bezpečnostní kontroly odeslat zpět jako acknowledged_safety_checks v dalším požadavku.

"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>" 
            } 
        } 
    ]

Zpracování bezpečnostní kontroly

Ve všech případech, kdy pending_safety_checks se vrátí, předáte koncovému uživateli akce, abyste potvrdili správné chování a přesnost modelu.

malicious_instructions a irrelevant_domain: Koncoví uživatelé by měli zkontrolovat akce modelu a ověřit, že se model chová podle očekávání.

sensitive_domain: Zajistěte, aby koncový uživatel aktivně monitoruje akce modelu na těchto webech. Přesná implementace tohoto "sledovacího režimu" se může lišit podle aplikace, ale potenciálním příkladem může být shromažďování dat o zobrazení uživatelů na webu pro zajištění aktivního zapojení koncových uživatelů do aplikace.

Řešení potíží

Problém Příčina Rozlišení
V odpovědi se nezobrazuje computer_call . Agent není nakonfigurovaný pomocí nástroje pro použití počítače, nasazení není modelem použití počítače nebo výzva nevyžaduje interakci s uživatelským rozhraním. Ověřte, že agent má computer_use_preview nástroj, a že vaše nasazení používá computer-use-preview model, a že vaše výzva vyžaduje akci uživatelského rozhraní (psaní, kliknutí nebo vytvoření snímku obrazovky).
Ukázkový kód selže s chybějícími pomocnými soubory nebo snímky obrazovky. Fragmenty kódu odkazují na pomocné nástroje a ukázkové obrázky, které nejsou součástí tohoto úložiště dokumentace. Spusťte spravované ukázky sady SDK v části Spustit spravované ukázky sady SDK nebo zkopírujte pomocný soubor a ukázkové image z úložiště sady SDK do vašeho projektu.
Smyčka se zastaví na limitu iterací. Úloha potřebuje více otočení nebo aplikace nepoužívá akce, které model požaduje. Zvyšte limit iterace a ověřte, že kód provede požadovanou akci, a po každém turnu odešle nový snímek obrazovky.
Obdržíte pending_safety_checks. Služba zjistila potenciální bezpečnostní riziko (například injekce kódu nebo citlivá doména). Pozastavit automatizaci, vyžadovat, aby koncový uživatel zkontroloval požadavek, a pokračovat až po odeslání acknowledged_safety_checks s dalším computer_call_output.
Model opakovaně říká "pořídit snímek obrazovky" bez posunu kupředu. Snímek obrazovky se neaktualizuje, je nízká kvalita nebo nezobrazuje příslušný stav uživatelského rozhraní. Po každé akci odešlete nový snímek obrazovky a v případě potřeby použijte obrázek s vyšší podrobnostmi. Ujistěte se, že snímek obrazovky obsahuje příslušné uživatelské rozhraní.
Přístup byl odepřen při žádosti o computer-use-preview model. Nemáte zaregistrovaný přístup nebo vám nebyl udělen přístup. Odešlete formulář žádosti a počkejte na schválení. Zkontrolujte si e-mail s potvrzením.
Snímek obrazovky s chybami kódování Problém s nepodporování formátu obrázku nebo kódování base64 Použijte formát PNG nebo JPEG. Zajistěte správné kódování base64 bez poškození. Zkontrolujte, zda rozměry obrázku odpovídají display_width a display_height.
Akce se provádějí na nesprávných souřadnicích. Neshoda rozlišení obrazovky mezi snímkem obrazovky a skutečným zobrazením Ujistěte se, že display_width a display_height v ComputerUsePreviewTool odpovídají skutečnému rozlišení obrazovky.
Model halucinuje prvky uživatelského rozhraní. Kvalita snímku obrazovky je příliš nízká nebo se mezi otočeními změnilo uživatelské rozhraní. Použijte snímky obrazovky s vyšším rozlišením. Okamžitě po každé akci odešlete nové snímky obrazovky. Zmenšete zpoždění mezi akcí a snímkem obrazovky.

Související obsah

  • Last updated on