StartAgent

client.agents.startExecution(, ?): AgentStartExecutionResponse { agentExecutionId }

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

body: AgentStartExecutionParams { agentId, annotations, codeContext, 6 more }

agentId?: string

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?: Record<string, string>

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”).

codeContext?: AgentCodeContext { contextUrl, environmentId, projectId, pullRequest }

contextUrl?: ContextURL { environmentClassId, url }

environmentClassId?: string

formatuuid

url?: string

formaturi

environmentId?: string

formatuuid

projectId?: string

formatuuid

pullRequest?: PullRequest | null

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?: string

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

author?: string

Author name as provided by the SCM system

draft?: boolean

Whether this is a draft pull request

fromBranch?: string

Source branch name (the branch being merged from)

repository?: Repository { cloneUrl, host, name, owner }

Repository information

cloneUrl?: string

host?: string

name?: string

owner?: string

state?: State

Current state of the pull request

One of the following:

"STATE_UNSPECIFIED"

"STATE_OPEN"

"STATE_CLOSED"

"STATE_MERGED"

title?: string

Pull request title

toBranch?: string

Target branch name (the branch being merged into)

url?: string

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

codexSettings?: CodexSettings { model, reasoningEffort, serviceTier }

codex_settings contains desired manual settings for the Codex app agent.

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"

mode?: 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?: string

maxLength100

runnerId?: string

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

sessionId?: string

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

formatuuid

workflowActionId?: string | null

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

AgentStartExecutionResponse { agentExecutionId }

agentExecutionId?: string

formatuuid

StartAgent

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.startExecution({
  agentId: 'b8a64cfa-43e2-4b9d-9fb3-07edc63f5971',
  codeContext: { projectId: '2d22e4eb-31da-467f-882c-27e21550992f' },
});

console.log(response.agentExecutionId);

{
  "agentExecutionId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
}

Returns Examples

{
  "agentExecutionId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
}