Skip to content
Tabstack Tabstack Tabstack
Get started
API Reference

Agent

AI Task
client.agent.automate(AgentAutomateParams { task, data, geo_target, 5 more } body, RequestOptionsoptions?): AutomateEvent | Stream<AutomateEvent>
POST/automate
Submit Input Response
client.agent.automateInput(stringrequestID, AgentAutomateInputParams { cancelled, fields } body, RequestOptionsoptions?): AgentAutomateInputResponse { status }
POST/automate/{requestID}/input
Research
client.agent.research(AgentResearchParams { query, fetch_timeout, mode, nocache } body, RequestOptionsoptions?): ResearchEvent | Stream<ResearchEvent>
POST/research
ModelsExpand Collapse
AutomateEvent = V1AutomateEventAgentAction { data, event } | V1AutomateEventAgentExtracted { data, event } | V1AutomateEventAgentProcessing { data, event } | 30 more

A Server-Sent Event from /v1/automate. Typed discriminated union keyed on event.

One of the following:
V1AutomateEventAgentAction { data, event }

Envelope for the “agent:action” event from /v1/automate.

data: Data { action, iterationId, timestamp, 2 more }

Event data for action execution

action: string
iterationId: string
timestamp: number
ref?: string | null
value?: string | null
event: "agent:action"
V1AutomateEventAgentExtracted { data, event }

Envelope for the “agent:extracted” event from /v1/automate.

data: Data { extractedData, iterationId, timestamp }

Event data for extracted data

extractedData: string
iterationId: string
timestamp: number
event: "agent:extracted"
V1AutomateEventAgentProcessing { data, event }

Envelope for the “agent:processing” event from /v1/automate.

data: Data { hasScreenshot, iterationId, operation, timestamp }

Event data for when the agent is waiting for model generation

hasScreenshot: boolean
iterationId: string
operation: string
timestamp: number
event: "agent:processing"
V1AutomateEventAgentReasoned { data, event }

Envelope for the “agent:reasoned” event from /v1/automate.

data: Data { iterationId, reasoning, timestamp }

Event data for agent reasoning

iterationId: string
reasoning: string
timestamp: number
event: "agent:reasoned"
V1AutomateEventAgentStatus { data, event }

Envelope for the “agent:status” event from /v1/automate.

data: Data { iterationId, message, timestamp }

Event data for status messages

iterationId: string
message: string
timestamp: number
event: "agent:status"
V1AutomateEventAgentStep { data, event }

Envelope for the “agent:step” event from /v1/automate.

data: Data { currentIteration, iterationId, timestamp }

Event data for agent step tracking (each loop iteration)

currentIteration: number
iterationId: string
timestamp: number
event: "agent:step"
V1AutomateEventAgentWaiting { data, event }

Envelope for the “agent:waiting” event from /v1/automate.

data: Data { iterationId, seconds, timestamp }

Event data for waiting notifications

iterationId: string
seconds: number
timestamp: number
event: "agent:waiting"
V1AutomateEventAIGeneration { data, event }

Envelope for the “ai:generation” event from /v1/automate.

data: Data { finishReason, iterationId, prompt, 8 more }

Event data when AI generation occurs

finishReason: "stop" | "length" | "content-filter" | 3 more
One of the following:
"stop"
"length"
"content-filter"
"tool-calls"
"error"
"other"
iterationId: string
prompt: string
schema: unknown
timestamp: number
usage: Usage { inputTokens, outputTokens, totalTokens }
inputTokens?: number
outputTokens?: number
totalTokens?: number
messages?: Array<System { content, role, providerOptions } | User { content, role, providerOptions } | Assistant { content, role, providerOptions } | Tool { content, role, providerOptions } >
One of the following:
System { content, role, providerOptions }

A system message. It can contain system information.

Note: using the “system” part of the prompt is strongly preferred to increase the resilience against prompt injection attacks, and because not all providers support several system messages.

content: string
role: "system"
providerOptions?: Record<string, Record<string, string | number | boolean | 2 more>>

Additional provider-specific metadata. They are passed through to the provider from the AI SDK and enable provider-specific functionality that can be fully encapsulated in the provider.

One of the following:
string
number
boolean
Record<string, string | number | boolean | 2 more>
string
number
boolean
unknown
Array<unknown>
Array<string | number | boolean | 2 more | null>
string
number
boolean
unknown
Array<unknown>
User { content, role, providerOptions }

A user message. It can contain text or a combination of text and images.

content: string | Array<Text { text, type, providerOptions } | Image { image, type, mediaType, providerOptions } | File { data, mediaType, type, 2 more } >

Content of a user message. It can be a string or an array of text and image parts.

One of the following:
string
Array<Text { text, type, providerOptions } | Image { image, type, mediaType, providerOptions } | File { data, mediaType, type, 2 more } >
Text { text, type, providerOptions }

Text content part of a prompt. It contains a string of text.

text: string

The text content.

type: "text"
providerOptions?: Record<string, Record<string, string | number | boolean | 2 more>>

Additional provider-specific metadata. They are passed through to the provider from the AI SDK and enable provider-specific functionality that can be fully encapsulated in the provider.

One of the following:
string
number
boolean
Record<string, string | number | boolean | 2 more>
string
number
boolean
unknown
Array<unknown>
Array<string | number | boolean | 2 more | null>
string
number
boolean
unknown
Array<unknown>
Image { image, type, mediaType, providerOptions }

Image content part of a prompt. It contains an image.

image: string | UnionMember1 { buffer, byteLength, byteOffset, 2 more } | ByteLength { byteLength } | V1GlobalBuffer { buffer, byteLength, byteOffset, 2 more }

Image data. Can either be:

  • data: a base64-encoded string, a Uint8Array, an ArrayBuffer, or a Buffer
  • URL: a URL that points to the image
One of the following:
string
UnionMember1 { buffer, byteLength, byteOffset, 2 more }
buffer: Buffer { byteLength }
byteLength: number
byteLength: number
byteOffset: number
BYTES_PER_ELEMENT: number
length: number
ByteLength { byteLength }
byteLength: number
V1GlobalBuffer { buffer, byteLength, byteOffset, 2 more }
buffer: Buffer { byteLength }
byteLength: number
byteLength: number
byteOffset: number
BYTES_PER_ELEMENT: number
length: number
type: "image"
mediaType?: string

Optional IANA media type of the image.

providerOptions?: Record<string, Record<string, string | number | boolean | 2 more>>

Additional provider-specific metadata. They are passed through to the provider from the AI SDK and enable provider-specific functionality that can be fully encapsulated in the provider.

One of the following:
string
number
boolean
Record<string, string | number | boolean | 2 more>
string
number
boolean
unknown
Array<unknown>
Array<string | number | boolean | 2 more | null>
string
number
boolean
unknown
Array<unknown>
File { data, mediaType, type, 2 more }

File content part of a prompt. It contains a file.

data: string | UnionMember1 { buffer, byteLength, byteOffset, 2 more } | ByteLength { byteLength } | V1GlobalBuffer { buffer, byteLength, byteOffset, 2 more }

File data. Can either be:

  • data: a base64-encoded string, a Uint8Array, an ArrayBuffer, or a Buffer
  • URL: a URL that points to the image
One of the following:
string
UnionMember1 { buffer, byteLength, byteOffset, 2 more }
buffer: Buffer { byteLength }
byteLength: number
byteLength: number
byteOffset: number
BYTES_PER_ELEMENT: number
length: number
ByteLength { byteLength }
byteLength: number
V1GlobalBuffer { buffer, byteLength, byteOffset, 2 more }
buffer: Buffer { byteLength }
byteLength: number
byteLength: number
byteOffset: number
BYTES_PER_ELEMENT: number
length: number
mediaType: string

IANA media type of the file.

type: "file"
filename?: string

Optional filename of the file.

providerOptions?: Record<string, Record<string, string | number | boolean | 2 more>>

Additional provider-specific metadata. They are passed through to the provider from the AI SDK and enable provider-specific functionality that can be fully encapsulated in the provider.

One of the following:
string
number
boolean
Record<string, string | number | boolean | 2 more>
string
number
boolean
unknown
Array<unknown>
Array<string | number | boolean | 2 more | null>
string
number
boolean
unknown
Array<unknown>
role: "user"
providerOptions?: Record<string, Record<string, string | number | boolean | 2 more>>

Additional provider-specific metadata. They are passed through to the provider from the AI SDK and enable provider-specific functionality that can be fully encapsulated in the provider.

One of the following:
string
number
boolean
Record<string, string | number | boolean | 2 more>
string
number
boolean
unknown
Array<unknown>
Array<string | number | boolean | 2 more | null>
string
number
boolean
unknown
Array<unknown>
Assistant { content, role, providerOptions }

An assistant message. It can contain text, tool calls, or a combination of text and tool calls.

content: string | Array<Text { text, type, providerOptions } | File { data, mediaType, type, 2 more } | Reasoning { text, type, providerOptions } | 3 more>

Content of an assistant message. It can be a string or an array of text, image, reasoning, redacted reasoning, and tool call parts.

One of the following:
string
Array<Text { text, type, providerOptions } | File { data, mediaType, type, 2 more } | Reasoning { text, type, providerOptions } | 3 more>
Text { text, type, providerOptions }

Text content part of a prompt. It contains a string of text.

text: string

The text content.

type: "text"
providerOptions?: Record<string, Record<string, string | number | boolean | 2 more>>

Additional provider-specific metadata. They are passed through to the provider from the AI SDK and enable provider-specific functionality that can be fully encapsulated in the provider.

One of the following:
string
number
boolean
Record<string, string | number | boolean | 2 more>
string
number
boolean
unknown
Array<unknown>
Array<string | number | boolean | 2 more | null>
string
number
boolean
unknown
Array<unknown>
File { data, mediaType, type, 2 more }

File content part of a prompt. It contains a file.

data: string | UnionMember1 { buffer, byteLength, byteOffset, 2 more } | ByteLength { byteLength } | V1GlobalBuffer { buffer, byteLength, byteOffset, 2 more }

File data. Can either be:

  • data: a base64-encoded string, a Uint8Array, an ArrayBuffer, or a Buffer
  • URL: a URL that points to the image
One of the following:
string
UnionMember1 { buffer, byteLength, byteOffset, 2 more }
buffer: Buffer { byteLength }
byteLength: number
byteLength: number
byteOffset: number
BYTES_PER_ELEMENT: number
length: number
ByteLength { byteLength }
byteLength: number
V1GlobalBuffer { buffer, byteLength, byteOffset, 2 more }
buffer: Buffer { byteLength }
byteLength: number
byteLength: number
byteOffset: number
BYTES_PER_ELEMENT: number
length: number
mediaType: string

IANA media type of the file.

type: "file"
filename?: string

Optional filename of the file.

providerOptions?: Record<string, Record<string, string | number | boolean | 2 more>>

Additional provider-specific metadata. They are passed through to the provider from the AI SDK and enable provider-specific functionality that can be fully encapsulated in the provider.

One of the following:
string
number
boolean
Record<string, string | number | boolean | 2 more>
string
number
boolean
unknown
Array<unknown>
Array<string | number | boolean | 2 more | null>
string
number
boolean
unknown
Array<unknown>
Reasoning { text, type, providerOptions }

Reasoning content part of a prompt. It contains a reasoning.

text: string

The reasoning text.

type: "reasoning"
providerOptions?: Record<string, Record<string, string | number | boolean | 2 more>>

Additional provider-specific metadata. They are passed through to the provider from the AI SDK and enable provider-specific functionality that can be fully encapsulated in the provider.

One of the following:
string
number
boolean
Record<string, string | number | boolean | 2 more>
string
number
boolean
unknown
Array<unknown>
Array<string | number | boolean | 2 more | null>
string
number
boolean
unknown
Array<unknown>
ToolCall { input, toolCallId, toolName, 3 more }

Tool call content part of a prompt. It contains a tool call (usually generated by the AI model).

input: unknown

Arguments of the tool call. This is a JSON-serializable object that matches the tool’s input schema.

toolCallId: string

ID of the tool call. This ID is used to match the tool call with the tool result.

toolName: string

Name of the tool that is being called.

type: "tool-call"
providerExecuted?: boolean

Whether the tool call was executed by the provider.

providerOptions?: Record<string, Record<string, string | number | boolean | 2 more>>

Additional provider-specific metadata. They are passed through to the provider from the AI SDK and enable provider-specific functionality that can be fully encapsulated in the provider.

One of the following:
string
number
boolean
Record<string, string | number | boolean | 2 more>
string
number
boolean
unknown
Array<unknown>
Array<string | number | boolean | 2 more | null>
string
number
boolean
unknown
Array<unknown>
ToolResult { output, toolCallId, toolName, 2 more }

Tool result content part of a prompt. It contains the result of the tool call with the matching ID.

output: Text { type, value, providerOptions } | Json { type, value, providerOptions } | ExecutionDenied { type, providerOptions, reason } | 3 more

Result of the tool call. This is a JSON-serializable object.

One of the following:
Text { type, value, providerOptions }
type: "text"

Text tool output that should be directly sent to the API.

value: string
providerOptions?: Record<string, Record<string, string | number | boolean | 2 more>>

Provider-specific options.

One of the following:
string
number
boolean
Record<string, string | number | boolean | 2 more>
string
number
boolean
unknown
Array<unknown>
Array<string | number | boolean | 2 more | null>
string
number
boolean
unknown
Array<unknown>
Json { type, value, providerOptions }
type: "json"
value: string | number | boolean | 2 more | null

A JSON value can be a string, number, boolean, object, array, or null. JSON values can be serialized and deserialized by the JSON.stringify and JSON.parse methods.

One of the following:
string
number
boolean
Record<string, string | number | boolean | 2 more>
string
number
boolean
Record<string, string | number | boolean | 2 more>
string
number
boolean
unknown
Array<unknown>
Array<string | number | boolean | 2 more | null>
string
number
boolean
unknown
Array<unknown>
Array<string | number | boolean | 2 more | null>
string
number
boolean
unknown
Array<unknown>
providerOptions?: Record<string, Record<string, string | number | boolean | 2 more>>

Provider-specific options.

One of the following:
string
number
boolean
Record<string, string | number | boolean | 2 more>
string
number
boolean
unknown
Array<unknown>
Array<string | number | boolean | 2 more | null>
string
number
boolean
unknown
Array<unknown>
ExecutionDenied { type, providerOptions, reason }
type: "execution-denied"

Type when the user has denied the execution of the tool call.

providerOptions?: Record<string, Record<string, string | number | boolean | 2 more>>

Provider-specific options.

One of the following:
string
number
boolean
Record<string, string | number | boolean | 2 more>
string
number
boolean
unknown
Array<unknown>
Array<string | number | boolean | 2 more | null>
string
number
boolean
unknown
Array<unknown>
reason?: string

Optional reason for the execution denial.

ErrorText { type, value, providerOptions }
type: "error-text"
value: string
providerOptions?: Record<string, Record<string, string | number | boolean | 2 more>>

Provider-specific options.

One of the following:
string
number
boolean
Record<string, string | number | boolean | 2 more>
string
number
boolean
unknown
Array<unknown>
Array<string | number | boolean | 2 more | null>
string
number
boolean
unknown
Array<unknown>
ErrorJson { type, value, providerOptions }
type: "error-json"
value: string | number | boolean | 2 more | null

A JSON value can be a string, number, boolean, object, array, or null. JSON values can be serialized and deserialized by the JSON.stringify and JSON.parse methods.

One of the following:
string
number
boolean
Record<string, string | number | boolean | 2 more>
string
number
boolean
Record<string, string | number | boolean | 2 more>
string
number
boolean
unknown
Array<unknown>
Array<string | number | boolean | 2 more | null>
string
number
boolean
unknown
Array<unknown>
Array<string | number | boolean | 2 more | null>
string
number
boolean
unknown
Array<unknown>
providerOptions?: Record<string, Record<string, string | number | boolean | 2 more>>

Provider-specific options.

One of the following:
string
number
boolean
Record<string, string | number | boolean | 2 more>
string
number
boolean
unknown
Array<unknown>
Array<string | number | boolean | 2 more | null>
string
number
boolean
unknown
Array<unknown>
Content { type, value }
type: "content"
value: Array<Text { text, type, providerOptions } | Media { data, mediaType, type } | FileData { data, mediaType, type, 2 more } | 6 more>
One of the following:
Text { text, type, providerOptions }
text: string

Text content.

type: "text"
providerOptions?: Record<string, Record<string, string | number | boolean | 2 more>>

Provider-specific options.

One of the following:
string
number
boolean
Record<string, string | number | boolean | 2 more>
string
number
boolean
unknown
Array<unknown>
Array<string | number | boolean | 2 more | null>
string
number
boolean
unknown
Array<unknown>
Media { data, mediaType, type }
data: string
mediaType: string
Deprecatedtype: "media"
Deprecated by the upstream schema.

Deprecated. Use image-data or file-data instead.

FileData { data, mediaType, type, 2 more }
data: string

Base-64 encoded media data.

mediaType: string

IANA media type.

type: "file-data"
filename?: string

Optional filename of the file.

providerOptions?: Record<string, Record<string, string | number | boolean | 2 more>>

Provider-specific options.

One of the following:
string
number
boolean
Record<string, string | number | boolean | 2 more>
string
number
boolean
unknown
Array<unknown>
Array<string | number | boolean | 2 more | null>
string
number
boolean
unknown
Array<unknown>
FileURL { type, url, providerOptions }
type: "file-url"
url: string

URL of the file.

providerOptions?: Record<string, Record<string, string | number | boolean | 2 more>>

Provider-specific options.

One of the following:
string
number
boolean
Record<string, string | number | boolean | 2 more>
string
number
boolean
unknown
Array<unknown>
Array<string | number | boolean | 2 more | null>
string
number
boolean
unknown
Array<unknown>
FileID { fileId, type, providerOptions }
fileId: string | Record<string, string>

ID of the file.

If you use multiple providers, you need to specify the provider specific ids using the Record option. The key is the provider name, e.g. ‘openai’ or ‘anthropic’.

One of the following:
string
Record<string, string>
type: "file-id"
providerOptions?: Record<string, Record<string, string | number | boolean | 2 more>>

Provider-specific options.

One of the following:
string
number
boolean
Record<string, string | number | boolean | 2 more>
string
number
boolean
unknown
Array<unknown>
Array<string | number | boolean | 2 more | null>
string
number
boolean
unknown
Array<unknown>
ImageData { data, mediaType, type, providerOptions }
data: string

Base-64 encoded image data.

mediaType: string

IANA media type.

type: "image-data"

Images that are referenced using base64 encoded data.

providerOptions?: Record<string, Record<string, string | number | boolean | 2 more>>

Provider-specific options.

One of the following:
string
number
boolean
Record<string, string | number | boolean | 2 more>
string
number
boolean
unknown
Array<unknown>
Array<string | number | boolean | 2 more | null>
string
number
boolean
unknown
Array<unknown>
ImageURL { type, url, providerOptions }
type: "image-url"

Images that are referenced using a URL.

url: string

URL of the image.

providerOptions?: Record<string, Record<string, string | number | boolean | 2 more>>

Provider-specific options.

One of the following:
string
number
boolean
Record<string, string | number | boolean | 2 more>
string
number
boolean
unknown
Array<unknown>
Array<string | number | boolean | 2 more | null>
string
number
boolean
unknown
Array<unknown>
ImageFileID { fileId, type, providerOptions }
fileId: string | Record<string, string>

Image that is referenced using a provider file id.

If you use multiple providers, you need to specify the provider specific ids using the Record option. The key is the provider name, e.g. ‘openai’ or ‘anthropic’.

One of the following:
string
Record<string, string>
type: "image-file-id"

Images that are referenced using a provider file id.

providerOptions?: Record<string, Record<string, string | number | boolean | 2 more>>

Provider-specific options.

One of the following:
string
number
boolean
Record<string, string | number | boolean | 2 more>
string
number
boolean
unknown
Array<unknown>
Array<string | number | boolean | 2 more | null>
string
number
boolean
unknown
Array<unknown>
Custom { type, providerOptions }
type: "custom"

Custom content part. This can be used to implement provider-specific content parts.

providerOptions?: Record<string, Record<string, string | number | boolean | 2 more>>

Provider-specific options.

One of the following:
string
number
boolean
Record<string, string | number | boolean | 2 more>
string
number
boolean
unknown
Array<unknown>
Array<string | number | boolean | 2 more | null>
string
number
boolean
unknown
Array<unknown>
toolCallId: string

ID of the tool call that this result is associated with.

toolName: string

Name of the tool that generated this result.

type: "tool-result"
providerOptions?: Record<string, Record<string, string | number | boolean | 2 more>>

Additional provider-specific metadata. They are passed through to the provider from the AI SDK and enable provider-specific functionality that can be fully encapsulated in the provider.

One of the following:
string
number
boolean
Record<string, string | number | boolean | 2 more>
string
number
boolean
unknown
Array<unknown>
Array<string | number | boolean | 2 more | null>
string
number
boolean
unknown
Array<unknown>
ToolApprovalRequest { approvalId, toolCallId, type }

Tool approval request prompt part.

approvalId: string

ID of the tool approval.

toolCallId: string

ID of the tool call that the approval request is for.

type: "tool-approval-request"
role: "assistant"
providerOptions?: Record<string, Record<string, string | number | boolean | 2 more>>

Additional provider-specific metadata. They are passed through to the provider from the AI SDK and enable provider-specific functionality that can be fully encapsulated in the provider.

One of the following:
string
number
boolean
Record<string, string | number | boolean | 2 more>
string
number
boolean
unknown
Array<unknown>
Array<string | number | boolean | 2 more | null>
string
number
boolean
unknown
Array<unknown>
Tool { content, role, providerOptions }

A tool message. It contains the result of one or more tool calls.

content: Array<ToolResult { output, toolCallId, toolName, 2 more } | ToolApprovalResponse { approvalId, approved, type, 2 more } >

Content of a tool message. It is an array of tool result parts.

One of the following:
ToolResult { output, toolCallId, toolName, 2 more }

Tool result content part of a prompt. It contains the result of the tool call with the matching ID.

output: Text { type, value, providerOptions } | Json { type, value, providerOptions } | ExecutionDenied { type, providerOptions, reason } | 3 more

Result of the tool call. This is a JSON-serializable object.

One of the following:
Text { type, value, providerOptions }
type: "text"

Text tool output that should be directly sent to the API.

value: string
providerOptions?: Record<string, Record<string, string | number | boolean | 2 more>>

Provider-specific options.

One of the following:
string
number
boolean
Record<string, string | number | boolean | 2 more>
string
number
boolean
unknown
Array<unknown>
Array<string | number | boolean | 2 more | null>
string
number
boolean
unknown
Array<unknown>
Json { type, value, providerOptions }
type: "json"
value: string | number | boolean | 2 more | null

A JSON value can be a string, number, boolean, object, array, or null. JSON values can be serialized and deserialized by the JSON.stringify and JSON.parse methods.

One of the following:
string
number
boolean
Record<string, string | number | boolean | 2 more>
string
number
boolean
Record<string, string | number | boolean | 2 more>
string
number
boolean
unknown
Array<unknown>
Array<string | number | boolean | 2 more | null>
string
number
boolean
unknown
Array<unknown>
Array<string | number | boolean | 2 more | null>
string
number
boolean
unknown
Array<unknown>
providerOptions?: Record<string, Record<string, string | number | boolean | 2 more>>

Provider-specific options.

One of the following:
string
number
boolean
Record<string, string | number | boolean | 2 more>
string
number
boolean
unknown
Array<unknown>
Array<string | number | boolean | 2 more | null>
string
number
boolean
unknown
Array<unknown>
ExecutionDenied { type, providerOptions, reason }
type: "execution-denied"

Type when the user has denied the execution of the tool call.

providerOptions?: Record<string, Record<string, string | number | boolean | 2 more>>

Provider-specific options.

One of the following:
string
number
boolean
Record<string, string | number | boolean | 2 more>
string
number
boolean
unknown
Array<unknown>
Array<string | number | boolean | 2 more | null>
string
number
boolean
unknown
Array<unknown>
reason?: string

Optional reason for the execution denial.

ErrorText { type, value, providerOptions }
type: "error-text"
value: string
providerOptions?: Record<string, Record<string, string | number | boolean | 2 more>>

Provider-specific options.

One of the following:
string
number
boolean
Record<string, string | number | boolean | 2 more>
string
number
boolean
unknown
Array<unknown>
Array<string | number | boolean | 2 more | null>
string
number
boolean
unknown
Array<unknown>
ErrorJson { type, value, providerOptions }
type: "error-json"
value: string | number | boolean | 2 more | null

A JSON value can be a string, number, boolean, object, array, or null. JSON values can be serialized and deserialized by the JSON.stringify and JSON.parse methods.

One of the following:
string
number
boolean
Record<string, string | number | boolean | 2 more>
string
number
boolean
Record<string, string | number | boolean | 2 more>
string
number
boolean
unknown
Array<unknown>
Array<string | number | boolean | 2 more | null>
string
number
boolean
unknown
Array<unknown>
Array<string | number | boolean | 2 more | null>
string
number
boolean
unknown
Array<unknown>
providerOptions?: Record<string, Record<string, string | number | boolean | 2 more>>

Provider-specific options.

One of the following:
string
number
boolean
Record<string, string | number | boolean | 2 more>
string
number
boolean
unknown
Array<unknown>
Array<string | number | boolean | 2 more | null>
string
number
boolean
unknown
Array<unknown>
Content { type, value }
type: "content"
value: Array<Text { text, type, providerOptions } | Media { data, mediaType, type } | FileData { data, mediaType, type, 2 more } | 6 more>
One of the following:
Text { text, type, providerOptions }
text: string

Text content.

type: "text"
providerOptions?: Record<string, Record<string, string | number | boolean | 2 more>>

Provider-specific options.

One of the following:
string
number
boolean
Record<string, string | number | boolean | 2 more>
string
number
boolean
unknown
Array<unknown>
Array<string | number | boolean | 2 more | null>
string
number
boolean
unknown
Array<unknown>
Media { data, mediaType, type }
data: string
mediaType: string
Deprecatedtype: "media"
Deprecated by the upstream schema.

Deprecated. Use image-data or file-data instead.

FileData { data, mediaType, type, 2 more }
data: string

Base-64 encoded media data.

mediaType: string

IANA media type.

type: "file-data"
filename?: string

Optional filename of the file.

providerOptions?: Record<string, Record<string, string | number | boolean | 2 more>>

Provider-specific options.

One of the following:
string
number
boolean
Record<string, string | number | boolean | 2 more>
string
number
boolean
unknown
Array<unknown>
Array<string | number | boolean | 2 more | null>
string
number
boolean
unknown
Array<unknown>
FileURL { type, url, providerOptions }
type: "file-url"
url: string

URL of the file.

providerOptions?: Record<string, Record<string, string | number | boolean | 2 more>>

Provider-specific options.

One of the following:
string
number
boolean
Record<string, string | number | boolean | 2 more>
string
number
boolean
unknown
Array<unknown>
Array<string | number | boolean | 2 more | null>
string
number
boolean
unknown
Array<unknown>
FileID { fileId, type, providerOptions }
fileId: string | Record<string, string>

ID of the file.

If you use multiple providers, you need to specify the provider specific ids using the Record option. The key is the provider name, e.g. ‘openai’ or ‘anthropic’.

One of the following:
string
Record<string, string>
type: "file-id"
providerOptions?: Record<string, Record<string, string | number | boolean | 2 more>>

Provider-specific options.

One of the following:
string
number
boolean
Record<string, string | number | boolean | 2 more>
string
number
boolean
unknown
Array<unknown>
Array<string | number | boolean | 2 more | null>
string
number
boolean
unknown
Array<unknown>
ImageData { data, mediaType, type, providerOptions }
data: string

Base-64 encoded image data.

mediaType: string

IANA media type.

type: "image-data"

Images that are referenced using base64 encoded data.

providerOptions?: Record<string, Record<string, string | number | boolean | 2 more>>

Provider-specific options.

One of the following:
string
number
boolean
Record<string, string | number | boolean | 2 more>
string
number
boolean
unknown
Array<unknown>
Array<string | number | boolean | 2 more | null>
string
number
boolean
unknown
Array<unknown>
ImageURL { type, url, providerOptions }
type: "image-url"

Images that are referenced using a URL.

url: string

URL of the image.

providerOptions?: Record<string, Record<string, string | number | boolean | 2 more>>

Provider-specific options.

One of the following:
string
number
boolean
Record<string, string | number | boolean | 2 more>
string
number
boolean
unknown
Array<unknown>
Array<string | number | boolean | 2 more | null>
string
number
boolean
unknown
Array<unknown>
ImageFileID { fileId, type, providerOptions }
fileId: string | Record<string, string>

Image that is referenced using a provider file id.

If you use multiple providers, you need to specify the provider specific ids using the Record option. The key is the provider name, e.g. ‘openai’ or ‘anthropic’.

One of the following:
string
Record<string, string>
type: "image-file-id"

Images that are referenced using a provider file id.

providerOptions?: Record<string, Record<string, string | number | boolean | 2 more>>

Provider-specific options.

One of the following:
string
number
boolean
Record<string, string | number | boolean | 2 more>
string
number
boolean
unknown
Array<unknown>
Array<string | number | boolean | 2 more | null>
string
number
boolean
unknown
Array<unknown>
Custom { type, providerOptions }
type: "custom"

Custom content part. This can be used to implement provider-specific content parts.

providerOptions?: Record<string, Record<string, string | number | boolean | 2 more>>

Provider-specific options.

One of the following:
string
number
boolean
Record<string, string | number | boolean | 2 more>
string
number
boolean
unknown
Array<unknown>
Array<string | number | boolean | 2 more | null>
string
number
boolean
unknown
Array<unknown>
toolCallId: string

ID of the tool call that this result is associated with.

toolName: string

Name of the tool that generated this result.

type: "tool-result"
providerOptions?: Record<string, Record<string, string | number | boolean | 2 more>>

Additional provider-specific metadata. They are passed through to the provider from the AI SDK and enable provider-specific functionality that can be fully encapsulated in the provider.

One of the following:
string
number
boolean
Record<string, string | number | boolean | 2 more>
string
number
boolean
unknown
Array<unknown>
Array<string | number | boolean | 2 more | null>
string
number
boolean
unknown
Array<unknown>
ToolApprovalResponse { approvalId, approved, type, 2 more }

Tool approval response prompt part.

approvalId: string

ID of the tool approval.

approved: boolean

Flag indicating whether the approval was granted or denied.

type: "tool-approval-response"
providerExecuted?: boolean

Flag indicating whether the tool call is provider-executed. Only provider-executed tool approval responses should be sent to the model.

reason?: string

Optional reason for the approval or denial.

role: "tool"
providerOptions?: Record<string, Record<string, string | number | boolean | 2 more>>

Additional provider-specific metadata. They are passed through to the provider from the AI SDK and enable provider-specific functionality that can be fully encapsulated in the provider.

One of the following:
string
number
boolean
Record<string, string | number | boolean | 2 more>
string
number
boolean
unknown
Array<unknown>
Array<string | number | boolean | 2 more | null>
string
number
boolean
unknown
Array<unknown>
object?: unknown
providerMetadata?: Record<string, unknown>
temperature?: number
warnings?: Array<unknown>
event: "ai:generation"
V1AutomateEventAIGenerationError { data, event }

Envelope for the “ai:generation:error” event from /v1/automate.

data: Data { error, iterationId, prompt, 3 more }

Event data when AI generation error occurs

error: string
iterationId: string
prompt: string
schema: unknown
timestamp: number
messages?: Array<unknown>
event: "ai:generation:error"
V1AutomateEventBrowserActionCompleted { data, event }

Envelope for the “browser:action_completed” event from /v1/automate.

data: Data { iterationId, success, timestamp, error }

Event data for action results

iterationId: string
success: boolean
timestamp: number
error?: string
event: "browser:action_completed"
V1AutomateEventBrowserActionStarted { data, event }

Envelope for the “browser:action_started” event from /v1/automate.

data: Data { action, iterationId, timestamp, 2 more }

Event data for action execution

action: string
iterationId: string
timestamp: number
ref?: string | null
value?: string | null
event: "browser:action_started"
V1AutomateEventBrowserNavigated { data, event }

Envelope for the “browser:navigated” event from /v1/automate.

data: Data { iterationId, timestamp, title, url }

Event data when navigating to a page

iterationId: string
timestamp: number
title: string
url: string
event: "browser:navigated"
V1AutomateEventBrowserReconnected { data, event }

Envelope for the “browser:reconnected” event from /v1/automate.

data: Data { endpointIndex, iterationId, startingUrl, 2 more }

Event data when the browser reconnects after a mid-task disconnect

endpointIndex: number

1-based index of the CDP endpoint now in use

iterationId: string
startingUrl: string

The original starting URL the agent is restarting execution from

timestamp: number
total: number

Total number of configured CDP endpoints

event: "browser:reconnected"
V1AutomateEventBrowserScreenshotCaptured { data, event }

Envelope for the “browser:screenshot_captured” event from /v1/automate.

data: Data { format, iterationId, size, timestamp }

Event data for screenshot capture

format: "jpeg" | "png"
One of the following:
"jpeg"
"png"
iterationId: string
size: number
timestamp: number
event: "browser:screenshot_captured"
V1AutomateEventBrowserScreenshotCapturedImage { data, event }

Envelope for the “browser:screenshot_captured_image” event from /v1/automate.

data: Data { image, iterationId, mediaType, timestamp }

Event data for screenshot image capture with full image data This event contains the complete screenshot and can be very large

image: string
iterationId: string
mediaType: "image/jpeg" | "image/png"
One of the following:
"image/jpeg"
"image/png"
timestamp: number
event: "browser:screenshot_captured_image"
V1AutomateEventCdpEndpointConnected { data, event }

Envelope for the “cdp:endpoint_connected” event from /v1/automate.

data: Data { endpointIndex, iterationId, timestamp, total }

Event data when a CDP endpoint is successfully connected to

endpointIndex: number

1-based index of the endpoint that connected

iterationId: string
timestamp: number
total: number

Total number of configured CDP endpoints

event: "cdp:endpoint_connected"
V1AutomateEventCdpEndpointCycle { data, event }

Envelope for the “cdp:endpoint_cycle” event from /v1/automate.

data: Data { attempt, error, iterationId, 2 more }

Event data when a CDP endpoint fails and the next one is being tried

attempt: number

1-based index of the endpoint attempt that failed

error: string

Sanitized error identifier from the failed connection attempt (error.name, not error.message — full messages may contain endpoint URLs)

iterationId: string
timestamp: number
total: number

Total number of configured CDP endpoints

event: "cdp:endpoint_cycle"
V1AutomateEventComplete { data, event }

Envelope for the “complete” event from /v1/automate.

data: Data { finalAnswer, stats, success, error }

Payload for the complete stream event. Structurally identical to TaskExecutionResult from webAgent.ts — the complete event’s data is the agent’s final TaskExecutionResult, stringified onto the SSE stream.

finalAnswer: string | null

Final answer or result from the agent

stats: Stats { actions, durationMs, endTime, 2 more }

Execution statistics

actions: number
durationMs: number
endTime: number
iterations: number
startTime: number
success: boolean

Whether the task completed successfully

error?: Error { code, message }

Structured error information for failed tasks

code: "TASK_ABORTED" | "MAX_ITERATIONS" | "MAX_ERRORS" | "TASK_FAILED"

Error codes for task failures

One of the following:
"TASK_ABORTED"
"MAX_ITERATIONS"
"MAX_ERRORS"
"TASK_FAILED"
message: string

Human-readable error message

event: "complete"
V1AutomateEventDone { data, event }

Envelope for the “done” event from /v1/automate.

data: Record<string, unknown>

Payload for the done stream terminator event. Empty today; reserved for future metadata.

event: "done"
V1AutomateEventError { data, event }

Envelope for the “error” event from /v1/automate.

data: Data { error, success }

Payload for the top-level error stream event. Emitted when an uncaught error escapes the task runner. Mirrors ErrorResponse from the server package’s taskRunner.ts — kept structurally aligned so schema and runtime stay consistent. Distinct from agent-level error events like ai:generation:error and task:validation_error, which are emitted through the normal event emitter during the agent loop.

error: Error { code, message, timestamp }
code: string
message: string
timestamp: string

ISO-8601 timestamp

success: false
event: "error"
V1AutomateEventInteractiveFormDataError { data, event }

Envelope for the “interactive:form_data:error” event from /v1/automate.

data: Data { fieldErrors, fields, formDescription, 5 more }

Event data when form validation fails and the agent re-requests data. Carries both the error context and the fields that need new values. Callers respond to this the same way as a request event.

fieldErrors: Record<string, string>

Per-field error messages from validation (field ref -> error text)

fields: Array<Field>
fieldType: "text" | "email" | "phone" | 8 more

Semantic field type

One of the following:
"text"
"email"
"phone"
"date"
"number"
"select"
"checkbox"
"radio"
"textarea"
"password"
"other"
label: string

The field’s visible label

ref: string

Element ref from the accessibility tree (e.g., “E42”)

required: boolean

Whether this field must be filled

currentValue?: string

Current value if already partially filled

description?: string

Additional context (e.g., validation error message on re-request)

options?: Array<string>

Available options for select/radio fields

formDescription: string
iterationId: string
pageTitle: string
pageUrl: string
requestId: string
timestamp: number
event: "interactive:form_data:error"
V1AutomateEventInteractiveFormDataRequest { data, event }

Envelope for the “interactive:form_data:request” event from /v1/automate.

data: Data { fields, formDescription, iterationId, 4 more }

Event data when the agent requests user data for form fields

fields: Array<Field>
fieldType: "text" | "email" | "phone" | 8 more

Semantic field type

One of the following:
"text"
"email"
"phone"
"date"
"number"
"select"
"checkbox"
"radio"
"textarea"
"password"
"other"
label: string

The field’s visible label

ref: string

Element ref from the accessibility tree (e.g., “E42”)

required: boolean

Whether this field must be filled

currentValue?: string

Current value if already partially filled

description?: string

Additional context (e.g., validation error message on re-request)

options?: Array<string>

Available options for select/radio fields

formDescription: string
iterationId: string
pageTitle: string
pageUrl: string
requestId: string
timestamp: number
event: "interactive:form_data:request"
V1AutomateEventSystemDebugCompression { data, event }

Envelope for the “system:debug_compression” event from /v1/automate.

data: Data { compressedSize, compressionPercent, iterationId, 2 more }

Event data for compression debug info

compressedSize: number
compressionPercent: number
iterationId: string
originalSize: number
timestamp: number
event: "system:debug_compression"
V1AutomateEventSystemDebugMessage { data, event }

Envelope for the “system:debug_message” event from /v1/automate.

data: Data { iterationId, messages, timestamp }

Event data for message debug info

iterationId: string
messages: Array<unknown>
timestamp: number
event: "system:debug_message"
V1AutomateEventTaskAborted { data, event }

Envelope for the “task:aborted” event from /v1/automate.

data: Data { finalAnswer, iterationId, reason, timestamp }

Event data when a task is aborted

finalAnswer: string
iterationId: string
reason: string
timestamp: number
event: "task:aborted"
V1AutomateEventTaskCompleted { data, event }

Envelope for the “task:completed” event from /v1/automate.

data: Data { finalAnswer, iterationId, timestamp, success }

Event data when a task is completed

finalAnswer: string | null
iterationId: string
timestamp: number
success?: boolean
event: "task:completed"
V1AutomateEventTaskMetrics { data, event }

Envelope for the “task:metrics” event from /v1/automate.

data: Data { aiGenerationCount, aiGenerationErrorCount, eventCounts, 5 more }
aiGenerationCount: number
aiGenerationErrorCount: number
eventCounts: Record<string, number>
iterationId: string
stepCount: number
timestamp: number
totalInputTokens: number
totalOutputTokens: number
event: "task:metrics"
V1AutomateEventTaskMetricsIncremental { data, event }

Envelope for the “task:metrics_incremental” event from /v1/automate.

data: Data { aiGenerationCount, aiGenerationErrorCount, eventCounts, 5 more }
aiGenerationCount: number
aiGenerationErrorCount: number
eventCounts: Record<string, number>
iterationId: string
stepCount: number
timestamp: number
totalInputTokens: number
totalOutputTokens: number
event: "task:metrics_incremental"
V1AutomateEventTaskSetup { data, event }

Envelope for the “task:setup” event from /v1/automate.

data: Data { browserName, iterationId, task, 14 more }

Event data when a task is setup

browserName: string
iterationId: string
task: string
timestamp: number
data?: unknown
guardrails?: string
hasApiKey?: boolean
keySource?: "global" | "env" | "not_set"
One of the following:
"global"
"env"
"not_set"
model?: string
provider?: string
proxy?: string
pwCdpEndpoint?: string
pwCdpEndpointCount?: number

Total number of CDP endpoints configured (index, not URLs)

pwCdpEndpoints?: Array<string>
pwEndpoint?: string
url?: string
vision?: boolean
event: "task:setup"
V1AutomateEventTaskStarted { data, event }

Envelope for the “task:started” event from /v1/automate.

data: Data { iterationId, plan, successCriteria, 4 more }

Event data when a task is started

iterationId: string
plan: string
successCriteria: string
task: string
timestamp: number
url: string
actionItems?: Array<string>
event: "task:started"
V1AutomateEventTaskTraceContext { data, event }

Envelope for the “task:trace_context” event from /v1/automate.

data: Data { traceId }

Payload for the task:trace_context event. Carries the OpenTelemetry trace ID for this /v1/automate request so consumers can deep-link to distributed-tracing UIs (e.g. Cloud Trace, Cloud Logging) for the run.

traceId: string

W3C trace ID — 32-character lowercase hexadecimal string.

event: "task:trace_context"
V1AutomateEventTaskValidated { data, event }

Envelope for the “task:validated” event from /v1/automate.

data: Data { completionQuality, finalAnswer, iterationId, 3 more }

Event data for task validation

completionQuality: "failed" | "partial" | "complete" | "excellent"
One of the following:
"failed"
"partial"
"complete"
"excellent"
finalAnswer: string
iterationId: string
observation: string
timestamp: number
feedback?: string
event: "task:validated"
V1AutomateEventTaskValidationError { data, event }

Envelope for the “task:validation_error” event from /v1/automate.

data: Data { errors, iterationId, rawResponse, 2 more }

Event data for validation errors during action response processing

errors: Array<string>
iterationId: string
rawResponse: unknown
retryCount: number
timestamp: number
event: "task:validation_error"
ResearchEvent = V1ResearchEventAnalyzingEnd { data, event } | V1ResearchEventAnalyzingStart { data, event } | V1ResearchEventComplete { data, event } | 20 more

A Server-Sent Event from /v1/research. Typed discriminated union keyed on event.

One of the following:
V1ResearchEventAnalyzingEnd { data, event }

Envelope for the “analyzing:end” event from /v1/research.

data: Data { analyzed, failed, iteration, 3 more }
analyzed: number
failed: number
iteration: number
message: string
samples: Array<Sample>
domain: string
title: string
url: string
urlSource: "user-input" | "search-result" | "extracted-link"

URL source tracking - where a URL came from

One of the following:
"user-input"
"search-result"
"extracted-link"
relevance?: "low" | "medium" | "high"
One of the following:
"low"
"medium"
"high"
reliability?: "low" | "medium" | "high"
One of the following:
"low"
"medium"
"high"
summary?: string
timestamp: number
event: "analyzing:end"
V1ResearchEventAnalyzingStart { data, event }

Envelope for the “analyzing:start” event from /v1/research.

data: Data { iteration, message, pageCount, timestamp }
iteration: number
message: string
pageCount: number
timestamp: number
event: "analyzing:start"
V1ResearchEventComplete { data, event }

Envelope for the “complete” event from /v1/research.

data: Data { message, metadata, report, timestamp }

complete - Research finished successfully

message: string
metadata: Metadata { executedQueries, mode, prompt, 11 more }

Research metadata

Note: citedPages, gapEvaluations, outline, and judgments are optional to support fast mode, which skips these phases for maximum speed.

executedQueries: Array<Array<string>>
mode: "fast" | "balanced" | "deep" | 2 more

Research mode determines depth, thinking budget, and quality controls

Modes (in order of cost/thoroughness):

  • fast: Quick answers with minimal validation (~$2, 1 iteration, no judge)
  • balanced: Standard research with moderate depth (~$8, 3 iterations, Flash models, no judge)
  • deep: Thorough research with judge review (~$15, 5 iterations, Flash models, with judge)
  • max: Maximum quality with Pro models (~$40, 5 iterations, Pro models, with judge)
  • ultra: Ultimate tier - all Pro models, 10 iterations (expensive, for when accuracy is paramount)
One of the following:
"fast"
"balanced"
"deep"
"max"
"ultra"
prompt: string
queryComplexity: "simple" | "moderate" | "complex"
One of the following:
"simple"
"moderate"
"complex"
researchObjective: string
researchPlan: string
researchQuestions: Array<string>
totalPagesAnalyzed: number

Total pages analyzed across all iterations

citedPages?: Array<CitedPage>

Pages cited in the report, ordered by first citation appearance

id: string
claims: Array<string>
sourceQueries: Array<string>
url: string
depth?: number
fullText?: string

Full page text (fetched markdown or search excerpts). Only populated when includeFullText: true in ResearchOptions.

  • Fast mode: Parallel API excerpts (~5000 chars)
  • Other modes: Fetched page markdown
parentUrl?: string
relevance?: "low" | "medium" | "high"
One of the following:
"low"
"medium"
"high"
reliability?: "low" | "medium" | "high"
One of the following:
"low"
"medium"
"high"
summary?: string

LLM-generated summary. Undefined in fast mode (no content analysis).

title?: string
urlSource?: "user-input" | "search-result" | "extracted-link"

URL source tracking - where a URL came from

One of the following:
"user-input"
"search-result"
"extracted-link"
gapEvaluations?: Array<GapEvaluation>
gapDescription: string

Based on unanswered/partial questions, what specific information is still needed?

questionAssessments: Array<QuestionAssessment>

Assessment of each research question’s status and findings

findings: string

What we learned (if answered/partial) or what’s missing (if unanswered)

question: string

The research question being assessed

status: "answered" | "partial" | "unanswered"

Status: answered (clear info), partial (some info, gaps remain), unanswered (no relevant info)

One of the following:
"answered"
"partial"
"unanswered"
researchCoverage: "Light" | "Moderate" | "Solid" | "Comprehensive"

Research coverage level - assesses quality across all questions.

Hierarchy: Light < Moderate < Solid < Comprehensive

  • Light: Basic info on some questions, most need more depth → Continue
  • Moderate: Multiple questions answered, some remain partial → Continue
  • Solid: Most questions well-answered with validated sources → Sufficient to stop
  • Comprehensive: All questions thoroughly answered, exceptional depth → Definitely stop
One of the following:
"Light"
"Moderate"
"Solid"
"Comprehensive"
shouldContinueResearch: boolean

Explicit decision: should research continue with another iteration?

  • Considers: how many questions unanswered/partial, coverage for mode, remaining iterations
  • Drives query generation: true → generate queries, false → stop researching
newResearchQuestions?: Array<string>

New research questions to add (optional, use sparingly)

  • Only if original decomposition missed something critical
  • Maximum 2-3 new questions total across all iterations
  • Most iterations should return empty array or omit this field
searchQueries?: Array<string>

Search queries to address identified gaps (only when shouldContinueResearch is true)

  • Target unanswered questions first, then partial questions
  • 3-10 targeted queries if shouldContinueResearch is true
  • Omit or provide empty array if shouldContinueResearch is false
judgments?: Array<Judgment>
approved: boolean
observation: string
score: number
feedback?: string
metrics?: Metrics { cachedFetches, cachedSearches, fetches, 7 more }

Complete research metrics

cachedFetches: number

Cached fetch count (subset of fetches)

cachedSearches: Record<string, number>

Cached search count by provider name (subset of searches)

fetches: number

Fetch count (number of pages fetched)

iterations: number

Number of research iterations performed

phases: Record<string, Phases>

Phase timings with duration in milliseconds

duration: number
robotsBlocked: number

Number of URLs blocked by robots.txt

searches: Record<string, number>

Search count by provider name (e.g., “bright-data”, “parallel”)

successRates: SuccessRates { analyzes, fetches, searches }

Success rate metrics

analyzes: number
fetches: number
searches: number
tokens: Record<string, Tokens>

Token usage by model ID (e.g., “gemini-2.5-flash”)

input: number
output: number
totalDuration: number

Total duration in milliseconds

outline?: Outline { directAnswer, keyTakeaways, outline, relevantSourceIds }

Report outline from research writer

directAnswer: string
keyTakeaways: Array<string>
outline: string
relevantSourceIds: Array<string>
urlSources?: URLSources { extractedLinks, searchResults, userProvided }
searchResults: number
userProvided: number
report: string
timestamp: number
event: "complete"
V1ResearchEventError { data, event }

Envelope for the “error” event from /v1/research.

data: Data { error, message, timestamp, 2 more }

error - Research failed

error: Error { message, name, stack }
message: string
name: string
stack?: string
message: string
timestamp: number
activity?: "prefetching" | "planning" | "iteration" | 7 more

Activity types for research workflow

One of the following:
"prefetching"
"planning"
"iteration"
"searching"
"analyzing"
"following"
"evaluating"
"outlining"
"writing"
"judging"
iteration?: number
event: "error"
V1ResearchEventEvaluatingEnd { data, event }

Envelope for the “evaluating:end” event from /v1/research.

data: Data { coverage, gaps, iteration, 5 more }
coverage: "Light" | "Moderate" | "Solid" | "Comprehensive"
One of the following:
"Light"
"Moderate"
"Solid"
"Comprehensive"
gaps: string
iteration: number
message: string
nextQueries: Array<string>
questionAssessments: Array<QuestionAssessment>
findings: string

What we learned (if answered/partial) or what’s missing (if unanswered)

question: string

The research question being assessed

status: "answered" | "partial" | "unanswered"

Status: answered (clear info), partial (some info, gaps remain), unanswered (no relevant info)

One of the following:
"answered"
"partial"
"unanswered"
shouldContinue: boolean
timestamp: number
event: "evaluating:end"
V1ResearchEventEvaluatingStart { data, event }

Envelope for the “evaluating:start” event from /v1/research.

data: Data { iteration, message, pagesAnalyzed, 2 more }
iteration: number
message: string
pagesAnalyzed: number

Total pages analyzed so far (including this iteration)

questionCount: number

Number of research questions being assessed

timestamp: number
event: "evaluating:start"
V1ResearchEventFollowingEnd { data, event }

Envelope for the “following:end” event from /v1/research.

data: Data { failed, followed, iteration, 3 more }
failed: number
followed: number
iteration: number
message: string
samples: Array<Sample>
domain: string
title: string
url: string
urlSource: "user-input" | "search-result" | "extracted-link"

URL source tracking - where a URL came from

One of the following:
"user-input"
"search-result"
"extracted-link"
relevance?: "low" | "medium" | "high"
One of the following:
"low"
"medium"
"high"
reliability?: "low" | "medium" | "high"
One of the following:
"low"
"medium"
"high"
summary?: string
timestamp: number
event: "following:end"
V1ResearchEventFollowingStart { data, event }

Envelope for the “following:start” event from /v1/research.

data: Data { iteration, linkCount, message, timestamp }
iteration: number
linkCount: number
message: string
timestamp: number
event: "following:start"
V1ResearchEventIterationEnd { data, event }

Envelope for the “iteration:end” event from /v1/research.

data: Data { isLast, iteration, message, 2 more }
isLast: boolean

Whether this is the final iteration

iteration: number
message: string
timestamp: number
stopReason?: "max_iterations" | "coverage_sufficient"

Why research iterations stopped (only present when isLast is true)

One of the following:
"max_iterations"
"coverage_sufficient"
event: "iteration:end"
V1ResearchEventIterationStart { data, event }

Envelope for the “iteration:start” event from /v1/research.

data: Data { iteration, maxIterations, message, 2 more }
iteration: number
maxIterations: number

Maximum iterations for this research mode

message: string
queries: Array<string>

Search queries to execute in this iteration

timestamp: number
event: "iteration:start"
V1ResearchEventJudgingEnd { data, event }

Envelope for the “judging:end” event from /v1/research.

data: Data { approved, attempt, message, 3 more }
approved: boolean
attempt: number
message: string
score: number
timestamp: number
feedback?: string
event: "judging:end"
V1ResearchEventJudgingStart { data, event }

Envelope for the “judging:start” event from /v1/research.

data: Data { attempt, maxAttempts, message, timestamp }
attempt: number
maxAttempts: number

Maximum attempts allowed (1 + maxRevisions)

message: string
timestamp: number
event: "judging:start"
V1ResearchEventOutliningEnd { data, event }

Envelope for the “outlining:end” event from /v1/research.

data: Data { message, sourcesSelected, timestamp }
message: string
sourcesSelected: number
timestamp: number
event: "outlining:end"
V1ResearchEventOutliningStart { data, event }

Envelope for the “outlining:start” event from /v1/research.

data: Data { message, pagesAnalyzed, qualityPageCount, timestamp }
message: string
pagesAnalyzed: number

Total pages analyzed across all iterations

qualityPageCount: number

Pages that meet quality threshold (medium+ relevance and reliability)

timestamp: number
event: "outlining:start"
V1ResearchEventPlanningEnd { data, event }

Envelope for the “planning:end” event from /v1/research.

data: Data { complexity, message, objective, 4 more }
complexity: "simple" | "moderate" | "complex"
One of the following:
"simple"
"moderate"
"complex"
message: string
objective: string
plan: string
queries: Array<string>
questions: Array<string>
timestamp: number
event: "planning:end"
V1ResearchEventPlanningStart { data, event }

Envelope for the “planning:start” event from /v1/research.

data: Data { hasPrefetchedContext, message, timestamp }
hasPrefetchedContext: boolean

Whether prefetched user-provided URLs exist for context

message: string
timestamp: number
event: "planning:start"
V1ResearchEventPrefetchingEnd { data, event }

Envelope for the “prefetching:end” event from /v1/research.

data: Data { failed, fetched, message, timestamp }
failed: number
fetched: number
message: string
timestamp: number
event: "prefetching:end"
V1ResearchEventPrefetchingStart { data, event }

Envelope for the “prefetching:start” event from /v1/research.

data: Data { message, timestamp, urlCount, urls }
message: string
timestamp: number
urlCount: number
urls: Array<string>
event: "prefetching:start"
V1ResearchEventSearchingEnd { data, event }

Envelope for the “searching:end” event from /v1/research.

data: Data { iteration, message, timestamp, 2 more }
iteration: number
message: string
timestamp: number
urlsFound: number
urlsNew: number
event: "searching:end"
V1ResearchEventSearchingStart { data, event }

Envelope for the “searching:start” event from /v1/research.

data: Data { iteration, message, queries, timestamp }
iteration: number
message: string
queries: Array<string>
timestamp: number
event: "searching:start"
V1ResearchEventStart { data, event }

Envelope for the “start” event from /v1/research.

data: Data { message, timestamp }

start - Research begins

message: string
timestamp: number
event: "start"
V1ResearchEventWritingEnd { data, event }

Envelope for the “writing:end” event from /v1/research.

data: Data { attempt, message, timestamp }
attempt: number
message: string
timestamp: number
event: "writing:end"
V1ResearchEventWritingStart { data, event }

Envelope for the “writing:start” event from /v1/research.

data: Data { attempt, isRevision, maxAttempts, 3 more }
attempt: number
isRevision: boolean

Whether this is a revision attempt (attempt > 1)

maxAttempts: number

Maximum attempts allowed (1 + maxRevisions)

message: string
timestamp: number
previousScore?: number

Previous judgment score if this is a revision

event: "writing:start"
AgentAutomateInputResponse { status }
status?: string