이 API를 사용하여 GitLab Duo Agent Platform에서 플로를 생성하고 관리합니다. 플로는 버그 수정, 코드 작성, 취약점 해결과 같은 개발 작업을 완료하기 위해 여러 AI 에이전트를 조합한 것입니다.

플로 트리거#

새 플로를 트리거하고 시작합니다.

사전 요구 사항:

• enforce_composite_identity_for_api_started_workflows 기능 플래그가 활성화되어 있고 start_workflow가 true 이면, 해당 플로에 복합 ID 서비스 계정이 있어야 합니다. 이 서비스 계정은 AI Catalog에서 플로에 구성된 계정이거나, 요청의 복합 ID 뒤에 있는 서비스 계정입니다. 그렇지 않으면 GitLab 이 403 Forbidden을 반환하고 플로를 시작하지 않습니다.

POST /ai/duo_workflows/workflows

지원되는 속성:

성공하면 201 Created와 다음 응답 속성을 반환합니다.

GitLab Duo Agent Platform을 사용하기 전에 사용자가 ID 확인을 완료해야 하는 경우, GitLab은 403 Forbidden과 함께 다음 message를 반환합니다.

{
  "message": "403 Forbidden - Identity verification is required to use GitLab Duo Agent Platform"
}

callback_hook_id가 설정되어 있고 다음 중 하나에 해당하면 GitLab은 400 Bad request를 반환합니다.

• 플로가 실행되는 프로젝트나 네임스페이스의 최상위 그룹에 duo_flow_callback_hooks 기능 플래그가 활성화되어 있지 않은 경우.
• 해당 ID가 플로가 실행되는 프로젝트나 네임스페이스, 또는 그 상위 그룹 중 하나에서 GitLab Duo 플로 콜백이 켜진 웹훅을 가리키지 않는 경우.

소비자 ID 조회#

ai_catalog_item_consumer_id를 사용하려면 먼저 GraphQL API로 AI Catalog에서 해당 ID를 조회해야 합니다. 해당 항목은 프로젝트에 이미 활성화되어 있어야 합니다.

query {
  aiCatalogConfiguredItems(projectId: "gid://gitlab/Project/<project_id>") {
    nodes {
      id
      item { name }
    }
  }
}

id 필드는 gid://gitlab/AiCatalogItemConsumer/<numeric_id> 형식의 전역 ID 입니다. 끝의 숫자 부분을 ai_catalog_item_consumer_id 값으로 사용합니다.

기본 제공 플로 유형을 사용하는 요청 예시:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --data '{
    "project_id": "5",
    "goal": "Fix the failing pipeline by correcting the syntax error in .gitlab-ci.yml",
    "workflow_definition": "developer/v1",
    "start_workflow": true
  }' \
  --url "https://gitlab.example.com/api/v4/ai/duo_workflows/workflows"

카탈로그에 구성된 플로를 사용하는 요청 예시:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --data '{
    "project_id": "5",
    "goal": "Fix the failing pipeline by correcting the syntax error in .gitlab-ci.yml",
    "ai_catalog_item_consumer_id": 12,
    "start_workflow": true
  }' \
  --url "https://gitlab.example.com/api/v4/ai/duo_workflows/workflows"

응답 예시:

{
  "id": 1,
  "web_url": "https://gitlab.example.com/group/project/-/automate/agent-sessions/1",
  "project_id": 5,
  "namespace_id": null,
  "agent_privileges": [1, 2, 3, 4, 5, 6],
  "agent_privileges_names": [
    "read_write_files",
    "read_only_gitlab",
    "read_write_gitlab",
    "run_commands",
    "use_git",
    "run_mcp_tools"
  ],
  "pre_approved_agent_privileges": [],
  "pre_approved_agent_privileges_names": [],
  "workflow_definition": "developer/v1",
  "status": "running",
  "allow_agent_to_request_user": true,
  "image": null,
  "environment": null,
  "ai_catalog_item_version_id": null,
  "workload": {
    "id": "abc-123",
    "message": "Workflow started"
  },
  "mcp_enabled": false,
  "gitlab_url": "https://gitlab.example.com"
}

플로 재시작#

실패했거나 중지된 플로를 같은 플로 파라미터로 새 플로를 시작하여 다시 시작합니다. 새 플로는 처음부터 실행됩니다. 원래 플로는 변경되지 않으며 failed 또는 stopped 상태로 유지됩니다.

상태가 failed 또는 stopped인 프로젝트 수준 플로만 재시작할 수 있습니다. 그 밖의 상태인 플로나 그룹 수준 플로를 재시작하면 403 Forbidden을 반환합니다. 재시작이 아직 진행 중인 상태에서 같은 플로를 다시 재시작하면 409 Conflict를 반환합니다.

POST /ai/duo_workflows/workflows/:workflow_id/restart

지원하는 속성:

성공하면 201 Created와 플로 트리거와 같은 응답 속성을 반환합니다. 응답은 새 플로를 설명하므로 id는 재시작한 플로가 아니라 새 플로의 ID입니다.

요청 예시:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/ai/duo_workflows/workflows/42/restart"

워크플로 트레이스를 JSONL로 가져오기#

워크플로 세션의 ui_chat_log 항목을 JSON Lines(JSONL) 형식으로 반환합니다. 각 줄은 ui_chat_log 배열의 항목 하나를 나타내는 유효한 JSON 객체입니다. 트레이스를 파싱하거나 jq 같은 도구로 전달할 때 이 엔드포인트를 사용합니다.

기본적으로 이 엔드포인트는 컨텍스트 압축 이전의 메시지를 포함하여 세션의 모든 스레드에 걸친 전체 대화를 반환합니다. 단일 스레드만 반환하려면 thread 속성을 사용합니다.

GET /ai/duo_workflows/workflows/:workflow_id/trace.jsonl

지원되는 속성:

성공하면 200 OK와 함께 다음을 반환합니다.

• Content-Type: application/x-ndjson
• Body: 한 줄에 JSON 객체 하나씩이며, 각 객체는 ui_chat_log 항목 하나를 나타냅니다. 워크플로에 체크포인트가 없거나 ui_chat_log 항목이 없으면 빈 본문을 반환합니다.

GitLab Duo Agent Platform을 사용하기 전에 사용자가 ID 확인을 완료해야 하는 경우, GitLab은 403 Forbidden과 함께 다음 message를 반환합니다.

{
  "message": "403 Forbidden - Identity verification is required to use GitLab Duo Agent Platform"
}

요청 예시:

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/ai/duo_workflows/workflows/1/trace.jsonl"

응답 예시(각 줄이 별도의 JSON 객체입니다):

{"status":"success","content":"Analyze the issue","message_type":"human"}
{"status":"success","content":"I'll start by reading the codebase.","message_type":"ai"}

출력을 jq로 전달하여 유형별로 항목을 필터링할 수 있습니다.

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/ai/duo_workflows/workflows/1/trace.jsonl" \
  | jq 'select(.message_type == "ai")'

모든 에이전트 권한 조회#

사용 가능한 모든 에이전트 권한을 ID, 이름, 설명, 기본 활성화 여부와 함께 조회합니다.

GET /ai/duo_workflows/workflows/agent_privileges

이 엔드포인트에는 지원되는 속성이 없습니다.

성공하면 200 OK와 다음 응답 속성을 반환합니다.

요청 예시:

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/ai/duo_workflows/workflows/agent_privileges"

응답 예시:

{
  "all_privileges": [
    {
      "id": 1,
      "name": "read_write_files",
      "description": "Allow local filesystem read/write access",
      "default_enabled": true
    },
    {
      "id": 2,
      "name": "read_only_gitlab",
      "description": "Allow read only access to GitLab APIs",
      "default_enabled": true
    },
    {
      "id": 3,
      "name": "read_write_gitlab",
      "description": "Allow write access to GitLab APIs",
      "default_enabled": true
    },
    {
      "id": 4,
      "name": "run_commands",
      "description": "Allow running any commands",
      "default_enabled": true
    },
    {
      "id": 5,
      "name": "use_git",
      "description": "Allow git commits, push and other git commands",
      "default_enabled": true
    },
    {
      "id": 6,
      "name": "run_mcp_tools",
      "description": "Allow running MCP tools",
      "default_enabled": true
    }
  ]
}