Skip to content
Ona API Reference
Ona Docs
API Reference
Agents

StartAgent

agents.start_execution(AgentStartExecutionParams**kwargs) -> AgentStartExecutionResponse
POST/gitpod.v1.AgentService/StartAgent

Starts (or triggers) an agent run using a provided agent.

Use this method to:

  • Launch an agent based on a known agent

Examples

  • Start an agent with a project ID:

    agentId: "b8a64cfa-43e2-4b9d-9fb3-07edc63f5971"
codeContext:
  projectId: "2d22e4eb-31da-467f-882c-27e21550992f"
ParametersExpand Collapse
agent_id: Optional[str]

agent_id identifies the agent to start. If omitted, the backend uses the configured default agent ID, or the Ona in-environment agent when no default is configured.

formatuuid
annotations: Optional[Dict[str, str]]

annotations are key-value pairs for tracking external context (e.g., integration session IDs, GitHub issue references). Keys should follow domain/name convention (e.g., “agent-client-session/id”).

code_context: Optional[AgentCodeContextParam]
context_url: Optional[ContextURL]
environment_class_id: Optional[str]
formatuuid
url: Optional[str]
formaturi
environment_id: Optional[str]
formatuuid
project_id: Optional[str]
formatuuid
pull_request: Optional[PullRequest]

Pull request context - optional metadata about the PR being worked on This is populated when the agent execution is triggered by a PR workflow or when explicitly provided through the browser extension

id: Optional[str]

Unique identifier from the source system (e.g., “123” for GitHub PR #123)

author: Optional[str]

Author name as provided by the SCM system

draft: Optional[bool]

Whether this is a draft pull request

from_branch: Optional[str]

Source branch name (the branch being merged from)

repository: Optional[PullRequestRepository]

Repository information

clone_url: Optional[str]
host: Optional[str]
name: Optional[str]
owner: Optional[str]
state: Optional[State]

Current state of the pull request

One of the following:
"STATE_UNSPECIFIED"
"STATE_OPEN"
"STATE_CLOSED"
"STATE_MERGED"
title: Optional[str]

Pull request title

to_branch: Optional[str]

Target branch name (the branch being merged into)

url: Optional[str]

Pull request URL (e.g., “https://github.com/owner/repo/pull/123”)

codex_settings: Optional[CodexSettingsParam]

codex_settings contains desired manual settings for the Codex app agent.

model: Optional[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"
reasoning_effort: Optional[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"
service_tier: Optional[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"
mode: Optional[AgentMode]

mode specifies the operational mode for this agent execution If not specified, defaults to AGENT_MODE_EXECUTION

One of the following:
"AGENT_MODE_UNSPECIFIED"
"AGENT_MODE_EXECUTION"
"AGENT_MODE_PLANNING"
"AGENT_MODE_RALPH"
"AGENT_MODE_SPEC"
name: Optional[str]
maxLength100
runner_id: Optional[str]

runner_id specifies a runner for this agent execution. When set, the agent execution is routed to this runner instead of the runner associated with the environment.

formatuuid
session_id: Optional[str]

session_id is the ID of the session this agent execution belongs to. If empty, a new session is created implicitly.

formatuuid
workflow_action_id: Optional[str]

workflow_action_id is an optional reference to the workflow execution action that created this agent execution. Used for tracking and event correlation.

formatuuid
ReturnsExpand Collapse
class AgentStartExecutionResponse: …
agent_execution_id: Optional[str]
formatuuid

StartAgent

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.start_execution(
    agent_id="b8a64cfa-43e2-4b9d-9fb3-07edc63f5971",
    code_context={
        "project_id": "2d22e4eb-31da-467f-882c-27e21550992f"
    },
)
print(response.agent_execution_id)
{
  "agentExecutionId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
}
Returns Examples
{
  "agentExecutionId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
}