SendToAgentExecution

client.agents.sendToExecution(, ?): 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, codexSettings, 2 more }

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"

codexSettings?: CodexSettings { model, reasoningEffort, serviceTier }

codex_settings contains per-turn desired settings for Codex app user_input sends.

model?: CodexOpenAIModel

CodexOpenAIModel is the static allowlist of concrete OpenAI models that the Codex app runtime can select through Ona’s Codex picker.

One of the following:

"CODEX_OPEN_AI_MODEL_UNSPECIFIED"

"CODEX_OPEN_AI_MODEL_GPT_5_5"

"CODEX_OPEN_AI_MODEL_GPT_5_4"

"CODEX_OPEN_AI_MODEL_GPT_5_4_MINI"

"CODEX_OPEN_AI_MODEL_GPT_5_3_CODEX"

"CODEX_OPEN_AI_MODEL_GPT_5_3_CODEX_SPARK"

"CODEX_OPEN_AI_MODEL_GPT_5_2"

reasoningEffort?: CodexReasoningEffort

CodexReasoningEffort is the static allowlist of reasoning efforts supported by the Codex app runtime.

One of the following:

"CODEX_REASONING_EFFORT_UNSPECIFIED"

"CODEX_REASONING_EFFORT_LOW"

"CODEX_REASONING_EFFORT_MEDIUM"

"CODEX_REASONING_EFFORT_HIGH"

"CODEX_REASONING_EFFORT_EXTRA_HIGH"

serviceTier?: CodexServiceTier

CodexServiceTier is the static allowlist of service tiers supported by the Codex app runtime.

One of the following:

"CODEX_SERVICE_TIER_UNSPECIFIED"

"CODEX_SERVICE_TIER_FAST"

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 { devcontainerRebuild, environment, interestId, 2 more }

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

devcontainerRebuild?: DevcontainerRebuild { environmentId, failureMessage, phase, sessionId }

environmentId?: string

failureMessage?: Array<string>

phase?: string

The devcontainer phase reached by the target session.

sessionId?: string

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

{}