에이전트 오케스트레이션

에이전트를 정의·연결·실행·관찰하는 오케스트레이션 레이어와 에이전트 라이프사이클, MCP & Skills를 설명합니다.

핵심 개념

• 에이전트(Agent) — 프롬프트 + 모델 + MCP 서버 목록 + Skills 집합으로 정의되는 실행 단위.
• 오케스트레이터(Orchestrator) — 에이전트를 생성·스케줄링·연결하는 루트 관리자.
• 계층성 — 에이전트는 하위 에이전트를 생성할 수 있고, 계층 깊이는 정책으로 관리합니다.
• 의존성 vs 격리 — 에이전트는 다른 에이전트의 출력을 입력으로 받거나, 완전히 독립적으로 실행할 수 있습니다.

구조

사용자 ──▶ Agent Dashboard
              │
              ▼
           Agent API ──▶ 데이터베이스
              │
              ▼
        Orchestrator Runtime
         ├──▶ Agent A
         │      ├──▶ Sub-Agent A.1
         │      └──▶ Sub-Agent A.2
         └──▶ Agent B ── (shared context) ── Agent A
              │
   Agent A ──┴──▶ MCP Servers · Skills

오케스트레이션 뷰는 노드-엣지 그래프로 에이전트 간 관계를 시각화합니다.

• 노드 — 에이전트, 오케스트레이터.
• 엣지 — 의존(데이터 흐름), 부모-자식(생성 관계), 구독(이벤트).

에이전트 라이프사이클

에이전트는 다음 상태를 따라 진행합니다.

Defined ──▶ Provisioned ──▶ Running ──▶ Done
   생성        바인딩         실행        성공 종료
                              │  │  ▲
                  Spawning ◀──┘  │  └──▶ Waiting (외부 이벤트 대기)
              (하위 에이전트)     │
                              Failed ──(재시도)──▶ Running

생성 주체

• 사용자 — 대시보드 UI에서 직접 정의합니다.
• 상위 에이전트 — 런타임에 하위 에이전트를 동적으로 생성합니다.
• 이벤트 트리거 — 알림 규칙이 자동으로 에이전트를 생성합니다(에러·크래시 자동 수정 파이프라인).

하위 에이전트 규칙

• 부모는 scope 축소 원칙으로 자식에게 권한을 부여합니다.
• 부모가 종료되면 자식도 취소됩니다(cascade). 설정으로 변경할 수 있습니다.
• 최대 깊이 기본값은 5이며, 조직별 정책으로 상한을 조정합니다.
• 자식의 결과는 부모 컨텍스트로 돌아오거나 별도 이벤트 스트림으로 방출됩니다.

격리 vs 의존

종료 조건

• 명시적 done 도구 호출.
• 상위로부터의 취소 시그널.
• 타임아웃.
• 오류 횟수 임계 초과.

MCP & Skills

에이전트의 능력은 두 축으로 구성됩니다. MCP 서버는 외부 시스템에 접근하는 인터페이스이고, Skills는 재사용 가능한 태스크 프로세스입니다. 둘은 독립적으로 진화합니다.

Skill은 여러 MCP를 조합해 하나의 태스크를 완성합니다.

Agent ──tool call──▶ MCP: GitHub / GitLab / Sophonz API
   │
   └──invoke──▶ Skill: error-triage / pr-create ──tool call──▶ MCP

MCP 서버 관리

• 리포지토리에 기본 프리셋이 제공되고, 시드 스크립트로 초기 등록됩니다.
• 사용자가 자체 MCP 서버를 추가할 수 있습니다(stdio, SSE, HTTP).
• 커뮤니티 Skill 마켓플레이스는 로드맵 항목입니다.

Skill 정의

• Skill은 프롬프트 템플릿 + 기본 MCP 목록 + 성공 기준으로 구성됩니다.
• 한 에이전트는 여러 Skill을 보유하고 런타임에 선택 실행합니다.
• Skill 간 조합은 상위 에이전트의 프롬프트에서 엮습니다.

관찰 가능성과 보안

• 에이전트 실행 자체가 트레이스로 기록되어, 같은 도구로 조회할 수 있습니다. 즉 에이전트도 관측 대상입니다.
• 모든 상태 전이가 이벤트로 방출되며, 액티비티 타임라인에서 조회합니다.
• LLM 토큰 사용량, MCP 호출, 생성된 자식 수가 트레이스 속성으로 기록됩니다.
• MCP 호출은 에이전트의 scope 내에서만 허용됩니다.
• 시크릿은 Bearer 토큰, *_TOKEN, *_SECRET, *_API_KEY 패턴에 대해 API 응답에서 마스킹되며, 원문은 저장소에만 보관되고 런타임 호출 시에만 사용됩니다.
• 민감 MCP(예: 프로덕션 배포)는 별도 승인 플로우가 필수입니다.

운영 모델

• SaaS — sophonz.com에서 관리형 오케스트레이터를 제공합니다.
• 온프레미스 — 로컬 LLM 어댑터와 연계해 고객 데이터를 외부로 내보내지 않습니다.

관련 문서

• AI Agent 개요
• 에러·크래시 자동 수정
• 커버리지·테스트 생성
• GitHub App 설정 · GitLab App 설정