이 가이드는 기초 에이전트를 다룹니다. 기초 플로우에 대한 내용은 기초 플로우 가이드를 참조하세요. 에이전트와 플로우의 차이점을 이해하려면 용어집을 참조하세요.

기초 에이전트는 GitLab이 생성하고 유지 관리하는 전문화된 에이전트로, 특정 사용 사례에 대해 더 정확한 응답을 제공합니다. 이 에이전트는 그룹을 포함하여 채팅 및 GitLab Duo 채팅을 사용할 수 있는 모든 곳에서 기본적으로 사용 가능하며, GitLab Duo Self-Hosted에서 지원됩니다.

기초 에이전트 생성#

기초 에이전트를 생성하는 두 가지 방법이 있습니다: AI Catalog 또는 GitLab Duo Workflow Service 사용. AI Catalog는 사용자 친화적인 인터페이스를 제공하며 선호되는 방법이지만, GitLab Duo Workflow Service에 정의를 작성하면 복잡한 경우에 더 많은 유연성이 있습니다.

AI Catalog 사용#

1. AI Catalog에서 에이전트를 생성하고 ID를 메모합니다. 에이전트가 공개로 설정되어 있는지 확인합니다. 예시: Planner Agent의 ID는 348입니다.

2. AI Catalog에서 생성된 에이전트는 SaaS에 접근할 수 없는 셀프 호스팅 설정에서 사용 가능하도록 GitLab Duo Workflow Service에 번들되어야 합니다. 이를 위해 GitLab Duo Workflow Service에 에이전트 ID를 추가하는 MR을 오픈하세요:

   # https://gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/ai-assist/-/blob/main/Dockerfile
   - RUN poetry run fetch-foundational-agents "https://gitlab.com" "$GITLAB_TOKEN" "348" \
   + RUN poetry run fetch-foundational-agents "https://gitlab.com" "$GITLAB_TOKEN" "duo_planner:348,<agent-reference>:<agent-catalog-id>" \
   

   위 명령은 테스트 목적으로 로컬에서도 실행할 수 있습니다. 에이전트 참조는 공백 없이 소문자여야 합니다(예: 'test_agent').

3. 에이전트를 선택 가능하게 만들려면 FoundationalChatAgentsDefinitions.rb에 추가합니다. Dockerfile에서 사용한 참조를 사용하세요:

   {
     id: 3,
     reference: '<agent-reference>',
     version: 'experimental',
     name: 'Test Agent',
     description: "An agent for testing"
   }
   

4. 사용자 대면 문서를 업데이트합니다.

GitLab Duo Workflow Service 사용#

1. /duo_workflow_service/agent_platform/v1/flows/configs/에 플로우 구성 파일을 생성합니다(GDK의 PATH-TO-YOUR-GDK/gdk/gitlab-ai-gateway 또는 ai-assist 저장소에 위치):

   파일: /duo_workflow_service/agent_platform/v1/flows/configs/foundational_pirate_agent.yml

   version: "v1"
   environment: chat-partial
   components:
     - name: "foundational_pirate_agent"
       type: AgentComponent
       prompt_id: "foundational_pirate_agent_prompt"
       inputs:
         - from: "context:goal"
           as: "goal"
         - from: "context:project_id"
           as: "project_id"
       toolset: []
       ui_log_events: []
   prompts:
     - name: Foundational Pirate Agent
       prompt_id: "foundational_pirate_agent_prompt"
       model:
         params:
           model_class_provider: anthropic
           max_tokens: 2_000
       prompt_template:
         system: |
           You are a seasoned pirate from the Golden Age of Piracy. You speak exclusively in pirate dialect, using nautical
           terms, pirate slang, and colorful seafaring expressions. Transform any input into authentic pirate speak while
           maintaining the original meaning. Use terms like 'ahoy', 'matey', 'ye', 'aye', 'landlubber', 'scallywag',
           'doubloons', 'plunder', etc. Add pirate exclamations like 'Arrr!', 'Shiver me timbers!', and 'Yo ho ho!' where
           appropriate. Refer to yourself in the first person as a pirate would.
         user: |
           {{goal}}
         placeholder: history
   routers: []
   flow:
     entry_point: "foundational_pirate_agent"
   

2. FoundationalChatAgentsDefinitions.rb에 에이전트 정의를 추가합니다:

   # frozen_string_literal: true
   
   module Ai
     module FoundationalChatAgentsDefinitions
       extend ActiveSupport::Concern
   
       ITEMS = [
         {
           id: 1,
           reference: 'chat',
           version: '',
           name: 'GitLab Duo Agent',
           description: "GitLab Duo is your general development assistant"
         },
         {
           id: 2,
           reference: 'foundational_pirate_agent',
           version: 'v1',
           name: 'Foundational Pirate Agent',
           description: "A most important agent that speaks like a pirate"
         }
       ].freeze
     end
   end
   

3. 사용자 대면 문서를 업데이트합니다.

팁:

1. 코드베이스에 추가하기 전에 AI Catalog를 사용하여 기초 에이전트를 테스트할 수 있습니다. 동일한 프롬프트와 동일한 도구로 AI Catalog에 새 비공개 에이전트를 생성하고 테스트 프로젝트에서 활성화합니다. 결과가 원하는 수준에 도달하면 GitLab Duo Workflow Service에 추가합니다.
2. GitLab Duo Workflow Service에 프롬프트를 추가하여 로컬 GDK에서 에이전트를 테스트할 수 있게 합니다.
3. AI Catalog를 사용하는 경우 FoundationalChatAgentsDefinitions.rb의 에이전트 version 필드는 experimental이어야 합니다. GitLab Duo Workflow Service에서 정의를 생성할 때 버전은 v1이어야 합니다.

채팅 에이전트 릴리스를 위한 기능 플래그 사용#

기능 플래그로 새 기초 에이전트의 릴리스를 제어합니다:

# ee/app/graphql/resolvers/ai/foundational_chat_agents_resolver.rb

  def resolve(*, project_id: nil, namespace_id: nil)
    project = GitlabSchema.find_by_gid(project_id)

    filtered_agents = []
    filtered_agents << 'foundational_pirate_agent' if Feature.disabled?(:my_feature_flag, project)
    # filtered_agents << 'foundational_pirate_agent' if Feature.disabled?(:my_feature_flag, current_user)

    ::Ai::FoundationalChatAgent
 .select {|agent| filtered_agents.exclude?(agent.reference) }
      .sort_by(&:id)
  end

이를 통해 기초 에이전트를 특정 티어에서 사용 가능하게 할 수도 있습니다.

범위 지정#

모든 에이전트가 모든 영역에서 유용한 것은 아닙니다. 예를 들어 일부 에이전트는 프로젝트에서 작동하고 다른 에이전트는 그룹에서 더 유용하거나 더 많은 기능을 갖습니다. 범위 지정은 지원되지 않습니다. 이슈 577395를 참조하세요.

트리거#

트리거는 기초 채팅 에이전트에 지원되지 않습니다. 그러나 AI Catalog에서 정의된 경우 사용자가 여전히 프로젝트에 추가할 수 있으며, 그 시점에서 트리거를 통해 사용할 수 있습니다.

버전 관리#

에이전트의 버전 관리는 아직 지원되지 않습니다. 에이전트를 변경하기 전에 이전 GitLab 버전에 대한 잠재적인 breaking changes를 고려하세요.

에이전트 프롬프트의 시크릿 보안 요구 사항#

기초 에이전트의 범위에 다음 중 하나가 포함되는 경우, 시스템 프롬프트에 반드시 시크릿 보안 지침을 포함해야 합니다:

• 파일 생성 또는 수정 (예: .gitlab-ci.yml, 구성 파일, 스크립트).

• CI/CD 파이프라인 구성 또는 변환.

• 자격 증명, API 키, 토큰 또는 연결 문자열 처리.

필수 프롬프트 지침#

다음 지침을 에이전트의 시스템 프롬프트에 그대로 추가하세요:

Never write literal secret values (API keys, tokens, passwords, connection strings, or any credentials)
into files or repository content. Always substitute secrets with CI/CD variable references
(for example, $API_KEY, $DB_PASSWORD, $DEPLOY_TOKEN). If a user provides a secret value directly,
do not echo it into any file — instead, recommend storing it in Settings > CI/CD > Variables and
reference it as a variable. When converting pipelines from other CI systems (for example, Jenkins,
GitHub Actions, CircleCI) that contain hardcoded secrets, replace those values with variable
references and flag to the user that the original pipeline contained hardcoded secrets.

체크리스트#

새 기초 에이전트를 머지하기 전에 다음을 확인하세요:

• 에이전트 프롬프트를 파일 쓰기, CI/CD 구성 또는 자격 증명 처리 범위에 대해 검토했습니다.

• 해당하는 경우: 시스템 프롬프트에 시크릿 보안 지침을 그대로 추가했습니다.

• 해당하지 않는 경우: MR 설명에 이유를 문서화했습니다.

로컬에서 기초 에이전트 개발#

AI Catalog로 생성된 에이전트의 경우 에이전트를 로컬에서 동기화해야 합니다. 이를 위해 로컬 AI Catalog 또는 GitLab.com AI Catalog에 에이전트를 생성하거나 가져오세요.

1. GitLab.com에서 에이전트 가져오기

   $GDK/gitlab-ai-gateway에서 다음 명령을 실행합니다:

   poetry run fetch-foundational-agents "http://gdk.test:3000 or https://gitlab.com" "<token-to-your-local-gdk>" \
    "<agent-reference>:<agent-id-in-local-catalog>" --flow-registry-version v1
   

   GitLab.com에서 duo_planner와 security_analyst_agent를 가져오는 예시:

   poetry run fetch-foundational-agents "https://gitlab.com" "<token-to-your-local-gdk>" \
    "duo_planner:348,security_analyst_agent:356" --flow-registry-version v1
   

   여기서:

   • 348은 GitLab.com의 GitLab Duo Planner 카탈로그 ID입니다
   • 356은 GitLab.com의 Security Analyst Agent 카탈로그 ID입니다

   구성을 가져온 후 서비스를 재시작합니다:

   gdk restart duo-workflow-service
   

2. 설정 확인

   기초 에이전트는 $GDK/gitlab-ai-gateway/duo_workflow_service/agent_platform/v1/flows/configs/에 .yml 파일로 저장됩니다.

   예를 들어 위의 poetry 명령을 사용하여 duo_planner와 security_analyst_agent를 가져왔다면 다음을 실행할 수 있습니다:

   ls duo_workflow_service/agent_platform/v1/flows/configs/ | grep -e "duo_planner" -e "security_analyst"
   

   다음 출력이 표시됩니다:

   duo_planner.yml
   security_analyst_agent.yml
   

   또는 GDK UI에서 확인하려면:

   1. FoundationalChatAgentsDefinitions.rb에 대한 변경 사항으로 이제 로컬 웹 채팅에서 기초 에이전트를 선택할 수 있습니다.
   2. 기초 에이전트를 보고 상호작용할 수 있는지 확인합니다
   3. 에이전트가 올바르게 응답하는지 확인하기 위해 메시지 전송 테스트

트러블슈팅#

• 에이전트가 채팅에 표시되지 않음: 구성 파일이 GitLab-ai-gateway 디렉토리에 생성되었고 서비스가 성공적으로 재시작되었는지 확인하세요
• 권한 오류: GitLab.com API 토큰에 API 범위가 있는지 확인하세요
• 플로우 레지스트리 버전 오류: --flow-registry-version v1을 사용하는지 확인하세요

기초 에이전트 동기화 파이프라인 테스트#

이 섹션은 로컬 GDK에서 기초 에이전트를 동기화하는 데 사용되는 파이프라인을 테스트하는 방법을 설명합니다. 기초 플로우 개발 또는 최신 플로우 가져오기는 위의 로컬에서 기초 에이전트 개발 섹션을 참조하세요.

사전 요구 사항#

• 실행 중인 GDK 인스턴스
• api 범위가 있는 GitLab API 토큰($GDK_PAT_WITH_API_SCOPE)
• GDK의 gitlab-ai-gateway 저장소에 대한 접근

1단계: 기존 기초 에이전트 확인#

먼저 모노리스에 정의되어 있지만 로컬 AI Catalog에 없는 기초 에이전트를 식별합니다:

1. 기초 에이전트 정의를 확인합니다:

   # GDK의 gitlab 디렉토리에서
   cat ee/lib/ai/foundational_chat_agents_definitions.rb
   

2. 로컬 AI Catalog에 있는 기존 에이전트 목록 조회:

   curl --header "Authorization: Bearer $GDK_PAT_WITH_API_SCOPE" \
     --header "Content-Type: application/json" \
     "http://gdk.test:3000/api/graphql" \
     --data '{"query": "query { aiCatalogItems { nodes { id name description } } }"}'
   

3. 결과를 비교하여 누락된 기초 에이전트를 식별합니다(일반적으로 duo_planner와 security_analyst_agent).

2단계: 누락된 기초 에이전트 생성#

기초 에이전트가 로컬 AI Catalog에 없는 경우 프로그래밍 방식으로 생성합니다:

1. 에이전트 호스팅을 위한 프로젝트 ID를 가져옵니다:

   bundle exec rake gitlab:duo:setup으로 duo 설정 스크립트를 실행했다면 ID 1000000인 프로젝트를 기초 에이전트 소유 프로젝트로 사용할 수 있습니다. 그렇지 않은 경우 GDK의 Premium 또는 Ultimate 프로젝트를 선택하고 해당 프로젝트 ID를 사용할 수 있습니다.

   # duo 설정 스크립트를 실행하지 않은 경우 프로젝트 ID 가져오기
   curl --header "Authorization: Bearer $GDK_PAT_WITH_API_SCOPE" \
     "http://gdk.test:3000/api/v4/projects" | jq '.[0].id'
   

2. Planner 에이전트 생성:

   curl --header "Authorization: Bearer $GDK_PAT_WITH_API_SCOPE" \
     --header "Content-Type: application/json" \
     "http://gdk.test:3000/api/graphql" \
     --data '{
       "query": "mutation { aiCatalogAgentCreate(input: { projectId: \"gid://gitlab/Project/YOUR_PROJECT_ID\", name: \"Planner\", description: \"Get help with planning and workflow management. Organize, edit, create, and track work more effectively in GitLab.\", public: true, systemPrompt: \"You are a helpful planning assistant that helps users organize, edit, create, and track work more effectively in GitLab.\" }) { item { id name } errors } }"
     }'
   

3. Security Analyst 에이전트 생성:

   curl --header "Authorization: Bearer $GDK_PAT_WITH_API_SCOPE" \
     --header "Content-Type: application/json" \
     "http://gdk.test:3000/api/graphql" \
     --data '{
       "query": "mutation { aiCatalogAgentCreate(input: { projectId: \"gid://gitlab/Project/YOUR_PROJECT_ID\", name: \"Security Analyst\", description: \"Automate vulnerability management and security workflows. The Security Analyst Agent acts as an AI team member that can autonomously analyze, triage, and remediate security vulnerabilities.\", public: true, systemPrompt: \"You are a security analyst AI that helps with vulnerability management and security workflows. You can analyze, triage, and help remediate security vulnerabilities.\" }) { item { id name } errors } }"
     }'
   

   YOUR_PROJECT_ID를 1단계의 실제 프로젝트 ID로 교체하세요.

3단계: 로컬 에이전트 ID 가져오기#

에이전트를 생성한 후 해당 로컬 카탈로그 ID를 가져옵니다:

# Planner 에이전트 ID 가져오기
curl --header "Authorization: Bearer $GDK_PAT_WITH_API_SCOPE" \
  --header "Content-Type: application/json" \
  "http://gdk.test:3000/api/graphql" \
  --data '{"query": "query { aiCatalogItems(search: \"Planner\") { nodes { id name } } }"}'

# Security Analyst 에이전트 ID 가져오기
curl --header "Authorization: Bearer $GDK_PAT_WITH_API_SCOPE" \
  --header "Content-Type: application/json" \
  "http://gdk.test:3000/api/graphql" \
  --data '{"query": "query { aiCatalogItems(search: \"Security Analyst\") { nodes { id name } } }"}'

응답에서 숫자 ID를 메모합니다(예: 10 및 11).

4단계: 기초 에이전트 구성 가져오기#

gitlab-ai-gateway 디렉토리에서 로컬 ID를 사용하여 에이전트 구성을 가져옵니다:

# v1 플로우 레지스트리(권장)
poetry run fetch-foundational-agents "http://gdk.test:3000" "$GDK_PAT_WITH_API_SCOPE" \
  "duo_planner:10,security_analyst_agent:11" \
  --flow-registry-version v1

# 실험적 플로우 레지스트리(대안)
poetry run fetch-foundational-agents "http://gdk.test:3000" "$GDK_PAT_WITH_API_SCOPE" \
  "duo_planner:10,security_analyst_agent:11" \
  --flow-registry-version experimental \
  --output-path duo_workflow_service/agent_platform/experimental/flows/configs

10과 11을 3단계의 실제 에이전트 ID로 교체하세요.

5단계: GitLab Duo Workflow Service 재시작#

gdk restart duo-workflow-service

6단계: 설정 확인#

FoundationalChatAgentsDefinitions.rb의 변경 사항과 가져온 구성을 통해 이제 로컬 웹 채팅에서 기초 에이전트를 선택할 수 있습니다.

트러블슈팅#

• 누락된 에이전트: 이 단계를 따른 후에도 에이전트가 채팅에 표시되지 않으면 다음을 확인하세요:

  • 에이전트가 로컬 AI Catalog에 존재하는지 확인(3단계의 GraphQL 쿼리로 확인)
  • fetch-foundational-agents 실행 후 플로우 구성 파일이 올바른 디렉토리에 생성되었는지 확인
  • GitLab Duo Workflow Service가 성공적으로 재시작되었는지 확인

• 플로우 레지스트리 버전: 프로덕션과 유사한 동작에는 v1, 새 기능 테스트에는 experimental 사용

• 권한 오류: API 토큰에 api 범위와 충분한 프로젝트 권한이 있는지 확인

• GraphQL 오류: GraphQL 내성을 사용하여 정확한 뮤테이션 파라미터 확인:

  curl --header "Authorization: Bearer $GDK_PAT_WITH_API_SCOPE" \
    --header "Content-Type: application/json" \
    "http://gdk.test:3000/api/graphql" \
    --data '{"query": "query { __type(name: \"AiCatalogAgentCreatePayload\") { fields { name type { name } } } }"}'
  

아키텍처 설계#

기초 채팅 에이전트는 GitLab이 개발하며 모든 GitLab 배포(GitLab.com, Self-Managed, Dedicated)에서 사용 가능해야 합니다.

기초 에이전트가 사용 가능하게 되는 아키텍처는 런타임에 AI Catalog에 연결하여 정의를 가져오는 것을 피하고 GitLab 엔지니어링 팀이 릴리스 시점에 대한 완전한 제어를 할 수 있게 합니다.

이 설계는 기초 플로우를 지원하도록 확장될 수도 있습니다.

모노리스에서의 기초 에이전트#

모노리스에서 기초 에이전트를 정의하는 것은 두 가지 목적을 제공합니다: 이전 버전 호환성 지원과 릴리스 제어.

FoundationalChatAgentsDefinitions 모듈은 GitLab 인스턴스 버전을 기반으로 에이전트 버전 관리를 합니다. 이전 GitLab 버전에 영향을 미치는 방식은 프롬프트 버전 관리와 유사합니다.

또한 FoundationalChatAgentsResolver에서 팀은 다음과 같은 상황에서 기초 채팅 에이전트를 사용할 수 있는 조건을 선택할 수 있습니다:

• 사용자가 Ultimate를 가지고 있는지
• 기능 플래그가 활성화되어 있는지
• 에이전트가 SaaS 전용인지

AI Catalog 또는 Duo Workflow Service에만 의존한다면 이러한 유연성은 불가능할 것입니다

버전 해결#

에이전트 버전은 FoundationalChatAgentsDefinitions.rb의 version 필드를 기반으로 해결되며, 이는 GitLab Duo Workflow Service의 폴더(예: v1, experimental)에 매핑됩니다.

향후에는 시맨틱 버전 관리를 기반으로 버전 해결이 이루어질 것입니다. 이를 통해 다음이 가능해집니다:

• 패치 및 마이너 업데이트(버그 수정, 성능 개선, 프롬프트 개선)를 GitLab 인스턴스 업데이트 없이 기존 GitLab 버전에 제공
• 주요 버전 릴리스(새 도구, API 변경, 스키마 수정 등 GitLab 신기능이 필요한 breaking changes)를 호환 가능한 GitLab 버전에만 제공

이 접근 방식은 이전 버전 호환성을 보장하면서 기초 에이전트의 지속적인 개선을 가능하게 합니다.

GitLab Duo Workflow Service에 번들링#

에이전트를 GitLab Duo Workflow Service에 번들링하면 AI Catalog에서 정의된 에이전트가 셀프 호스팅 설정을 포함한 모든 배포에서 사용 가능해집니다. 시맨틱 버전 관리 지원으로, 각 주요 릴리스의 최신 버전이 번들되며, 각 기초 에이전트의 특정 고정 버전도 함께 번들됩니다.

이에 대한 대안은 YAML 정의 자체를 GitLab 모노리스의 일부로 제공하는 것이지만, 이는 클라우드 연결된 셀프 매니지드 인스턴스에 신속하게 수정을 제공하지 못하는 단점이 있습니다.

결국 AI Catalog에 레이블이 구현된다면, 팀이 Dockerfile에 항목을 추가할 필요 없이 올바른 레이블로 버전을 가져올 수 있을 것입니다.

생성 플로우#

%%{init: {"sequence": {"actorMargin": 50}}}%%
sequenceDiagram
    accTitle: Foundational agent creation flow
    accDescr: Sequence diagram showing the process of creating a foundational agent from AI Catalog through to GitLab monolith
    participant Team
    participant AI Catalog
    participant DWS Repo as DWS Repository
    participant CI
    participant Monolith
Team->>AI Catalog: Create foundational agent
Team->>DWS Repo: Add agent ID to Dockerfile
DWS Repo->>CI: Trigger build
CI->>AI Catalog: Pull agent definitions
AI Catalog->>CI: Returns all required versions
CI->>CI: Store definitions in DWS image
CI->>CI: Ships images with definitions
Team-&gt;&gt;Monolith: Add agent to FoundationalChatAgentsDefinitions.rb</code></pre></details></div>

사용 플로우#
Mermaid 다이어그램 (14줄)
소스 코드 보기
%%{init: {"sequence": {"actorMargin": 50}}}%%
sequenceDiagram
    accTitle: Foundational agent usage flow
    accDescr: Sequence diagram showing how users interact with foundational agents through GitLab monolith and Duo Workflow Service
    participant User
    participant Monolith
    participant DWS as GitLab Duo Workflow Service
User-&gt;&gt;Monolith: Request to foundational agent
Monolith-&gt;&gt;DWS: Request specific agent version
DWS-&gt;&gt;DWS: Resolve agent version
DWS-&gt;&gt;DWS: Process request
DWS-&gt;&gt;Monolith: Return response
Monolith-&gt;&gt;User: Return response</code></pre></details></div>

실행 플로우는 사용자가 로컬 모노리스, GitLab SaaS, 클라우드 연결 DWS 또는 DWS 로컬 설치를 사용하든 동일합니다.

# ee/app/graphql/resolvers/ai/foundational_chat_agents_resolver.rb

  def resolve(*, project_id: nil, namespace_id: nil)
    project = GitlabSchema.find_by_gid(project_id)

    filtered_agents = []
    filtered_agents << 'foundational_pirate_agent' if Feature.disabled?(:my_feature_flag, project)
    # filtered_agents << 'foundational_pirate_agent' if Feature.disabled?(:my_feature_flag, current_user)

    ::Ai::FoundationalChatAgent
 .select {|agent| filtered_agents.exclude?(agent.reference) }
      .sort_by(&:id)
  end

Never write literal secret values (API keys, tokens, passwords, connection strings, or any credentials)
into files or repository content. Always substitute secrets with CI/CD variable references
(for example, $API_KEY, $DB_PASSWORD, $DEPLOY_TOKEN). If a user provides a secret value directly,
do not echo it into any file — instead, recommend storing it in Settings > CI/CD > Variables and
reference it as a variable. When converting pipelines from other CI systems (for example, Jenkins,
GitHub Actions, CircleCI) that contain hardcoded secrets, replace those values with variable
references and flag to the user that the original pipeline contained hardcoded secrets.

# Planner 에이전트 ID 가져오기
curl --header "Authorization: Bearer $GDK_PAT_WITH_API_SCOPE" \
  --header "Content-Type: application/json" \
  "http://gdk.test:3000/api/graphql" \
  --data '{"query": "query { aiCatalogItems(search: \"Planner\") { nodes { id name } } }"}'

# Security Analyst 에이전트 ID 가져오기
curl --header "Authorization: Bearer $GDK_PAT_WITH_API_SCOPE" \
  --header "Content-Type: application/json" \
  "http://gdk.test:3000/api/graphql" \
  --data '{"query": "query { aiCatalogItems(search: \"Security Analyst\") { nodes { id name } } }"}'

# v1 플로우 레지스트리(권장)
poetry run fetch-foundational-agents "http://gdk.test:3000" "$GDK_PAT_WITH_API_SCOPE" \
  "duo_planner:10,security_analyst_agent:11" \
  --flow-registry-version v1

# 실험적 플로우 레지스트리(대안)
poetry run fetch-foundational-agents "http://gdk.test:3000" "$GDK_PAT_WITH_API_SCOPE" \
  "duo_planner:10,security_analyst_agent:11" \
  --flow-registry-version experimental \
  --output-path duo_workflow_service/agent_platform/experimental/flows/configs

gdk restart duo-workflow-service

%%{init: {"sequence": {"actorMargin": 50}}}%%
sequenceDiagram
    accTitle: Foundational agent creation flow
    accDescr: Sequence diagram showing the process of creating a foundational agent from AI Catalog through to GitLab monolith
    participant Team
    participant AI Catalog
    participant DWS Repo as DWS Repository
    participant CI
    participant Monolith
Team->>AI Catalog: Create foundational agent
Team->>DWS Repo: Add agent ID to Dockerfile
DWS Repo->>CI: Trigger build
CI->>AI Catalog: Pull agent definitions
AI Catalog->>CI: Returns all required versions
CI->>CI: Store definitions in DWS image
CI->>CI: Ships images with definitions
Team-&gt;&gt;Monolith: Add agent to FoundationalChatAgentsDefinitions.rb</code></pre></details></div>

사용 플로우#
Mermaid 다이어그램 (14줄)
소스 코드 보기
%%{init: {"sequence": {"actorMargin": 50}}}%%
sequenceDiagram
    accTitle: Foundational agent usage flow
    accDescr: Sequence diagram showing how users interact with foundational agents through GitLab monolith and Duo Workflow Service
    participant User
    participant Monolith
    participant DWS as GitLab Duo Workflow Service
User-&gt;&gt;Monolith: Request to foundational agent
Monolith-&gt;&gt;DWS: Request specific agent version
DWS-&gt;&gt;DWS: Resolve agent version
DWS-&gt;&gt;DWS: Process request
DWS-&gt;&gt;Monolith: Return response
Monolith-&gt;&gt;User: Return response</code></pre></details></div>

실행 플로우는 사용자가 로컬 모노리스, GitLab SaaS, 클라우드 연결 DWS 또는 DWS 로컬 설치를 사용하든 동일합니다.