v1

latestOpenAPI 3.1.02026-07-2686787.0 KB

Execute an AI agent

Runs an autonomous AI agent that can perform complex multi-step browser tasks.

post/v1/sessions/{id}/agentExecute

Path parameters

idstring required

Unique session identifier

Example:c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123

Unique session identifier

Headers

x-stream-response'true' | 'false'

Whether to stream the response via SSE

Example:true

Whether to stream the response via SSE

Request body

frameIdstring nullable

Target frame ID for the agent

streamResponseboolean

Whether to stream the response via SSE

shouldCacheboolean

If true, the server captures a cache entry and returns it to the client

Example request

{
  "agentConfig": {
    "provider": "openai",
    "model": {
      "modelName": "openai/gpt-5.4-mini",
      "apiKey": "sk-some-openai-api-key",
      "baseURL": "https://api.openai.com/v1",
      "providerOptions": {
        "vertex": {
          "project": "my-gcp-project",
          "location": "us-central1"
        }
      }
    },
    "cua": true,
    "mode": "cua",
    "executionModel": {
      "modelName": "openai/gpt-5.4-mini",
      "apiKey": "sk-some-openai-api-key",
      "baseURL": "https://api.openai.com/v1",
      "providerOptions": {
        "vertex": {
          "project": "my-gcp-project",
          "location": "us-central1"
        }
      }
    }
  },
  "executeOptions": {
    "instruction": "Log in with username 'demo' and password 'test123', then navigate to settings",
    "maxSteps": 20,
    "highlightCursor": true,
    "useSearch": true,
    "toolTimeout": 30000
  },
  "streamResponse": true
}

Response

Default Response

successboolean required

Indicates whether the request was successful

Example response

{
  "data": {
    "result": {
      "success": true,
      "message": "Successfully logged in and navigated to dashboard",
      "actions": [
        {
          "type": "click"
        }
      ],
      "completed": true,
      "usage": {
        "input_tokens": 1500,
        "output_tokens": 250,
        "inference_time_ms": 2500
      }
    }
  }
}