---
title: "StartAgent"
method: POST
path: "/gitpod.v1.AgentService/StartAgent"
tags: ["gitpod.v1.AgentService"]
---

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

## Request body

- GitpodV1StartAgentRequest — unresolved $ref

## Response `200`

Success

- GitpodV1StartAgentResponse
  - `agentExecutionId` string, uuid

## Other responses

- `default` — Error

## Changes

- **2026-07-30** `44d50c2ac284` — 4 info
  - added the new optional request property `codeContext/pullRequest/headSha`
  - added the new optional request property `codexSettings`
  - added the new optional request property `turnOptions`
  - added the new `AGENT_MODE_GOAL` enum value to the request property `mode`
- **2026-04-02** `dabc0ff98cd7` — 1 info
  - added the new optional request property `sessionId`
- **2026-02-11** `b97dcde84128` — 2 info
  - added the new optional request property `annotations`
  - added the new optional request property `runnerId`
- **2026-01-21** `2423c089f280` — 4 info
  - added the new optional request property `codeContext/pullRequest/draft`
  - added the new optional request property `codeContext/pullRequest/state`
  - added the new `AGENT_MODE_RALPH` enum value to the request property `mode`
  - added the new `AGENT_MODE_SPEC` enum value to the request property `mode`
- **2025-12-15** `d62ef4b9187c` — 4 info
  - added the new optional request property `codeContext/pullRequest`
  - added the new optional request property `mode`
  - added the new optional request property `name`
  - added the new optional request property `workflowActionId`

[Full history](https://skmtc.dev/gitpod-io/apis/gitpod-v1/changes/gitpod.v1.AgentService/StartAgent/post.md)

---

[API](https://skmtc.dev/gitpod-io/apis/gitpod-v1.md) · [All operations](https://skmtc.dev/gitpod-io/apis/gitpod-v1/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/gitpod-io/gitpod-v1/revisions/44d50c2ac284/schema)