Skip to content
Ona API Reference
Ona Docs
API Reference
Agents

SendToAgentExecution

client.agents.sendToExecution(AgentSendToExecutionParams { agentExecutionId, agentMessage, userInput, wakeEvent } body, RequestOptionsoptions?): AgentSendToExecutionResponse
POST/gitpod.v1.AgentService/SendToAgentExecution

Sends user input to an active agent run.

This method is used to provide interactive or conversation-based input to an agent. The agent can respond with output blocks containing text, file changes, or tool usage requests.

Examples

  • Send a text message to an agent:

    agentExecutionId: "6fa1a3c7-fbb7-49d1-ba56-1890dc7c4c35"
userInput:
  text:
    content: "Generate a report based on the latest logs."
ParametersExpand Collapse
body: AgentSendToExecutionParams { agentExecutionId, agentMessage, userInput, wakeEvent }
agentExecutionId?: string
formatuuid
agentMessage?: AgentMessage { payload, type }

AgentMessage is a message sent between agents (e.g. from a parent agent to a child agent execution, or vice versa).

payload?: string

Free-form payload of the message.

type?: Type
One of the following:
"TYPE_UNSPECIFIED"
"TYPE_UPDATE"
"TYPE_COMPLETE"
userInput?: UserInputBlock { id, createdAt, image, 2 more }
id?: string
createdAt?: string

Timestamp when this block was created. Used for debugging and support bundles.

formatdate-time
Deprecatedimage?: Image { data, mimeType }

ImageInput allows sending images to the agent. Client must provide the MIME type; backend validates against magic bytes.

data?: string

Raw image data (max 4MB). Supported formats: PNG, JPEG.

formatbyte
maxLength4194304
minLength1
mimeType?: "image/png" | "image/jpeg"
One of the following:
"image/png"
"image/jpeg"
inputs?: Array<Input>
image?: Image { data, mimeType }

ImageInput allows sending images to the agent. Client must provide the MIME type; backend validates against magic bytes.

data?: string

Raw image data (max 4MB). Supported formats: PNG, JPEG.

formatbyte
maxLength4194304
minLength1
mimeType?: "image/png" | "image/jpeg"
One of the following:
"image/png"
"image/jpeg"
text?: Text { content }
content?: string
minLength1
Deprecatedtext?: Text { content }
content?: string
minLength1
wakeEvent?: WakeEvent { environment, interestId, loopRetrigger, timer }

WakeEvent is sent by the backend to wake an agent when a registered interest fires. Delivered via SendToAgentExecution as a new oneof variant.

environment?: Environment { environmentId, failureMessage, phase }
environmentId?: string
failureMessage?: Array<string>
phase?: string

The phase the environment reached (e.g. “running”, “stopped”, “deleted”).

interestId?: string

The interest ID that fired (from WaitingInfo.Interest.id).

loopRetrigger?: LoopRetrigger { outputs, unmetConditions }
outputs?: Record<string, string>
unmetConditions?: Array<UnmetCondition>
id?: string
description?: string
expression?: string
iteration?: number
formatint32
maxIterations?: number
formatint32
reason?: string
timer?: Timer { firedAt }
firedAt?: string

The actual time the timer was evaluated as expired.

formatdate-time
ReturnsExpand Collapse
AgentSendToExecutionResponse = unknown

SendToAgentExecution

import Gitpod from '@gitpod/sdk';

const client = new Gitpod({
  bearerToken: process.env['GITPOD_API_KEY'], // This is the default and can be omitted
});

const response = await client.agents.sendToExecution({
  agentExecutionId: '6fa1a3c7-fbb7-49d1-ba56-1890dc7c4c35',
  userInput: { text: { content: 'Generate a report based on the latest logs.' } },
});

console.log(response);
{}
Returns Examples
{}