## StartAgent

`client.agents.startExecution(AgentStartExecutionParamsbody, RequestOptionsoptions?): AgentStartExecutionResponse`

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

### Parameters

- `body: AgentStartExecutionParams`

  - `agentId?: string`

  - `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?: ContextURL`

      - `environmentClassId?: string`

      - `url?: string`

    - `environmentId?: string`

    - `projectId?: string`

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

        Repository information

        - `cloneUrl?: string`

        - `host?: string`

        - `name?: string`

        - `owner?: string`

      - `state?: State`

        Current state of the pull request

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

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

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

  - `sessionId?: string`

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

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

### Returns

- `AgentStartExecutionResponse`

  - `agentExecutionId?: string`

### Example

```typescript
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);
```

#### Response

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