## StartAgent

**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:

  ```yaml
  agentId: "b8a64cfa-43e2-4b9d-9fb3-07edc63f5971"
  codeContext:
    projectId: "2d22e4eb-31da-467f-882c-27e21550992f"
  ```

### Body Parameters

- `agentId: optional string`

- `annotations: optional map[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: optional AgentCodeContext`

  - `contextUrl: optional object { environmentClassId, url }`

    - `environmentClassId: optional string`

    - `url: optional string`

  - `environmentId: optional string`

  - `projectId: optional string`

  - `pullRequest: optional object { id, author, draft, 6 more }`

    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 string`

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

    - `author: optional string`

      Author name as provided by the SCM system

    - `draft: optional boolean`

      Whether this is a draft pull request

    - `fromBranch: optional string`

      Source branch name (the branch being merged from)

    - `repository: optional object { cloneUrl, host, name, owner }`

      Repository information

      - `cloneUrl: optional string`

      - `host: optional string`

      - `name: optional string`

      - `owner: optional string`

    - `state: optional State`

      Current state of the pull request

      - `"STATE_UNSPECIFIED"`

      - `"STATE_OPEN"`

      - `"STATE_CLOSED"`

      - `"STATE_MERGED"`

    - `title: optional string`

      Pull request title

    - `toBranch: optional string`

      Target branch name (the branch being merged into)

    - `url: optional string`

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

- `mode: optional AgentMode`

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

  - `"AGENT_MODE_UNSPECIFIED"`

  - `"AGENT_MODE_EXECUTION"`

  - `"AGENT_MODE_PLANNING"`

  - `"AGENT_MODE_RALPH"`

  - `"AGENT_MODE_SPEC"`

- `name: optional string`

- `runnerId: optional 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.

- `sessionId: optional string`

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

- `workflowActionId: optional string`

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

### Returns

- `agentExecutionId: optional string`

### Example

```http
curl https://app.gitpod.io/api/gitpod.v1.AgentService/StartAgent \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $GITPOD_API_KEY" \
    -d '{}'
```

#### Response

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