이 문서는 제가 구축하고 있는 에이전트 오케스트레이션 (agent-orchestration) 라이브러리의 아키텍처를 다루는 시리즈 문서 중 두 번째입니다. 이전 문서는 에이전트가 실행되는 환경에 관한 것이었습니다. 이번에는 실제로 라이브러리를 선언하고 사용하는 방법에 관한 것입니다.

저는 에이전트를 쉽게 선언할 수 있는 무언가를 만들고 싶었습니다. 대부분의 라이브러리가 이를 달성하는 방식은 보통 고정된 설정(fixed configuration)을 가진 스레드(thread)로 만드는 것입니다. 그러면 설정할 것이 거의 없기 때문에 하나를 생성(spawning)하는 것이 매우 간단해집니디.

저는 각 에이전트가 자신만의 런타임 (runtime), 워크스페이스 (workspace), 하네스 (harness), 그리고 툴체인 (toolchain)을 가진 독립적인 엔티티 (entity)가 되기를 원했습니다. 여기에는 분명 비용이 따릅니다. 만약 모든 에이전트가 모든 축(axis)에서 서로 다를 수 있다면, 모든 에이전트가 자신에 대한 모든 것을 명시해야 하므로 플릿 (fleet, 에이전트 군단)을 선언하고 운영하는 것이 매우 지루해질 것입니다.

이전 포스트에서 설명한 이유로 인해 각 에이전트는 여전히 자신만의 격리된 워크스페이스 (workspace), 아티팩트 (artifacts), 그리고 시크릿 (secrets)을 가지고 있다는 점에 유의하십시오. 이번 내용은 이들을 어떻게 선언하고 구동하는지에 관한 것입니다.

제가 고안한 해결책은 다음과 같습니다.

위치
모든 것은 레포지토리 루트 (repo root)의 .agents 아래에 위치합니다. 설정 또한 이전의 아티팩트 (artifacts), 시크릿 (secrets), 워크스페이스 (workspaces)와 함께 agents.yaml 파일로 그곳에 위치합니다.
<repo-root>/ .artifacts/ agents/ common/ .secrets/ agents/ common/ .workspaces/ agents.yaml
여기서 제가 중요하게 생각하는 점은 전체 플릿 (fleet)이 제가 열어서 읽을 수 있는 디렉토리라는 것입니다. 설정과 상태는 레포지토리에 있으며, 아마도 git에 포함될 것입니다.

에이전트 선언하기
설정은 두 부분으로 구성됩니다: 모든 에이전트가 상속받는 기본값 (defaults), 그리고 차이가 나는 축만 재정의(override)하는 에이전트별 항목 (per-agent entries)입니다.

defaults: harness: claude workspace: environment: filesystem mode: worktree agents: atlas: harness: codex runtime: docker toolchain: nodepy workspace: mode: clone agent2: harness: kimi agent3: harness: codex agent4: null agent5: null agent6: null

각 에이전트는 defaults에서 모든 것을 상속받고 필요한 것만 변경합니다. atlas는 다른 harness, runtime, 그리고 workspace를 실행합니다.

agent2는 harness만 교체합니다. agent4부터 agent6까지는 null이므로, 기본값을 그대로 사용합니다. 어떤 에이전트든 실제로 차이가 나는 부분만 작성함으로써 어떤 축(axis)이라도 재정의(override)할 수 있습니다.

저는 JSON 대신 yaml을 선택했습니다. 왜냐하면 이 파일은 플릿(fleet)을 실행하는 동안 제가 직접 수동으로 편집할 수도 있는 파일이기 때문입니다. 따라서 직렬화 형식(serialization format)이 아닌, 읽기와 편집에 최적화되기를 원했습니다.

실행하기 (Driving them)
에이전트를 시작하려면 다음과 같이 수행합니다:

agents init # (선택 사항) 각 에이전트를 위한 디렉토리를 자동으로 생성합니다
agents provision atlas # 워크스페이스(workspace)를 생성합니다
agents start atlas # 실제 환경(Docker 컨테이너와 같은)을 시작합니다

init은 설정을 구성하고, provision은 에이전트의 환경을 구축하며, start는 이를 실행합니다.

환경이 시작되면 다음과 같이 연결(attach)할 수 있습니다:

agents attach atlas --via tmux # 에이전트당 하나의 창을 가진 단일 tmux 세션을 엽니다
agents attach atlas,agent2,agent3 --via tmux

환경에 연결하는 것은 에이전트와 통신하는 방법 중 하나입니다. 이 명령어가 수행하는 작업은 사용자를 해당 환경으로 텔레포트시키는 것입니다. 또 다른 통신 방법도 있습니다.

중요한 점은 각 에이전트가 편의성을 해치지 않으면서도 서로 다르고 개인화된 환경을 가질 수 있다는 것입니다. 환경 자체가 어떻게 연결하거나 통신해야 하는지 알고 있기 때문입니다. 그러면 저는 하나의

init 및 doctor 명령어
라이브러리는 모든 것을 쉽게 설정하고 도구들이 올바르게 설정되었는지 확인할 수 있는 두 가지 명령어를 제공합니다.

agents init은 부트스트랩(bootstrap) 명령어입니다. 이는 .agents를 생성하고, 내장된 템플릿을 그 안에 복사하며, 라이브러리의 나머지 부분이 존재한다고 가정하는 디렉토리 구조를 배치합니다.

Secrets에는 약간 비직관적인 구현 세부 사항이 하나 있습니다. Windows에서는 디렉토리가 mode 755로 생성되며, 복사된 대부분의 자격 증명(credential) 파일은 644일 것으로 예상됩니다. 단일 사용자 호스트 프로세스만 생각한다면 이것이 느슨해 보일 수 있지만, Docker 기반 에이전트를 위해서는 의도된 사항입니다. 많은 에이전트 도구들은 non-root 사용자로 실행될 것을 요구합니다.

마운트된 비밀 정보(secrets)는 컨테이너 내부에서 읽을 수 있어야 합니다. Kimi 자격 증명(credential) 파일의 경우, 해당 도구가 요구하는 사항이기 때문에 예상되는 모드(mode)는 더 엄격한 600입니다.

또한 선택 사항인 --copy-credentials 플래그가 있습니다. 이 플래그를 사용하면, init 명령어가 사용자의 홈 디렉토리로부터 Claude, Codex, Gemini, GitHub CLI/Copilot, Kimi, 그리고 MiniMax 설정 파일을 포함한 알려진 AI 도구 자격 증명들을 .agents/.secrets/common으로 복사합니다. 이를 통해 각 에이전트가 개별 복사본을 강제로 가질 필요 없이, 모든 에이전트가 공통적인 폴백(fallback) 자격 증명 세트를 가질 수 있게 됩니다.

agents doctor는 이에 대응하는 사전 점검(preflight) 명령입니다.
이 명령은 먼저 디렉토리 트리를 확인하여 파일이 존재하는지 검증합니다. 에이전트별 비밀 정보 디렉토리가 누락된 것은 실패로 간주되지 않는데, 이는 많은 에이전트가 공통 비밀 정보에 의존할 수 있기 때문입니다. 하지만 기존 비밀 정보 디렉토리의 권한이 잘못된 경우에는 이를 수정할 수 있는 정확한 chmod 명령과 함께 보고됩니다.

그 후 도구들을 점검합니다. git은 필수 사항입니다. Harness 바이너리는 설정된 에이전트들로부터 검색되며 존재할 경우 보고되지만, 에이전트가 호스트 대신 Docker 내부에서 이를 실행할 수 있으므로 doctor 단계에서는 선택 사항으로 취급됩니다. Docker는 설정된 에이전트 중 최소 하나가 runtime: docker를 사용하는 경우에만 필수 요구 사항이며, 그렇지 않으면 단순히 선택 사항으로 보고됩니다.

마지막으로, --no-network로 비활성화하지 않는 한, GitHub, Anthropic, 그리고 OpenAI에 대한 외부 연결성 점검을 실행합니다.
명령어는 모든 필수 점검을 통과했을 때만 0으로 종료됩니다. 그렇지 않으면 1로 종료되며 실패 요약과 힌트를 출력합니다. 이는 사람이 직접 사용하는 명령어로도, 스크립트 내의 설정 게이트(setup gate)로도 유용하게 만듭니다.

이와 관련하여 몇 가지 가치 있는 사용자 제안들이 있었으며, 이를 어떻게 구현할지는 아직 계획 중입니다:

이들은 기존 모델을 깨뜨리지 않으며, 그 위에 추가할 수 있는 개선 사항들입니다.
이 부분은 꽤 간단하지만, 다른 모든 것의 토대를 마련합니다. 다음은 각 에이전트의 환경 라이프사이클(environment lifecycle)에 관한 내용입니다.

이 글은 제가 구축하고 있는 에이전트 오케스트레이션 (agent-orchestration) 라이브러리의 아키텍처를 다루는 일련의 문서 중 두 번째입니다. 이전 글은 에이전트가 실행되는 환경 (environment)에 관한 것이었습니다. 이번 글은 실제로 라이브러리를 어떻게 선언하고 사용하는지에 관한 것입니다.

저는 에이전트를 쉽게 선언할 수 있는 무언가를 만들고 싶었습니다. 대부분의 라이브러리가 이를 달성하는 방식은 보통 고정된 설정 (fixed configuration)을 가진 스레드 (thread)로 만드는 것입니다. 그렇게 하면 설정할 것이 거의 없기 때문에 하나를 생성하는 것이 매우 간단해집니다.

저는 각 에이전트가 자신만의 런타임 (runtime), 워크스페이스 (workspace), 하네스 (harness), 그리고 툴체인 (toolchain)을 가진 독립적인 엔티티 (entity)가 되기를 원했습니다. 여기에는 분명 비용이 따릅니다. 만약 모든 에이전트가 모든 축 (axis)에서 서로 다를 수 있다면, 모든 에이전트가 자신에 대한 모든 것을 명시해야 하므로 플릿 (fleet, 에이전트 군단)을 선언하고 운영하는 것이 매우 지루해질 것입니다.

이전 포스트에서 설명한 이유로 인해 각 에이전트는 여전히 자신만의 격리된 워크스페이스 (workspace), 아티팩트 (artifacts), 그리고 시크릿 (secrets)을 가진다는 점에 유의하세요. 이번 글은 이것들을 어떻게 선언하고 구동하는지에 관한 것입니다.

제가 고안한 해결책은 다음과 같습니다.

위치 (Where it lives)
모든 것은 리포지토리 루트 (repo root)의 .agents 아래에 위치합니다. 설정 (config) 또한 이전에 언급한 아티팩트 (artifacts), 시크릿 (secrets), 워크스페이스 (workspaces)와 함께 agents.yaml 파일로 그곳에 위치합니다.

<repo-root>/ .agents/ .artifacts/ agents/ common/ .secrets/ agents/ common/ .workspaces/ agents.yaml

여기서 제가 중요하게 생각하는 점은 전체 플릿 (fleet)이 제가 열어서 읽을 수 있는 디렉토리라는 것입니다. 설정 (config)과 상태 (state)는 리포지토리에 있으며, 아마도 git에 포함될 것입니다.

에이전트 선언 (Declaring agents)
설정 (config)은 두 부분으로 나뉩니다: 모든 에이전트가 상속받는 기본값 (defaults), 그리고 차이가 나는 축 (axes)만 덮어쓰는 에이전트별 항목 (per-agent entries)입니다.

defaults:
  harness: claude
  workspace:
    environment:
      filesystem:
        mode: worktree

agents:
  atlas:
    harness: codex
    runtime: docker
    toolchain: nodepy
    workspace:
      mode: clone
  agent2:
    harness: kimi
  agent3:
    harness: codex
  agent4: null
  agent5: null
  agent6: null

각 에이전트는 defaults로부터 모든 것을 상속받고 필요한 것만 변경합니다. atlas는 다른 하네스 (harness), 런타임 (runtime), 그리고 워크스페이스 (workspace)를 실행합니다.

agent2는 하네스 (harness)만 교체합니다. agent4부터 agent6까지는 null이므로, 기본값(defaults)을 그대로 가져갑니다. 어떤 에이전트든 실제로 차이가 나는 부분만을 기록함으로써 어떤 축(axis)이든 재정의(override)할 수 있습니다.

저는 JSON 대신 yaml을 선택했는데, 그 이유는 이 파일이 플릿 (fleet)을 운영하는 동안 제가 끊임없이 직접 수정하는 파일이기 때문입니다. 따라서 직렬화 형식 (serialization format)이 아닌, 읽기와 편집에 최적화되기를 원했습니다.

실행하기 (Driving them)
에이전트를 시작하려면 다음과 같이 수행합니다:

agents init # 각 에이전트를 위한 디렉토리를 자동으로 생성합니다.
agents provision atlas # 워크스페이스 (workspace)를 생성합니다.
agents start atlas # 실제 환경 (예: Docker 컨테이너)을 시작합니다.

init은 설정을 구성하고, provision은 에이전트의 환경을 구축하며, start는 이를 실행합니다.

환경이 시작되면 다음과 같이 접속(attach)할 수 있습니다:

agents attach atlas --via tmux # 에이전트당 하나의 창을 가진 단일 tmux 세션을 엽니다.
agents attach atlas,agent2,agent3 --via tmux

환경에 접속하는 것은 에이전트와 통신하는 방법 중 하나입니다. 이 명령어가 수행하는 역할은 사용자를 해당 환경으로 텔레포트시키는 것입니다. 또 다른 통신 방법도 존재합니다.

중요한 점은, 편의성을 해치지 않으면서도 각 에이전트가 서로 다른 개인화된 환경을 가질 수 있다는 것입니다. 환경 자체가 자신에게 접속하거나 통신하는 방법을 알고 있기 때문입니다. 그러면 저는 하나의

init 및 doctor 명령어
라이브러리는 모든 것을 쉽게 설정하고 도구들이 올바르게 설정되었는지 확인할 수 있는 두 가지 명령어를 제공합니다.

agents init은 부트스트랩 (bootstrap) 명령어입니다. 이는 .agents를 생성하고, 내장된 템플릿을 그 안에 복사하며, 라이브러리의 나머지 부분이 존재한다고 가정하는 디렉토리 구조를 배치합니다.

Secrets에는 약간 직관적이지 않은 구현 세부 사항이 하나 있습니다. Windows에서는 디렉토리가 mode 755로 생성되며, 복사되는 대부분의 자격 증명 (credential) 파일은 644일 것으로 예상됩니다. 단일 사용자 호스트 프로세스만 생각한다면 이것이 느슨해 보일 수 있지만, Docker 기반 에이전트를 위해서는 의도된 사항입니다. 많은 에이전트 도구들은 루트 (non-root) 사용자로 실행될 것을 요구합니다.

마운트된 비밀 정보 (secrets)는 컨테이너 내부에서 읽을 수 있어야 합니다. Kimi 자격 증명 (credential) 파일의 경우, 해당 도구가 요구하는 사항에 따라 더 엄격한 모드인 600이 요구됩니다.

또한 선택 사항인 --copy-credentials 플래그가 있습니다. 이 플래그를 사용하면, init이 사용자의 홈 디렉토리에서 Claude, Codex, Gemini, GitHub CLI/Copilot, Kimi, 그리고 MiniMax 설정 파일을 포함한 알려진 AI 도구 자격 증명들을 .agents/.secrets/common으로 복사합니다. 이를 통해 각 에이전트가 개별 복사본을 가질 필요 없이, 모든 에이전트가 공통적인 폴더백 (fallback) 자격 증명 세트를 가질 수 있게 됩니다.

agents doctor는 이에 대응하는 사전 점검 (preflight) 명령입니다.
이 명령은 먼저 디렉토리 트리를 확인하여 파일이 존재하는지 검증합니다. 에이전트별 비밀 정보 디렉토리가 누락된 것은 실패로 간주되지 않는데, 이는 많은 에이전트가 공통 비밀 정보에 의존할 수 있기 때문입니다. 하지만 기존 비밀 정보 디렉토리의 권한이 잘못된 경우에는 이를 수정할 수 있는 정확한 chmod 명령과 함께 보고됩니다.

그 후 도구들을 점검합니다. git은 필수 사항입니다. Harness 바이너리들은 설정된 에이전트들로부터 발견되어 존재할 경우 보고되지만, 에이전트가 호스트 대신 Docker 내부에서 이를 실행할 수 있으므로 doctor 실행 시점에는 선택 사항으로 취급됩니다. Docker는 설정된 에이전트 중 최소 하나가 runtime: docker를 사용하는 경우에만 필수 요구 사항이며, 그렇지 않으면 단순히 선택 사항으로 보고됩니다.

마지막으로, --no-network로 비활성화하지 않는 한, GitHub, Anthropic, 그리고 OpenAI에 대한 외부 연결성 점검을 실행합니다.
명령어는 모든 필수 점검을 통과했을 때만 0으로 종료됩니다. 그렇지 않으면 1로 종료되며 실패 요약과 힌트를 출력합니다. 이는 사람을 위한 명령어로도, 스크립트 내의 설정 게이트 (setup gate)로도 유용하게 사용할 수 있게 합니다.

이와 관련하여 몇 가지 가치 있는 사용자 제안들이 있었으며, 이를 어떻게 구현할지는 아직 계획 중입니다:

이것들은 기존 모델을 망가뜨리지 않으며, 그 위에 추가될 수 있는 개선 사항들입니다.
이 부분은 꽤 간단하지만, 다른 모든 것의 토대를 마련합니다. 다음은 각 에이전트의 환경 생명주기 (environment lifecycle)에 관한 내용입니다.
submitted by /u/facu_75 to r/LocalLLaMA
[link] [comments]