> ## 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`](https://ona.com/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](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/StartAgent" \
  --header "Authorization: Bearer $ONA_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "agentId": "<agent-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.StartAgentRequest(
    agent_id="<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: "<agent-id>",
  });
  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: "<agent-id>",
	})
	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": "<agent-id>"
}
```

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

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

> [accordion] ContextURL
>
> `gitpod.v1.AgentCodeContext.ContextURL`
>
> | Field | Type | Required | Description |
> | - | - | - | - |
> | `url` | string | No | Constraints: `string.uri=true`. |
> | `environmentClassId` | string | No | Constraints: `string.uuid=true`. |

> [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] PullRequest
>
> 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. |

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

> [accordion] State
>
> Current state of the pull request
>
> | Value | Number | Description |
> | - | -: | - |
> | `STATE_UNSPECIFIED` | 0 | |
> | `STATE_OPEN` | 1 | |
> | `STATE_CLOSED` | 2 | |
> | `STATE_MERGED` | 3 | |


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