> ## 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. # Start Agent > Starts (or triggers) an agent run using a provided agent. `Unary` ยท [`Agents`](/docs/api-reference/generated/agent/overview) 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: ```yaml theme={null} agentId: "b8a64cfa-43e2-4b9d-9fb3-07edc63f5971" codeContext: projectId: "2d22e4eb-31da-467f-882c-27e21550992f" ``` ## Endpoint ```text theme={null} POST /api/gitpod.v1.AgentService/StartAgent ``` 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/StartAgent" \ --header "Authorization: Bearer $ONA_API_KEY" \ --header "Content-Type: application/json" \ --data '{ "agentId": "" }' ``` ```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.StartAgentRequest( agent_id="", ) response = ona.services.agent.start_agent(request) print(response) ``` ```typescript TypeScript theme={null} import { create } from "@bufbuild/protobuf"; import { createClientFromEnv } from "@gitpod/sdk"; import { StartAgentRequestSchema } from "@gitpod/sdk/gitpod/v1/agent_pb"; async function main() { const ona = createClientFromEnv(); const request = create(StartAgentRequestSchema, { agentId: "", }); const response = await ona.services.agent.startAgent(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.StartAgentRequest{ AgentId: "", }) response, err := ona.Services.Agent.StartAgent(context.Background(), request) if err != nil { log.Fatal(err) } fmt.Println(response.Msg) } ``` ```json Request body theme={null} { "agentId": "" } ``` ## Request `gitpod.v1.StartAgentRequest` | Field | Type | Required | Description | | ------------------ | ------------------------------------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `agentId` | string | No | 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. Constraints: `ignore=1, string.uuid=true`. | | `codeContext` | [AgentCodeContext](#type-gitpod-v1-agent-code-context) | No | | | `name` | string | No | Constraints: `string.max_len=100`. | | `workflowActionId` | string | No | workflow\_action\_id is an optional reference to the workflow execution action that created this agent execution. Used for tracking and event correlation. Constraints: `string.uuid=true`. | | `mode` | [AgentMode](#enum-gitpod-v1-agent-mode) | No | mode specifies the operational mode for this agent execution If not specified, defaults to AGENT\_MODE\_EXECUTION | | `runnerId` | string | No | 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. Constraints: `ignore=1, string.uuid=true`. | | `annotations` | map of string to string | No | 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"). | | `sessionId` | string | No | session\_id is the ID of the session this agent execution belongs to. If empty, a new session is created implicitly. Constraints: `ignore=1, string.uuid=true`. | | `codexSettings` | [CodexSettings](#type-gitpod-v1-codex-settings) | No | codex\_settings contains desired manual settings for the Codex app agent. | | `turnOptions` | [TurnOptions](#type-gitpod-v1-turn-options) | No | turn\_options contains options for the initial turn. It is not persisted as durable execution state. | ## Response `gitpod.v1.StartAgentResponse` | Field | Type | Required | Description | | ------------------ | ------ | -------- | -------------------------------- | | `agentExecutionId` | string | No | Constraints: `string.uuid=true`. | ## Related types `gitpod.v1.AgentCodeContext` | Field | Type | Required | Description | | --------------- | ------------------------------------------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `projectId` | string | No | Constraints: `string.uuid=true`. | | `environmentId` | string | No | Constraints: `string.uuid=true`. | | `contextUrl` | [ContextURL](#type-gitpod-v1-agent-code-context-context-url) | No | | | `pullRequest` | [PullRequest](#type-gitpod-v1-pull-request) | No | 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 | `gitpod.v1.AgentCodeContext.ContextURL` | Field | Type | Required | Description | | -------------------- | ------ | -------- | -------------------------------- | | `url` | string | No | Constraints: `string.uri=true`. | | `environmentClassId` | string | No | Constraints: `string.uuid=true`. | 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`. | PullRequest represents pull request metadata from source control systems. This message is used across workflow triggers, executions, and agent contexts to maintain consistent PR information throughout the system. `gitpod.v1.PullRequest` | Field | Type | Required | Description | | ------------ | ------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | No | Unique identifier from the source system (e.g., "123" for GitHub PR #123) | | `title` | string | No | Pull request title | | `fromBranch` | string | No | Source branch name (the branch being merged from) | | `toBranch` | string | No | Target branch name (the branch being merged into) | | `url` | string | No | Pull request URL (e.g., "[https://github.com/owner/repo/pull/123](https://github.com/owner/repo/pull/123)") | | `author` | string | No | Author name as provided by the SCM system | | `repository` | Repository | No | | | `draft` | boolean | No | Whether this is a draft pull request | | `state` | [State](#enum-gitpod-v1-pull-request-state) | No | | | `headSha` | string | No | Current revision identity for the PR head commit. Used internally for workflow execution deduplication and excluded from customer SDKs. | `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`. | 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 | | Current state of the pull request | Value | Number | Description | | ------------------- | -----: | ----------- | | `STATE_UNSPECIFIED` | 0 | | | `STATE_OPEN` | 1 | | | `STATE_CLOSED` | 2 | | | `STATE_MERGED` | 3 | |