간단한 소개를 시작하겠습니다. 지난달 저는 제가 가장 자주 사용하는 AI 에이전트에 대해 불편한 사실 하나를 깨달았습니다. 바로 그것을 어디로든 가져갈 수 없다는 점이었습니다.

그것은 제가 몇 주 동안 튜닝해 온 리서치 에이전트(research agent)입니다. 수십 번의 프롬프트(prompt) 반복, 두 개의 스킬(skills), 하나의 MCP 데이터 소스, 지식 파일(knowledge files), 그리고 엄선된 도구 권한(tool permissions)까지 포함되어 있습니다. 이 모든 것이 하나의 클라우드 플랫폼 내, 하나의 계정 아래 흩어진 콘솔 페이지들로 존재합니다. 만약 제가 계정이나 플랫폼을 바꾸게 된다면, 저는 스크린샷만을 가지고 떠나게 될 것입니다.

우리는 코드(Git), 의존성(dependencies, lockfiles), 또는 인프라(infra, Terraform)에 대해서는 이런 상황을 결코 용납하지 않습니다. 그런데 왜 에이전트에 대해서는 이를 용납하는 걸까요?

[

제가 시도한 것

OpenAgentPack — 오픈 소스 (Apache-2.0, beta). 하나의 agents.yaml이 전체 에이전트 스택(agent stack)을 선언하며, Terraform 스타일의 워크플로(workflow)가 이를 클라우드로 푸시(push)합니다.

npm install -g @openagentpack/cli   # Node.js 22+

mkdir my-agents && cd my-agents
...

전체 실행 과정은 다음과 같습니다:

[

선언문에는 모델(model), 지침(instructions), 도구(tools), 스킬(skills), MCP 서버(MCP servers), 환경(environments), 그리고 자격 증명 참조(credential references)가 포함됩니다. 비밀 정보(secrets)는 파일에 절대 포함되지 않고 .env 파일에 ${VAR_NAME} 형태로 유지됩니다. 따라서 YAML 파일은 Git에 깔끔하게 커밋(commit)될 수 있습니다.

agents:
  assistant:
    description: "General-purpose coding assistant"
...

저를 설득한 세 가지 요소

1. plan은 진정한 의미의 3-way diff입니다. 이는 사용자가 선언한 설정(config), 로컬 상태 파일(local state file, 원격 ID + 콘텐츠 해시), 그리고 실제로 원격에 존재하는 상태를 조정(reconcile)합니다. 필드 하나를 변경하면 → plan에서 하나의 업데이트가 발생합니다. 누군가 콘솔을 수동으로 편집하면 → 드리프트(drift)로 표시됩니다.

2. 나의 첫 번째 실수는 오프라인에서 발견되었습니다. validate 명령어가 단 한 번의 API 호출이 나가기 전에 들여쓰기 실수를 잡아냈습니다. 비용이 적게 드는 단계에서 빠르게 실패(Fail-fast)하십시오.

3. 수락 테스트(Acceptance testing)가 내장되어 있습니다. agents playground는 로컬 WebUI를 실행하고 동일한 선언으로부터 실제 세션을 실행합니다. 저는 마이그레이션 후 표준 연구 작업을 다시 실행하여 이전 설정과 출력을 비교했습니다. 동일한 구조, 동일한 엄격함을 유지했습니다. 또한 --provider (bailian / qoder / ark / claude)를 전환하여 동일한 시나리오를 여러 백엔드(backend)에 대해 벤치마킹할 수도 있습니다.

솔직한 주의사항

• 이것은 베타(beta) 버전입니다. 1.0 버전이 되기 전에 스키마(schema)가 변경될 수 있습니다. 저는 지금까지 테스트용 에이전트만 옮겼습니다.
• 제공자 간의 기능적 동등성(Provider parity)은 명시적으로 약속되지 않았습니다. 모든 기능은 제공자별로 native / emulated / unsupported로 표시됩니다. 실제 데이터를 마이그레이션하기 전에 해당 매트릭스(matrix)를 읽어보십시오.
• 상태(State)는 현재 로컬 파일입니다. 팀 수준의 상태 공유는 사용자의 몫입니다 (초기 Terraform의 느낌과 비슷합니다).

이것이 왜 중요한지에 대한 나의 생각

"코드로서의 에이전트(Agents as code)"는 10년 전의 "코드로서의 인프라(infrastructure as code)"가 가던 길처럼 느껴집니다. 지나고 나면 당연해 보이지만, 한 번 경험하고 나면 그것 없이 살기가 어색해지는 방식입니다. 여러분의 프롬프트(prompt), 워크플로우(workflow), 그리고 판단력은 여러분이 실제로 소유할 수 있는 형태를 가질 자격이 있습니다.

Repo: github.com/modelstudioai/OpenAgentPack

Bailian 제공자를 사용해 보시겠습니까? DASHSCOPE_API_KEY가 필요합니다. Alibaba Cloud Model Studio에서 무료로 생성할 수 있습니다.

다른 분들도 에이전트를 버전 관리하고 있는지 궁금합니다. 여러분의 설정은 어떠신가요?