Skip to content
Ona API Reference
Ona Docs
API Reference
Agents

SendToAgentExecution

agents.send_to_execution(AgentSendToExecutionParams**kwargs) -> object
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
agent_execution_id: Optional[str]
formatuuid
agent_message: Optional[AgentMessageParam]

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

payload: Optional[str]

Free-form payload of the message.

type: Optional[Type]
One of the following:
"TYPE_UNSPECIFIED"
"TYPE_UPDATE"
"TYPE_COMPLETE"
user_input: Optional[UserInputBlockParam]
id: Optional[str]
created_at: Optional[datetime]

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

formatdate-time
Deprecatedimage: Optional[Image]

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

data: Optional[str]

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

formatbyte
maxLength4194304
minLength1
mime_type: Optional[Literal["image/png", "image/jpeg"]]
One of the following:
"image/png"
"image/jpeg"
inputs: Optional[List[Input]]
image: Optional[InputImage]

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

data: Optional[str]

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

formatbyte
maxLength4194304
minLength1
mime_type: Optional[Literal["image/png", "image/jpeg"]]
One of the following:
"image/png"
"image/jpeg"
text: Optional[InputText]
content: Optional[str]
minLength1
Deprecatedtext: Optional[Text]
content: Optional[str]
minLength1
wake_event: Optional[WakeEventParam]

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[Environment]
environment_id: Optional[str]
failure_message: Optional[List[str]]
phase: Optional[str]

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

interest_id: Optional[str]

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

loop_retrigger: Optional[LoopRetrigger]
outputs: Optional[Dict[str, str]]
unmet_conditions: Optional[List[LoopRetriggerUnmetCondition]]
id: Optional[str]
description: Optional[str]
expression: Optional[str]
iteration: Optional[int]
formatint32
max_iterations: Optional[int]
formatint32
reason: Optional[str]
timer: Optional[Timer]
fired_at: Optional[datetime]

The actual time the timer was evaluated as expired.

formatdate-time
ReturnsExpand Collapse
object

SendToAgentExecution

import os
from gitpod import Gitpod

client = Gitpod(
    bearer_token=os.environ.get("GITPOD_API_KEY"),  # This is the default and can be omitted
)
response = client.agents.send_to_execution(
    agent_execution_id="6fa1a3c7-fbb7-49d1-ba56-1890dc7c4c35",
    user_input={
        "text": {
            "content": "Generate a report based on the latest logs."
        }
    },
)
print(response)
{}
Returns Examples
{}