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

플로우 트리거#

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

POST /ai/duo_workflows/workflows

지원되는 속성:

성공 시 201 Created 및 다음 응답 속성을 반환합니다:

소비자 ID 조회#

ai_catalog_item_consumer_id를 사용하기 전에 GraphQL API를 사용하여 AI 카탈로그에서 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,
  "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"
}

플로우 콜백 엔드포인트 등록#

플로우 수명 주기 이벤트(flow.started, flow.completed, flow.failed)를 수신하는 HTTPS 엔드포인트를 등록합니다. 플로우를 트리거할 때 반환된 id를 callback_hook_id 속성으로 참조하면 상태를 폴링하는 대신 수명 주기 알림을 받을 수 있습니다.

URL과 시크릿은 저장 시 암호화되며, 등록 후에는 API가 절대 반환하지 않습니다.

사전 요구 사항:

• 조직에 대한 Owner 역할이 있어야 합니다.

POST /ai/duo_workflows/flow_callbacks

지원되는 속성:

성공 시 201 Created 및 다음 응답 속성을 반환합니다:

요청 예시:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --data '{
    "url": "https://autoflow.example.com/duo/callbacks",
    "name": "AutoFlow",
    "signing_token": "whsec_<base64_encoded_32_byte_secret>"
  }' \
  --url "https://gitlab.example.com/api/v4/ai/duo_workflows/flow_callbacks"

응답 예시:

{
  "id": 1,
  "url": "https://autoflow.example.com/duo/callbacks",
  "name": "AutoFlow",
  "signing_token_set": true,
  "token_set": false,
  "created_at": "2026-07-22T11:37:00.000Z"
}

플로우 콜백 엔드포인트 나열#

조직에 등록된 플로우 콜백 엔드포인트를 나열합니다. 시크릿은 반환되지 않습니다.

사전 요구 사항:

• 조직에 대한 Owner 역할이 있어야 합니다.

GET /ai/duo_workflows/flow_callbacks

page 및 per_page 페이지네이션 파라미터를 사용하여 결과의 페이지네이션을 제어합니다.

성공 시 200 OK 및 플로우 콜백 엔드포인트 객체의 배열을 반환합니다.

요청 예시:

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

플로우 콜백 엔드포인트 가져오기#

등록된 플로우 콜백 엔드포인트 하나를 반환합니다. 시크릿은 반환되지 않습니다.

사전 요구 사항:

• 조직에 대한 Owner 역할이 있어야 합니다.

GET /ai/duo_workflows/flow_callbacks/:id

지원되는 속성:

성공 시 200 OK 및 플로우 콜백 엔드포인트 객체를 반환합니다.

요청 예시:

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

플로우 콜백 엔드포인트 삭제#

등록된 플로우 콜백 엔드포인트를 삭제하여 더 이상 전달을 수신하지 않도록 합니다.

사전 요구 사항:

• 조직에 대한 Owner 역할이 있어야 합니다.

DELETE /ai/duo_workflows/flow_callbacks/:id

지원되는 속성:

성공 시 204 No Content를 반환합니다.

요청 예시:

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

워크플로 트레이스를 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: 각 줄이 ui_chat_log 항목을 나타내는 JSON 객체 하나씩. 워크플로에 체크포인트가 없거나 ui_chat_log 항목이 없으면 빈 본문을 반환합니다.

요청 예시:

curl --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 --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 --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
    }
  ]
}