> ## 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`](https://ona.com/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](https://ona.com/docs/api-reference.md#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=<your-token>

curl --request POST \
  --url "$ONA_HOST/api/gitpod.v1.AgentService/SendToAgentExecution" \
  --header "Authorization: Bearer $ONA_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "agentExecutionId": "<agent-execution-id>"
}'
```

```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="<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: "<agent-execution-id>",
  });
  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: "<agent-execution-id>",
	})
	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": "<agent-execution-id>"
}
```

## 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

> [accordion] AgentControlInput
>
> `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 | |

> [accordion] Compact
>
> `gitpod.v1.AgentControlInput.Compact`
>
> This message has no fields.

> [accordion] DeleteQueuedMessage
>
> `gitpod.v1.AgentControlInput.DeleteQueuedMessage`
>
> | Field | Type | Required | Description |
> | - | - | - | - |
> | `userInputId` | string | No | Constraints: `string.min_len=1`. |

> [accordion] Goal
>
> `gitpod.v1.AgentControlInput.Goal`
>
> | Field | Type | Required | Description |
> | - | - | - | - |
> | `pause` | Pause | No | |
> | `resume` | Resume | No | |
> | `complete` | Complete | No | |
> | `clear` | Clear | No | |
> | `set` | Set | No | |

> [accordion] MoveQueuedMessage
>
> `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. |

> [accordion] SteerQueuedMessage
>
> `gitpod.v1.AgentControlInput.SteerQueuedMessage`
>
> | Field | Type | Required | Description |
> | - | - | - | - |
> | `userInputId` | string | No | Constraints: `string.min_len=1`. |

> [accordion] AgentMessage
>
> 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. |

> [accordion] CodexSettings
>
> 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`. |

> [accordion] TurnOptions
>
> `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`. |

> [accordion] UserInputBlock
>
> `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. |

> [accordion] ImageInput
>
> 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. |

> [accordion] Input
>
> `gitpod.v1.UserInputBlock.Input`
>
> | Field | Type | Required | Description |
> | - | - | - | - |
> | `text` | TextInput | One of `input` | |
> | `image` | ImageInput | One of `input` | |

> [accordion] TextInput
>
> `gitpod.v1.UserInputBlock.TextInput`
>
> | Field | Type | Required | Description |
> | - | - | - | - |
> | `content` | string | No | Constraints: `string.min_len=1`. |

> [accordion] UserInputMetadata
>
> 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`. |

> [accordion] WakeEvent
>
> 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 | |

> [accordion] DevcontainerPhaseReached
>
> `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 | |

> [accordion] EnvironmentPhaseReached
>
> `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 | |

> [accordion] LoopRetrigger
>
> `gitpod.v1.WakeEvent.LoopRetrigger`
>
> | Field | Type | Required | Description |
> | - | - | - | - |
> | `unmetConditions` | array of UnmetCondition | No | |
> | `outputs` | map of string to string | No | |

> [accordion] TimerFired
>
> `gitpod.v1.WakeEvent.TimerFired`
>
> | Field | Type | Required | Description |
> | - | - | - | - |
> | `firedAt` | RFC 3339 timestamp | No | The actual time the timer was evaluated as expired. |

> [accordion] Role
>
> 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). |

> [accordion] Type
>
> | 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. |

> [accordion] AgentMode
>
> 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 |

> [accordion] CodexOpenAIModel
>
> 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 | |
> | `CODEX_OPEN_AI_MODEL_GPT_6_ASTRA` | 10 | |
> | `CODEX_OPEN_AI_MODEL_GPT_6_SOL` | 11 | |
> | `CODEX_OPEN_AI_MODEL_GPT_6_LUNA` | 12 | |
> | `CODEX_OPEN_AI_MODEL_GPT_6_1_SOL` | 13 | |

> [accordion] CodexReasoningEffort
>
> 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 | |

> [accordion] CodexServiceTier
>
> 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 | |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.