## StartAgent

`agents.start_execution(AgentStartExecutionParams**kwargs)  -> 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

- `agent_id: Optional[str]`

- `annotations: Optional[Dict[str, str]]`

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

- `code_context: Optional[AgentCodeContextParam]`

  - `context_url: Optional[ContextURL]`

    - `environment_class_id: Optional[str]`

    - `url: Optional[str]`

  - `environment_id: Optional[str]`

  - `project_id: Optional[str]`

  - `pull_request: Optional[PullRequest]`

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

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

    - `author: Optional[str]`

      Author name as provided by the SCM system

    - `draft: Optional[bool]`

      Whether this is a draft pull request

    - `from_branch: Optional[str]`

      Source branch name (the branch being merged from)

    - `repository: Optional[PullRequestRepository]`

      Repository information

      - `clone_url: Optional[str]`

      - `host: Optional[str]`

      - `name: Optional[str]`

      - `owner: Optional[str]`

    - `state: Optional[State]`

      Current state of the pull request

      - `"STATE_UNSPECIFIED"`

      - `"STATE_OPEN"`

      - `"STATE_CLOSED"`

      - `"STATE_MERGED"`

    - `title: Optional[str]`

      Pull request title

    - `to_branch: Optional[str]`

      Target branch name (the branch being merged into)

    - `url: Optional[str]`

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

- `runner_id: Optional[str]`

  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.

- `session_id: Optional[str]`

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

- `workflow_action_id: Optional[str]`

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

### Returns

- `class AgentStartExecutionResponse: …`

  - `agent_execution_id: Optional[str]`

### Example

```python
import os
from gitpod import Gitpod

client = Gitpod(
    bearer_token=os.environ.get("GITPOD_API_KEY"),  # This is the default and can be omitted
)
response = client.agents.start_execution(
    agent_id="b8a64cfa-43e2-4b9d-9fb3-07edc63f5971",
    code_context={
        "project_id": "2d22e4eb-31da-467f-882c-27e21550992f"
    },
)
print(response.agent_execution_id)
```

#### Response

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