# 다중 에이전트 조정

여러 LLM 에이전트가 관련 작업을 수행할 때, Synapse는 조정 계층 — 공유
메모리, 작업 할당, 비동기 채팅 — 을 제공합니다.

## 패턴

### 패턴 1: 공유 마인드 (단일 진실 소스)

모든 에이전트가 하나의 Mind Key를 공유합니다. 동일한 메모리 저장소를
읽고/씁니다.

```
┌──────────┐  ┌──────────┐  ┌──────────┐
│ Agent A  │  │ Agent B  │  │ Agent C  │
└────┬─────┘  └────┬─────┘  └────┬─────┘
     │             │             │
     └─────────────┼─────────────┘
                   ▼
           ┌──────────────┐
           │ Shared Mind  │
           │  (one key)   │
           └──────────────┘
```

**사용 사례:** 한 프로젝트에서 작업하는 소규모 에이전트 팀.

**설정:**

```bash
# All agents use the same Mind Key
export SYNAPSE_MIND_KEY=mk_shared_key...
```

**작업을 통한 조정:**

```python
# Agent A creates a task
create_task("Review PR #42", priority="high")

# Agent B picks it up
tasks = list_tasks(status="pending")
if tasks:
    task = tasks[0]
    update_task(task["id"], status="in_progress")
    # ... do work ...
    update_task(task["id"], status="done")
```

### 패턴 2: 전문화된 마인드 (격리된 컨텍스트)

각 에이전트는 자체 마인드를 가집니다. 공유 "조정" 마인드를 통해 통신합니다.

```
┌──────────┐  ┌──────────┐  ┌──────────┐
│ Coder    │  │ Reviewer │  │ Deployer │
│ Agent    │  │ Agent    │  │ Agent    │
└────┬─────┘  └────┬─────┘  └────┬─────┘
     │             │             │
     ▼             ▼             ▼
┌─────────┐  ┌─────────┐  ┌─────────┐
│ Mind C  │  │ Mind R  │  │ Mind D  │
└─────────┘  └─────────┘  └─────────┘
     │             │             │
     └─────────────┼─────────────┘
                   ▼
           ┌──────────────────┐
           │ Coordination Mind│
           │ (shared)         │
           └──────────────────┘
```

**사용 사례:** 다른 전문 분야 (코딩, 리뷰, 배포)를 가진 에이전트.

**설정:**

```bash
# Coder agent
SYNAPSE_MIND_KEY=mk_coder... MCP_TRANSPORT=stdio npx synapse-mcp-api@latest

# Reviewer agent
SYNAPSE_MIND_KEY=mk_reviewer... MCP_TRANSPORT=stdio npx synapse-mcp-api@latest

# Deployer agent
SYNAPSE_MIND_KEY=mk_deployer... MCP_TRANSPORT=stdio npx synapse-mcp-api@latest
```

**공유 마인드를 통한 조정:**

```python
# Coder stores "ready for review"
COORDINATION_KEY = "mk_coordination..."
requests.post(f"{URL}/memory",
    headers={"Authorization": f"Bearer {COORDINATION_KEY}"},
    json={
        "category": "project",
        "key": "pr_42_ready",
        "content": "PR #42 is ready for review. Branch: feature/docs-system",
        "tags": ["review", "pr-42"],
        "priority": "high"
    })

# Reviewer polls for review requests
r = requests.get(f"{URL}/memory/search?q=ready+for+review",
    headers={"Authorization": f"Bearer {COORDINATION_KEY}"})
```

### 패턴 3: 허브 앤 스포크 (오케스트레이터)

중앙 오케스트레이터 에이전트가 워커 에이전트에게 작업을 할당합니다.

```
        ┌──────────────┐
        │ Orchestrator │
        │    Agent     │
        └──────┬───────┘
               │
    ┌──────────┼──────────┐
    ▼          ▼          ▼
┌──────┐  ┌──────┐  ┌──────┐
│Worker│  │Worker│  │Worker│
│  A   │  │  B   │  │  C   │
└──────┘  └──────┘  └──────┘
```

**사용 사례:** 병렬 작업이 있는 복잡한 워크플로우.

**구현:**

```python
# Orchestrator
class Orchestrator:
    def assign_task(self, worker_id, task_description):
        # Store task in worker's mind (or shared coordination mind)
        create_task(task_description, priority="high")
        # Notify worker via chat
        reply(f"@{worker_id}: New task — {task_description}")
    
    def check_progress(self):
        tasks = list_tasks(status="in_progress")
        for t in tasks:
            print(f"{t['title']}: {t['status']}")

# Workers poll for assigned tasks
class Worker:
    def run(self):
        while True:
            tasks = list_tasks(status="pending")
            for t in tasks:
                if assigned_to_me(t):
                    update_task(t["id"], status="in_progress")
                    result = do_work(t)
                    update_task(t["id"], status="done")
                    reply(f"Completed: {t['title']}")
            time.sleep(60)
```

## 채팅을 통한 조정

에이전트는 채팅 시스템을 통해 통신할 수 있습니다:

```python
# Agent A sends to Agent B
reply("@agent-b: Can you review my PR?")

# Agent B polls and responds
for msg in poll_messages():
    if "@agent-b" in msg["content"]:
        reply(f"@agent-a: Sure, looking at it now.")
```

> [!NOTE]
> 채팅 메시지는 역할 태그가 지정됩니다. 에이전트 간 메시지의 경우
> role=agent, 사람-에이전트의 경우 role=human으로 설정하십시오.

## 변수를 통한 조정

경량 조정 (잠금, 플래그)을 위해 변수 사용:

```python
# Acquire a lock
def acquire_lock(name):
    r = requests.post(f"{URL}/var",
        headers={"Authorization": f"Bearer {KEY}"},
        json={"key": f"lock_{name}", "value": "acquired"})
    return True

def release_lock(name):
    requests.delete(f"{URL}/var/lock_{name}",
        headers={"Authorization": f"Bearer {KEY}"})

# Use
if acquire_lock("deploy"):
    try:
        deploy_to_production()
    finally:
        release_lock("deploy")
```

## 모범 사례

> [!TIP]
> - **관심사별로 별도 마인드 사용** — 코더와 리뷰어 메모리를 혼합하지 마십시오
> - **채팅에서 에이전트 태그** — 명확한 주소 지정을 위해 `@agent-name`
> - **작업 할당에 작업 사용** — 채팅이 아님 (채팅은 논의용)
> - **멱등성 구현** — 에이전트가 실패한 작업을 재시도할 수 있음
> - **모든 것 로그** — 감사 가능성을 위해 결정을 메모리에 저장

## 다음 단계

- [영구 LLM 에이전트](/docs/guides/persistent-llm-agent)
- [LLM Cookbook](/docs/llm-cookbook/session-start-pattern)
- [웹훅 자동화](/docs/guides/webhook-automation)