SendToAgentExecution

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."

Body ParametersJSONExpand Collapse

agentExecutionId: optional string

formatuuid

agentMessage: optional 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: optional string

Free-form payload of the message.

type: optional Type

One of the following:

"TYPE_UNSPECIFIED"

"TYPE_UPDATE"

"TYPE_COMPLETE"

userInput: optional UserInputBlock { id, createdAt, image, 2 more }

id: optional string

createdAt: optional string

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

formatdate-time

Deprecatedimage: optional object { data, mimeType }

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

data: optional string

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

formatbyte

maxLength4194304

minLength1

mimeType: optional "image/png" or "image/jpeg"

One of the following:

"image/png"

"image/jpeg"

inputs: optional array of object { image, text }

image: optional object { data, mimeType }

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

data: optional string

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

formatbyte

maxLength4194304

minLength1

mimeType: optional "image/png" or "image/jpeg"

One of the following:

"image/png"

"image/jpeg"

text: optional object { content }

content: optional string

minLength1

Deprecatedtext: optional object { content }

content: optional string

minLength1

wakeEvent: optional 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: optional object { environmentId, failureMessage, phase }

environmentId: optional string

failureMessage: optional array of string

phase: optional string

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

interestId: optional string

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

loopRetrigger: optional object { outputs, unmetConditions }

outputs: optional map[string]

unmetConditions: optional array of object { id, description, expression, 3 more }

id: optional string

description: optional string

expression: optional string

iteration: optional number

formatint32

maxIterations: optional number

formatint32

reason: optional string

timer: optional object { firedAt }

firedAt: optional string

The actual time the timer was evaluated as expired.

formatdate-time

SendToAgentExecution

curl https://app.gitpod.io/api/gitpod.v1.AgentService/SendToAgentExecution \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $GITPOD_API_KEY" \
    -d '{}'

{}

Returns Examples

{}