StartAgent

client.Agents.StartExecution(ctx, body) (*AgentStartExecutionResponse, error)

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:

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

ParametersExpand Collapse

body AgentStartExecutionParams

AgentID param.Field[string]Optional

formatuuid

Annotations param.Field[map[string, string]]Optional

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 param.Field[AgentCodeContext]Optional

Mode param.Field[AgentMode]Optional

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

Name param.Field[string]Optional

maxLength100

RunnerID param.Field[string]Optional

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.

formatuuid

SessionID param.Field[string]Optional

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

formatuuid

WorkflowActionID param.Field[string]Optional

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

formatuuid

ReturnsExpand Collapse

type AgentStartExecutionResponse struct{…}

AgentExecutionID stringOptional

formatuuid

StartAgent

package main

import (
  "context"
  "fmt"

  "github.com/gitpod-io/gitpod-sdk-go"
  "github.com/gitpod-io/gitpod-sdk-go/option"
)

func main() {
  client := gitpod.NewClient(
    option.WithBearerToken("My Bearer Token"),
  )
  response, err := client.Agents.StartExecution(context.TODO(), gitpod.AgentStartExecutionParams{
    AgentID: gitpod.F("b8a64cfa-43e2-4b9d-9fb3-07edc63f5971"),
    CodeContext: gitpod.F(gitpod.AgentCodeContextParam{
      ProjectID: gitpod.F("2d22e4eb-31da-467f-882c-27e21550992f"),
    }),
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", response.AgentExecutionID)
}

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

Returns Examples

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