블로그 · 가이드 · 2026년 10월 28일
AEGIS 에이전트 매니페스트: 모든 필드와 그것이 강제하는 것
공개: AEGIS는 100monkeys.ai가 만들고 있으므로 이 가이드는 만든 쪽의 설명으로 읽어 주세요. 이 가이드는 저희 AI 에이전트 하나가 공개 AEGIS 문서(영어), 주로 Agent Manifest Reference, CLI Reference, Workflow Manifest Reference, Human Approvals를 바탕으로 초안을 쓰고 회사가 검토했으며, 이 한국어판은 영어 원문 가이드의 번역입니다. 필드 이름, 기본값, 거부 메시지는 그 페이지들에서 인용했습니다.
AEGIS by 100monkeys.ai, in beta는 YAML 파일 하나로 에이전트를 실행합니다. 문서는 에이전트 매니페스트를 "the source of truth for an Agent's identity, capabilities, security constraints, and execution requirements."(에이전트의 신원, 능력, 보안 제약, 실행 요건에 대한 기준 원본)라고 부릅니다. 이 가이드는 매니페스트를 절마다 살펴보며, 각 필드를 오케스트레이터가 어떻게 다루는지 설명합니다.
1단계. 헤더 쓰기
apiVersion: 100monkeys.ai/v1
kind: Agent
metadata:
name: pr-reviewer
version: "1.0.0"
description: "Reviews pull request diffs and returns structured feedback."apiVersion과 kind는 정확히 이 값이어야 합니다. name은 ^[a-z0-9][a-z0-9-]{0,62}$와 맞아야 하고, name과 version의 쌍은 유일해야 합니다. 같은 쌍을 다시 배포하면 --force를 주지 않는 한 실패합니다. labels와 annotations는 검색과 메모를 위한 선택적 키-값 맵입니다.
2단계. 런타임 고르기
spec.runtime은 spec에서 유일한 필수 부분입니다. language와 version(python, javascript, typescript, rust, go 중 하나로, 공식 이미지로 해석됨)을 주거나, 완전한 이름의 image를 주되 둘 다 주지는 않습니다. version 없는 language는 유효하지 않습니다. image_pull_policy의 기본값은 IfNotPresent입니다. model은 aegis-config.yaml의 모델 별칭을 가리키며, 이미지를 생성하는 별칭은 거부됩니다. isolation은 inherit, docker, firecracker, process를 받으며, 레퍼런스는 docker를 Phase 1, 나머지 둘을 Phase 2로 표시합니다.
3단계. 작업 주기
task.instruction은 에이전트가 따르는 지침이며, 이것을 설정하면 "auto-enables semantic validation"(의미 검증이 자동으로 켜집니다). task.prompt_template은 Handlebars 템플릿이고, 변수는 {{intent}}, {{instruction}}, {{input}}, {{iteration_number}}, {{previous_error}}, {{context}}입니다. type: object인 JSON Schema spec.input_schema는 이름 있는 입력을 선언하고 에이전트가 실행되기 전에 검증합니다.
4단계. 필요한 접근만 선언하기
"All permissions are deny-by-default."(모든 권한은 기본적으로 거부입니다.) spec.security가 없으면 에이전트에게는 네트워크도 파일 시스템 접근도 없습니다. network.mode는 allow(allowlist만), deny(denylist를 뺀 전부), 또는 none이며, none은 "attaches no network interface to the container"(컨테이너에 네트워크 인터페이스를 붙이지 않습니다). filesystem.read와 filesystem.write는 경로를 나열하며 glob을 쓸 수 있습니다. 리소스 기본값은 cpu: 1000 밀리코어, memory: "512Mi", disk: "1Gi", timeout: "1800s"이고, 최대 1시간입니다. 에이전트가 두 번 이상 시도할 수 있다면 timeout은 시도 두 번을 온전히 담아야 합니다. 2 × (iteration_timeout + 심사자의 timeout_seconds) + 45초. 그렇지 않으면 에이전트는 "is refused on create and update"(생성과 업데이트 때 거부됩니다).
5단계. 볼륨 마운트하기
spec.volumes[]의 각 항목에는 name, storage_class(ephemeral은 ttl_hours가, persistent는 source.volume_id가 필요), /workspace 아래의 mount_path, 그리고 access_mode가 있습니다. 영구 볼륨에 대한 읽기-쓰기 접근은 한 번에 한 실행만 가질 수 있습니다. 마운트할 수 없는 볼륨은 반복을 멈춥니다. 에이전트는 "never runs without its volume."(자기 볼륨 없이는 절대 실행되지 않습니다.)
6단계. 반복 방식과 완료 기준 정하기
execution.mode는 iterative(기본값) 또는 one-shot입니다. max_iterations는 1부터 20까지, 기본값 5이며, max_retries는 같은 필드입니다. iteration_timeout의 기본값은 600s, llm_timeout_seconds는 300입니다. 시도할 때마다 validation이 순서대로 실행됩니다. exit_code, json_schema, regex, semantic(심사 에이전트, 기본 min_score 0.7), 또는 multi_judge. 실패는 {{previous_error}}로 에이전트에게 돌아갑니다. tool_validation은 각 도구 호출을 실행 전에 심사하며, 여기서는 semantic 항목만 쓰입니다. outputs는 실행이 남겨야 할 파일을 지정하고, 각각 선택적으로 min_bytes와 magic을 가지며, 하나라도 없으면 그 시도는 실패합니다.
7단계. 도구 허용하기
spec.tools는 "mcp:filesystem" 같은 문자열이나 name, server, config를 가진 객체를 받습니다. 명령을 실행하려면 executor: "builtin:cmd"와 필수 항목 subcommand_allowlist(명령에서 허용된 첫 인자로 가는 맵)를 선언합니다. 그 밖의 호출은 "is rejected with a policy violation"(정책 위반으로 거부됩니다). 오케스트레이터는 선언으로 작업을 할 수 있는지 확인합니다. 파일을 써야 하는데 도구를 하나도 선언하지 않았거나, 읽기-쓰기 볼륨 없이 fs.write를 선언한 에이전트는 배포 때 이유를 밝힌 문장과 함께 거부됩니다.
8단계. 설정과 시크릿 전달하기
spec.env 값은 리터럴, "secret:<name>"(OpenBao에서 주입되며 "never logged", 절대 기록되지 않음), 또는 "config:<key>"입니다. spec.security_context는 플랫폼 운영자 전용이며, 이것을 설정한 소비자 계정은 403 Forbidden을 받습니다.
9단계. 검증한 다음 배포하기
aegis agent deploy ./agent.yaml --validate-only
aegis agent deploy ./agent.yaml--validate-only는 배포하지 않고 파싱과 검증만 합니다. aegis agent show <AGENT_ID>는 저장된 매니페스트를 다시 출력합니다.
사람의 승인은 어디에 들어가는가
에이전트 매니페스트에는 승인 필드가 없습니다. 사람의 yes는 워크플로의 kind: Human 상태에 속합니다. prompt는 필수이고, timeout의 기본값은 3600s이며, default_response는 시간이 다 되었을 때 채택되는 답입니다. 그것이 없으면 워크플로는 실패합니다. Human Approvals에 따르면 게이트의 input_equals_yes 전이는 yes를, input_equals_no는 no를 받으며, 어느 전이도 받지 않는 답은 거부되고 다시 묻습니다.
문서가 답하지 않은 것
- 두 레퍼런스는 게이트 단어에서 서로 다릅니다. Workflow Manifest Reference에서는
input_equals_yes가 "yes", "approve", "approved", "true"를 받고, Human Approvals는yes,y,1이라고 합니다. 이 가이드는 Human Approvals를 따릅니다. metadata.version은 예시에서는 "semantic version"(시맨틱 버전), 표에서는 "Manifest schema version"(매니페스트 스키마 버전)이라고 불립니다.firecracker와process는 유효한isolation값으로 Phase 2 표시와 함께 나열되어 있지만, 지금 매니페스트에 그중 하나를 적으면 어떻게 되는지는 레퍼런스에 없습니다.
다음
새 서버에서 매니페스트를 처음부터 끝까지 실행하려면 새 Ubuntu VPS에 AEGIS를 설치하고 첫 번째 승인 작업 실행하기를 읽으세요. AEGIS는 100monkeys.ai에 적힌 명령으로 설치합니다.
curl -fsSL https://get.100monkeys.ai | bash