> ## Documentation Index
> Fetch the complete documentation index at: https://ona.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Send To Agent Execution
> Sends user input to an active agent run.
`Unary` ยท [`Agents`](/docs/api-reference/generated/agent/overview)
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:
```yaml theme={null}
agentExecutionId: "6fa1a3c7-fbb7-49d1-ba56-1890dc7c4c35"
userInput:
text:
content: "Generate a report based on the latest logs."
```
## Endpoint
```text theme={null}
POST /api/gitpod.v1.AgentService/SendToAgentExecution
```
Send a Bearer token as described in [Authentication](/docs/api-reference#authenticate-requests). If your organization uses a custom management-plane domain, replace `https://app.ona.com` with that domain.
## Request example
```bash cURL theme={null}
export ONA_HOST=https://app.ona.com
export ONA_API_KEY=
curl --request POST \
--url "$ONA_HOST/api/gitpod.v1.AgentService/SendToAgentExecution" \
--header "Authorization: Bearer $ONA_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"agentExecutionId": ""
}'
```
```python Python theme={null}
import gitpod.v1.agent_pb2 as agent_pb2
from ona_sdk import create_client_from_env
ona = create_client_from_env()
request = agent_pb2.SendToAgentExecutionRequest(
agent_execution_id="",
)
response = ona.services.agent.send_to_agent_execution(request)
print(response)
```
```typescript TypeScript theme={null}
import { create } from "@bufbuild/protobuf";
import { createClientFromEnv } from "@gitpod/sdk";
import { SendToAgentExecutionRequestSchema } from "@gitpod/sdk/gitpod/v1/agent_pb";
async function main() {
const ona = createClientFromEnv();
const request = create(SendToAgentExecutionRequestSchema, {
agentExecutionId: "",
});
const response = await ona.services.agent.sendToAgentExecution(request);
console.log(response);
}
main().catch(console.error);
```
```go Go theme={null}
package main
import (
"context"
"fmt"
"log"
"connectrpc.com/connect"
"github.com/gitpod-io/gitpod-sdk-go/sdk"
gitpodpb "github.com/gitpod-io/gitpod-sdk-go/v1"
)
func main() {
ona, err := sdk.NewFromEnv()
if err != nil {
log.Fatal(err)
}
request := connect.NewRequest(&gitpodpb.SendToAgentExecutionRequest{
AgentExecutionId: "",
})
response, err := ona.Services.Agent.SendToAgentExecution(context.Background(), request)
if err != nil {
log.Fatal(err)
}
fmt.Println(response.Msg)
}
```
```json Request body theme={null}
{
"agentExecutionId": ""
}
```
## Request
`gitpod.v1.SendToAgentExecutionRequest`
| Field | Type | Required | Description |
| ------------------ | -------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------- |
| `agentExecutionId` | string | No | Constraints: `string.uuid=true`. |
| `userInput` | [UserInputBlock](#type-gitpod-v1-user-input-block) | No | |
| `agentMessage` | [AgentMessage](#type-gitpod-v1-agent-message) | No | |
| `wakeEvent` | [WakeEvent](#type-gitpod-v1-wake-event) | No | |
| `controlInput` | [AgentControlInput](#type-gitpod-v1-agent-control-input) | No | |
| `codexSettings` | [CodexSettings](#type-gitpod-v1-codex-settings) | No | codex\_settings contains per-turn desired settings for Codex app user\_input sends. |
| `turnOptions` | [TurnOptions](#type-gitpod-v1-turn-options) | No | turn\_options contains options that apply to this submitted turn. |
## Response
`gitpod.v1.SendToAgentExecutionResponse`
This message has no fields.
## Related types
`gitpod.v1.AgentControlInput`
| Field | Type | Required | Description |
| --------------------- | -------------------------------------------------------------------------------- | -------- | ----------- |
| `compact` | [Compact](#type-gitpod-v1-agent-control-input-compact) | No | |
| `goal` | [Goal](#type-gitpod-v1-agent-control-input-goal) | No | |
| `deleteQueuedMessage` | [DeleteQueuedMessage](#type-gitpod-v1-agent-control-input-delete-queued-message) | No | |
| `steerQueuedMessage` | [SteerQueuedMessage](#type-gitpod-v1-agent-control-input-steer-queued-message) | No | |
| `moveQueuedMessage` | [MoveQueuedMessage](#type-gitpod-v1-agent-control-input-move-queued-message) | No | |
`gitpod.v1.AgentControlInput.Compact`
This message has no fields.
`gitpod.v1.AgentControlInput.DeleteQueuedMessage`
| Field | Type | Required | Description |
| ------------- | ------ | -------- | -------------------------------- |
| `userInputId` | string | No | Constraints: `string.min_len=1`. |
`gitpod.v1.AgentControlInput.Goal`
| Field | Type | Required | Description |
| ---------- | -------- | -------- | ----------- |
| `pause` | Pause | No | |
| `resume` | Resume | No | |
| `complete` | Complete | No | |
| `clear` | Clear | No | |
| `set` | Set | No | |
`gitpod.v1.AgentControlInput.MoveQueuedMessage`
| Field | Type | Required | Description |
| ------------------- | ------ | -------- | ----------------------------------------------------------------------------------------------- |
| `userInputId` | string | No | Constraints: `string.min_len=1`. |
| `beforeUserInputId` | string | No | before\_user\_input\_id is the queued user input to insert before. Empty means move to the end. |
`gitpod.v1.AgentControlInput.SteerQueuedMessage`
| Field | Type | Required | Description |
| ------------- | ------ | -------- | -------------------------------- |
| `userInputId` | string | No | Constraints: `string.min_len=1`. |
AgentMessage is a message sent between agents (e.g. from a parent agent to a
child agent execution, or vice versa).
`gitpod.v1.AgentMessage`
| Field | Type | Required | Description |
| ------------------- | ------------------------------------------ | -------- | ----------------------------------------------------- |
| `type` | [Type](#enum-gitpod-v1-agent-message-type) | No | |
| `payload` | string | No | Free-form payload of the message. |
| `role` | [Role](#enum-gitpod-v1-agent-message-role) | No | The role of the sender in the agent hierarchy. |
| `senderExecutionId` | string | No | The execution ID of the agent that sent this message. |
CodexSettings contains settings consumed only by the Codex app agent.
`gitpod.v1.CodexSettings`
| Field | Type | Required | Description |
| ----------------- | -------------------------------------------------------------- | -------- | -------------------------------------- |
| `model` | [CodexOpenAIModel](#enum-gitpod-v1-codex-open-ai-model) | No | Constraints: `enum.defined_only=true`. |
| `reasoningEffort` | [CodexReasoningEffort](#enum-gitpod-v1-codex-reasoning-effort) | No | Constraints: `enum.defined_only=true`. |
| `serviceTier` | [CodexServiceTier](#enum-gitpod-v1-codex-service-tier) | No | Constraints: `enum.defined_only=true`. |
`gitpod.v1.TurnOptions`
| Field | Type | Required | Description |
| ------- | ------------------------------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `modes` | array of [AgentMode](#enum-gitpod-v1-agent-mode) | No | modes contains requested modes for this turn. Agents decide whether a mode remains active after the submitted turn and report durable state via AgentExecution.Status. Constraints: `repeated.max_items=4`. |
`gitpod.v1.UserInputBlock`
| Field | Type | Required | Description |
| ----------- | ---------------------------------------------------------- | -------- | ------------------------------------------------------------------------------ |
| `id` | string | No | |
| `text` | [TextInput](#type-gitpod-v1-user-input-block-text-input) | No | **Deprecated.** |
| `image` | [ImageInput](#type-gitpod-v1-user-input-block-image-input) | No | **Deprecated.** |
| `inputs` | array of [Input](#type-gitpod-v1-user-input-block-input) | No | Constraints: `repeated.max_items=10`. |
| `createdAt` | RFC 3339 timestamp | No | Timestamp when this block was created. Used for debugging and support bundles. |
| `metadata` | [UserInputMetadata](#type-gitpod-v1-user-input-metadata) | No | Integration-specific metadata for this input. |
ImageInput allows sending images to the agent.
Client must provide the MIME type; backend validates against magic bytes.
`gitpod.v1.UserInputBlock.ImageInput`
| Field | Type | Required | Description |
| ---------- | ------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data` | base64 string | No | Raw image data (max 4MB). Supported formats: PNG, JPEG. Constraints: `bytes.max_len=4194304, bytes.min_len=1`. |
| `mimeType` | string | No | Constraints: `string.in=image/jpeg, string.in=image/png`. |
| `dataRef` | string | No | Content-addressed reference to offloaded image data. Set by the runner when storing in the conversation store; data is cleared. Clients never send this field. |
`gitpod.v1.UserInputBlock.Input`
| Field | Type | Required | Description |
| ------- | ---------- | -------------- | ----------- |
| `text` | TextInput | One of `input` | |
| `image` | ImageInput | One of `input` | |
`gitpod.v1.UserInputBlock.TextInput`
| Field | Type | Required | Description |
| --------- | ------ | -------- | -------------------------------- |
| `content` | string | No | Constraints: `string.min_len=1`. |
UserInputMetadata carries integration-specific context for a user input.
Internal only - not exposed in public SDKs. External API consumers should
not set these fields; they are populated by integration handlers.
`gitpod.v1.UserInputMetadata`
| Field | Type | Required | Description |
| -------- | ------------------------------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `source` | string | No | Origin of this input - set by integration handlers to their host (e.g. "github.com", "slack.com"). Empty for non-integration callers. This field drives emission gating: when set, agent responses are only emitted to the matching integration. Treated as trusted input from integration handlers; not validated against registered hosts. |
| `modes` | array of [AgentMode](#enum-gitpod-v1-agent-mode) | No | modes records the structured modes requested for this user input. When present, clients should prefer these modes over legacy prompt prefixes for rendering user-message labels. Constraints: `repeated.max_items=4`. |
WakeEvent is sent by the backend to wake an agent when a registered interest fires.
Delivered via SendToAgentExecution as a new oneof variant.
`gitpod.v1.WakeEvent`
| Field | Type | Required | Description |
| --------------------- | --------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------- |
| `interestId` | string | No | The interest ID that fired (from WaitingInfo.Interest.id). |
| `timer` | [TimerFired](#type-gitpod-v1-wake-event-timer-fired) | No | |
| `loopRetrigger` | [LoopRetrigger](#type-gitpod-v1-wake-event-loop-retrigger) | No | |
| `environment` | [EnvironmentPhaseReached](#type-gitpod-v1-wake-event-environment-phase-reached) | No | |
| `devcontainerRebuild` | [DevcontainerPhaseReached](#type-gitpod-v1-wake-event-devcontainer-phase-reached) | No | |
`gitpod.v1.WakeEvent.DevcontainerPhaseReached`
| Field | Type | Required | Description |
| ---------------- | --------------- | -------- | ----------------------------------------------------- |
| `environmentId` | string | No | |
| `phase` | string | No | The devcontainer phase reached by the target session. |
| `sessionId` | string | No | |
| `failureMessage` | array of string | No | |
`gitpod.v1.WakeEvent.EnvironmentPhaseReached`
| Field | Type | Required | Description |
| ---------------- | --------------- | -------- | ------------------------------------------------------------------------- |
| `environmentId` | string | No | |
| `phase` | string | No | The phase the environment reached (e.g. "running", "stopped", "deleted"). |
| `failureMessage` | array of string | No | |
`gitpod.v1.WakeEvent.LoopRetrigger`
| Field | Type | Required | Description |
| ----------------- | ----------------------- | -------- | ----------- |
| `unmetConditions` | array of UnmetCondition | No | |
| `outputs` | map of string to string | No | |
`gitpod.v1.WakeEvent.TimerFired`
| Field | Type | Required | Description |
| --------- | ------------------ | -------- | --------------------------------------------------- |
| `firedAt` | RFC 3339 timestamp | No | The actual time the timer was evaluated as expired. |
Role identifies the sender's relationship in the parent/child hierarchy.
| Value | Number | Description |
| ------------------ | -----: | ---------------------------------- |
| `ROLE_UNSPECIFIED` | 0 | |
| `ROLE_PARENT` | 1 | The sender is the parent agent. |
| `ROLE_CHILD` | 2 | The sender is a child (sub-agent). |
| Value | Number | Description |
| ------------------ | -----: | ------------------------------------------------------ |
| `TYPE_UNSPECIFIED` | 0 | |
| `TYPE_UPDATE` | 1 | Regular inter-agent update message. |
| `TYPE_COMPLETE` | 2 | Signals that the sending agent has completed its task. |
AgentMode defines the operational mode of an agent
| Value | Number | Description |
| ------------------------ | -----: | ----------------------------------------------------------------- |
| `AGENT_MODE_UNSPECIFIED` | 0 | Default execution mode - standard agent behavior |
| `AGENT_MODE_EXECUTION` | 1 | Execution mode - agent performs tasks and makes changes |
| `AGENT_MODE_PLANNING` | 2 | Planning mode - agent focuses on analysis and planning |
| `AGENT_MODE_RALPH` | 3 | Ralph mode - autonomous planning and implementation mode |
| `AGENT_MODE_SPEC` | 4 | Spec mode - planning phase followed by interactive implementation |
| `AGENT_MODE_GOAL` | 5 | Goal mode - agent treats the user input as a goal objective |
CodexOpenAIModel is the static allowlist of concrete OpenAI models that the
Codex app runtime can select through Ona's Codex picker.
| Value | Number | Description |
| ----------------------------------------- | -----: | --------------- |
| `CODEX_OPEN_AI_MODEL_UNSPECIFIED` | 0 | |
| `CODEX_OPEN_AI_MODEL_GPT_5_5` | 1 | |
| `CODEX_OPEN_AI_MODEL_GPT_5_4` | 2 | |
| `CODEX_OPEN_AI_MODEL_GPT_5_4_MINI` | 3 | **Deprecated.** |
| `CODEX_OPEN_AI_MODEL_GPT_5_3_CODEX` | 4 | **Deprecated.** |
| `CODEX_OPEN_AI_MODEL_GPT_5_3_CODEX_SPARK` | 5 | **Deprecated.** |
| `CODEX_OPEN_AI_MODEL_GPT_5_2` | 6 | **Deprecated.** |
| `CODEX_OPEN_AI_MODEL_GPT_5_6_SOL` | 7 | |
| `CODEX_OPEN_AI_MODEL_GPT_5_6_TERRA` | 8 | |
| `CODEX_OPEN_AI_MODEL_GPT_5_6_LUNA` | 9 | |
CodexReasoningEffort is the static allowlist of reasoning efforts supported
by the Codex app runtime.
| Value | Number | Description |
| ------------------------------------ | -----: | ----------- |
| `CODEX_REASONING_EFFORT_UNSPECIFIED` | 0 | |
| `CODEX_REASONING_EFFORT_LOW` | 1 | |
| `CODEX_REASONING_EFFORT_MEDIUM` | 2 | |
| `CODEX_REASONING_EFFORT_HIGH` | 3 | |
| `CODEX_REASONING_EFFORT_EXTRA_HIGH` | 4 | |
| `CODEX_REASONING_EFFORT_MAX` | 5 | |
| `CODEX_REASONING_EFFORT_ULTRA` | 6 | |
CodexServiceTier is the static allowlist of service tiers supported by the
Codex app runtime.
| Value | Number | Description |
| -------------------------------- | -----: | ----------- |
| `CODEX_SERVICE_TIER_UNSPECIFIED` | 0 | |
| `CODEX_SERVICE_TIER_FAST` | 1 | |