agentopology/agentopology

AI 에이전트를 위한 Terraform.

에이전트 팀을 한 번만 정의하세요. 어떤 플랫폼으로든 배포할 수 있습니다.

Claude Code · Claude Workflow · OpenClaw · Codex · Cursor · Gemini CLI · Copilot · Kiro

Claude Code 스킬과 함께 제공됩니다 — 그냥 /agentopology를 입력하고 팀을 설명하세요.

AI 에이전트 하나를 만드는 것은 쉽습니다. 실제로 함께 작동하는 에이전트 **팀 (team)**을 구축하는 것은 매우 고통스러운 일입니다.

마케팅 팀이 필요하신가요? 개발 파이프라인 (dev pipeline)? 지원 부대인가요? AGENT.md 파일, soul.md 설정, MCP 서버, 훅 (hooks), 그리고 스크립트들을 연결하느라 몇 시간을 소비합니다. Claude Code에서 겨우 작동하게 만들었습니다. 그다음 OpenClaw에서도 동일한 팀이 필요해지면 — 처음부터 다시 시작해야 합니다. 서로 다른 설정 형식 (config format). 서로 다른 디렉토리 구조 (directory structure). 서로 다른 컨벤션 (conventions). 에이전트는 같고 로직도 같지만, 이식성 (portability)은 제로입니다.

OpenClaw만 사용하더라도 각 에이전트마다 soul.md, 스킬 파일 (skill files), 채널 설정 (channel configs), 게이트웨이 설정 (gateway setup), 그리고 워크스페이스 정의 (workspace definitions)가 필요합니다. 에이전트가 5개라면, 시각화하거나 검증할 수도 없고 누구에게도 전달할 수 없는 20개 이상의 파일을 관리해야 한다는 뜻입니다.

그리고 이것은 단지 플랫폼의 문제일 뿐입니다. 아키텍처 (architecture) 문제는 더 심각합니다:

전체적인 그림을 어떻게 볼 수 있나요? 당신의 토폴로지 (topology)는 중첩된 디렉토리 내 15개의 파일에 흩어져 있습니다. 다이어그램도 없고, 단일 진실 공급원 (single source of truth)도 없습니다. 에이전트들이 서로 어떻게 대화하나요? 파일 기반 프로토콜을 임시로 만들거나 프롬프트 사이에 컨텍스트 (context)를 복사해서 붙여넣습니다. 표준이 없습니다. 품질을 어떻게 강제하나요? 단계 사이에 게이트 (gate)를 두고 싶지만, 이를 정의하는 표준적인 방법이 없습니다. 어떻게 빠르게 움직이나요? 새로운 에이전트가 추가될 때마다 여러 도구에 걸쳐 5~12개의 파일을 수정해야 합니다.

AgenTopology가 이 모든 것을 해결합니다.

에이전트 팀을 단 하나의 .at 파일에 작성하세요. 마케팅, 개발, 지원, 카피라이팅 — 어떤 팀이든, 어떤 구조든 가능합니다. 시각화하세요. 검증하세요. 단 한 번의 명령으로 어떤 플랫폼으로든 스캐폴딩 (scaffold) 하세요.

topology code-review : [pipeline] {
agent researcher { model: sonnet tools: [Read, Grep, WebSearch] }
agent writer { model: sonnet tools: [Read, Write] }
...
}

agentopology scaffold my-team.at --target claude-code # → .claude/agents/
agentopology scaffold my-team.at --target claude-workflow # → my-team.workflow.js (+ SEAM/README/LOSSY-REPORT)
agentopology scaffold my-team.at --target openclaw # → .openclaw/soul.md
...

단 하나의 파일. 모든 플랫폼. 토폴로지 (Topology) 자체가 곧 문서입니다.

단 하나의 .at 토폴로지는 두 개의 결합된 타겟 (coupled targets)으로 동시에 컴파일될 수 있습니다. claude-code는 호스트 (host) — 에이전트 (agents), 훅 (hooks), 블랙보드 (Blackboard), 동시 관찰성 (concurrent observability), 그리고 인간/게이트/분기 노드 (human/gate/branching nodes)를 소유하는 이벤트 기반 레이어 (event-driven layer)입니다. claude-workflow는 임베디드된 결정론적 런 (deterministic rung) — 병렬 팬아웃 단계 (parallel fan-out phases)이며, Claude Workflow 도구 스크립트로 컴파일됩니다. 호스트는 이 런 (rung)을 실행하고 PostToolUse 훅을 통해 블랙보드 쓰기 (Blackboard writes)를 실시간으로 관찰하므로, Workflow 런타임 (runtime)이 자체적으로 수행할 수 없는 동시 관찰성을 얻을 수 있습니다.

extensions { claude-workflow { execution: workflow } }를 사용하여 런 (rung)의 단계를 표시한 다음, 둘 다 스캐폴딩 (scaffold) 하세요:

agentopology scaffold my-team.at --target claude-code # 호스트 (the host)
agentopology scaffold my-team.at --target claude-workflow # 임베디드 런 (the embedded rung)

하이브리드 방식은 선택 사항 (opt-in)입니다. execution: workflow 표시가 없는 토폴로지는 변경 없이 순수한 claude-code로 컴파일됩니다. 그 이유는 docs/AT_VS_WORKFLOW_STRATEGY.md를 참조하세요.

AgenTopology는 에이전트 정의를 플랫폼 네이티브 설정 파일 (platform-native configuration files)로 변환하는 선언적 언어 (declarative language) (.at 파일)이자 CLI 컴파일러 (CLI compiler) 입니다.

┌──────────────┐ ┌────────────┐ ┌─────────────────────┐
│ .at file     │ ───▶ │ Parser &   │ ───▶ │ Platform configs    │
│ (you write)  │ │ Validator  │ │ (auto-generated)   │
└──────────────┘ └────────────┘ └─────────────────────┘
...

이제 설정 파일을 수동으로 유지 관리할 필요가 없습니다. 당신의 토폴로지가 단일 진실 공급원 (single source of truth)이 됩니다.

npm install -g agentopology

검증 (Validate) — 스캐폴딩 하기 전에 오류를 포착하세요:
agentopology validate my-team.at

스캐폴딩 (Scaffold) — 플랫폼 설정 파일을 생성하세요:
agentopology scaffold my-team.at --target claude-code

시각화 (Visualize) — 당신의 토폴로지를 인터랙티브 그래프 (interactive graph)로 확인하세요:

agentopology visualize my-team.at

대상 목록 확인 (List targets) — 지원되는 모든 플랫폼을 확인하세요:

agentopology targets

.at 구문을 배울 필요가 없습니다. AgenTopology는 Claude Code를 토폴로지 디자이너 (topology designer)로 변환해 주는 인터랙티브 스킬 (interactive skill)을 제공합니다. 원하는 팀의 모습을 일상적인 영어로 설명하기만 하면 됩니다. 그러면 스킬이 모든 것을 생성합니다.

# 전역 설치 (Install globally)
npm install -g agentopology
# 프로젝트에 스킬 연결 (Link the skill into your project)
...

Claude Code에서 /agentopology를 입력하거나,

— 또는 자연스럽게 질문하세요:

> /agentopology
┌─────────────────────────────────────┐
│ AgenTopology │
...

**"분석가(analyzer), 보안 스캐너(security scanner), 리뷰어(reviewer)가 포함된 코드 리뷰 팀을 원해"**라고 말해보세요. 그러면 스킬이 다음 작업을 수행합니다:

• 올바른 구문으로 .at 파일을 생성합니다.
• 82가지 규칙에 따라 이를 검증 (validate) 합니다.
• Claude Code, OpenClaw, Cursor 또는 원하는 대상(target)에 맞춰 스캐폴딩 (scaffold) 합니다.

2분 이내에 완전한 에이전트 팀을 구축하세요. 읽어야 할 문서도, 암기해야 할 구문도 없습니다. 당신은 원하는 것을 설명하기만 하면 되고, 나머지는 스킬이 처리합니다.

작동하는 .at 파일이 있고 이를 개선하고 싶으신가요? 스킬에게 필요한 내용을 말하기만 하면 됩니다:

"리뷰어 앞에 보안 스캐너 에이전트를 추가해줘" — 스킬이 에이전트를 추가하고, 흐름(flow)에 연결하며, 다시 검증합니다.
"모든 쓰기 작업 후에 코드를 포맷팅하는 훅(hook)을 추가해줘" — 올바른 라이프사이클 이벤트 (lifecycle event)와 함께 훅 블록을 생성합니다.
"GitHub을 위한 MCP 서버를 추가해줘" — 환경 변수와 함께 서버 설정을 추가합니다.
"빌더(builder)와 리뷰어 사이에 품질 게이트(quality gate)를 추가해줘" — 실패 시 중단(halt-on-fail) 기능이 있는 게이트를 삽입합니다.
"대상을 OpenClaw로 전환해줘" — 다른 플랫폼에 맞춰 전체 토폴로지를 다시 스캐폴딩 합니다.

워크플로우는 항상 동일합니다: 변경 사항 설명 → 스킬이 .at 파일 업데이트 → 검증 → 재스캐폴딩. 설정 파일을 수동으로 만질 일은 전혀 없습니다.

변경 사항이 발생하면 agentopology visualize가 인터랙티브 그래프를 업데이트하여 모든 에이전트, 연결, 도구, 훅, 게이트를 한눈에 확인하며 무엇이 변경되었는지 정확히 볼 수 있습니다.

전체 언어 참조 및 가이드는 agentopology.com/docs에서 확인할 수 있습니다.

.at

.at 파일은 사람이 읽을 수 있고 버전 관리 (version-controllable)가 가능합니다. 실제 토폴로지 (topology) 예시는 다음과 같습니다:

topology content-pipeline : [pipeline, human-gate] {
meta {
version: "1.0.0"
...

이것은 단 40줄 만에 세 개의 에이전트 (agents), 그들의 도구 (tools)와 메모리 (memory), 품질 게이트 (quality gate), 그리고 조건부 재시도 루프 (conditional retry loop)가 포함된 흐름 (flow)을 정의합니다.

대상 (Target)	명령어 (Command)	생성물 (What It Generates)
Claude Code	--target claude-code	.claude/agents/ , .claude/skills/ , .mcp.json , .claude/settings.json (이벤트 기반 호스트)
Claude Workflow	--target claude-workflow	<topology>.workflow.js (결정론적 팬아웃 단계 (deterministic fan-out rung)) + -SEAM.md , -README.md , -LOSSY-REPORT.md
OpenClaw	--target openclaw	.openclaw/soul.md , .openclaw/skills/ , .openclaw/config.json
Codex	--target codex	.codex/config.toml , AGENTS.md
Cursor	--target cursor	.cursor/rules/*.mdc , .cursor/mcp.json , .cursor/hooks.json
Gemini CLI	--target gemini-cli	.gemini/ , AGENTS.md
Copilot	--target copilot-cli	.github/agents/*.agent.md , .github/copilot-instructions.md
Kiro	--target kiro	.kiro/agents/*.json , .kiro/steering/

모든 바인딩 (binding)은 실제 프로덕션 리포지토리 (production repos)의 설정값과 대조하여 실질적인 진실 (ground-truth)임을 검증합니다.

|
|
|
|
|
|
|
|
|

또한: 메모리 저장소 (memory stores) (시맨틱 (semantic), 그래프 (graph), 에피소드 (episodic) — 11개의 백엔드), 검색 전략 (retrieval strategies) (스코어링 가중치 (scoring weights), 캐시 히트 라우팅 (cache-hit routing)), 스키마 (schemas), 아티팩트 (artifacts), 미터링 (metering), 서킷 브레이커 (circuit breakers), 스케일 설정 (scale configs), 깊이 수준 (depth levels), 환경 오버라이드 (environment overrides), 프롬프트 변형 (prompt variants), 임포트 (imports)를 통한 구성 (composition) 등을 지원합니다.

그룹 (Groups)은 단순히 팬아웃 (fan-out) 구조가 아닙니다. 그것은 실제 대화입니다. 각 에이전트는 다른 에이전트가 작성한 내용을 읽고 응답합니다:

group design-review {
members: [architect, security-lead, tech-lead]
speaker-selection: "round-robin"
...

Claude Code에서 이것은 **파일 기반 프로토콜 (file-based protocol)**로 컴파일됩니다. 즉, 에이전트들이 순차적으로 읽고 내용을 추가하는 공유 트랜스크립트 (shared transcript) 파일입니다. HTTP도, 메시지 버스 (message bus)도 필요 없습니다. 오직 파일 시스템 (filesystem)을 공유 상태 (shared state)로 사용할 뿐입니다.

import { parse, validate, bindings } from "agentopology";
// 파싱 (Parse)
const ast = parse(atSource);
...

어떤 플랫폼이든 추가할 수 있도록 BindingTarget 인터페이스를 구현하세요:

import type { BindingTarget } from "agentopology";
export const myBinding: BindingTarget = {
name: "my-platform",
...

.at 파일이 곧 당신의 아키텍처 다이어그램 (architecture diagram)입니다. 파일을 열면 다음을 확인할 수 있습니다:

• 에이전트 (agents)가 누구인지
• 어떤 도구 (tools)를 가지고 있는지
• 에이전트 간에 작업이 어떻게 흐르는지 (work flows)
• 품질 게이트 (quality gates)가 어디에 있는지
• 문제가 발생했을 때 어떤 일이 일어나는지

agentopology visualize 명령어를 통해 이를 대화형 그래프 (interactive graph)로 시각화할 수 있습니다. 새로운 팀원에게 이 파일을 건네주면 30초 만에 시스템을 이해할 수 있습니다. 흩어져 있는 15개의 AGENT.md 파일로 이 작업을 시도해 보세요.

비교 항목	설정 파일들 (Config files)	AgenTopology
플랫폼 전환	모든 것을 다시 작성	--target 변경
에이전트 추가	3개의 도구에 걸쳐 5~12개 파일 업데이트	.at 파일에 4줄 추가
아키텍처 확인	6개 디렉토리에 걸친 YAML, JSON, TOML, Markdown 읽기	단 하나의 .at 파일. 또는 visualize 사용
검증 (Validate)	최선의 결과가 나오길 기도하기	29개의 내장 규칙이 배포 전 오류를 포착
온보딩 (Onboard)	"이 15개 파일을 읽고 파악해 보세요"	"이 .at 파일을 읽어보세요"
버전 관리 (Version control)	생성된 47개 파일의 차이(Diff) 확인	단 하나의 .at 파일 차이(Diff) 확인
새로운 도구로 이동	처음부터 다시 시작	--target new-tool

simple-pipeline.at — 연구 → 작성 → 품질 게이트가 포함된 검토 (review)
code-review.at — 보안 스캐닝이 포함된 멀티 에이전트 (multi-agent) 코드 리뷰
data-processing.at — 배치 처리 (batch processing) 및 미터링 (metering)이 포함된 ETL 파이프라인
scheduled-monitor.at — 예약된 상태 확인 (health checks)이 포함된 모니터링 시스템
openclaw-assistant.at — 라우팅 (routing) 및 스케줄링 (scheduling)이 포함된 고객 지원

agentopology validate <file> .at 파일 검증 (82개 규칙)
agentopology scaffold <file> --target <t> 플랫폼 설정 생성
agentopology sync <file> --target <t> --dir <d> 플랫폼 파일을 .at로 다시 동기화
...

기여를 환영합니다. 시작하기 가장 쉬운 방법은 다음과 같습니다:

• 새로운 예시 토폴로지 (topology) 추가
• 바인딩 (binding) 개선
• 테스트 추가
• 문서 작성

문법 (Grammar) 및 AST 변경 사항은 RFC가 필요합니다.

Apache 2.0 — LICENSE를 참조하세요.

Nadav Naveh 제작