에이전트 프레임워크AI 개발Extension PointPluginMCPGateway시스템 설계

에이전트 프레임워크 스터디 Day 9: 확장점은 플러그인이 아니라 경계면이다

2026년 6월 19일16분 읽기

예상 읽기 시간: 20~30분

오늘의 목표

Day 1에서는 에이전트를 모델 하나가 아니라 harness, 즉 실행 환경 전체로 봤습니다. Day 2에서는 도구를 계약(contract) 으로 봤고, Day 3에서는 컨텍스트를 실행 상태(state) 로 봤습니다. Day 4에서는 관측 가능성, Day 5에서는 워크플로와 에이전트 판단의 경계, Day 6에서는 사람 개입, Day 7에서는 이벤트와 산출물, Day 8에서는 여러 에이전트의 capability/handoff 계약을 봤습니다.

오늘은 프레임워크를 실제로 키우기 시작할 때 부딪히는 문제입니다.

text

어디를 열어 두어야 확장 가능한가?
어디는 닫아 두어야 안전한가?

처음에는 “플러그인 구조를 만들면 되지 않나?”라고 생각하기 쉽습니다. 하지만 개인 에이전트 프레임워크에서 확장점은 단순히 외부 코드를 꽂는 자리가 아닙니다.

확장점은 기능 추가 지점이 아니라 책임과 권한이 갈리는 경계면이다.

이 말을 이해해야 Hermes, OpenClaw, MCP 서버, 게이트웨이, 크론, 스킬, 메모리, 리뷰 게이트 같은 조각을 아무 데나 섞지 않을 수 있습니다.

1. 플러그인을 많이 열면 확장성이 좋아질까?

프레임워크를 만들다 보면 이런 욕심이 생깁니다.

text

- 모델 provider를 쉽게 바꾸고 싶다.
- 도구를 쉽게 추가하고 싶다.
- 기억 backend를 바꾸고 싶다.
- Discord, Telegram, Slack 같은 플랫폼을 붙이고 싶다.
- cron, webhook, MCP, browser, image, voice를 모두 연결하고 싶다.

그래서 모든 곳에 플러그인 포인트를 만들면 유연해 보입니다. 그런데 실제 운영에서는 반대로 위험해질 수 있습니다.

text

ModelPlugin이 도구 권한까지 만진다.
MemoryPlugin이 임시 작업 상태를 장기 기억에 저장한다.
GatewayPlugin이 사용자 메시지를 세션 계약 없이 직접 실행 API로 보낸다.
ToolPlugin이 secret-bearing 파일을 출력한다.
CronJob이 서비스 재시작까지 자동으로 한다.
ReviewerPlugin이 검증 없이 push를 허용한다.

이건 플러그인 수가 부족해서 생긴 문제가 아닙니다. 경계가 부족해서 생긴 문제입니다.

좋은 확장점은 “뭐든 할 수 있음”이 아닙니다. 오히려 반대입니다.

text

이 확장점은 무엇을 받아도 되는가?
무엇을 절대 보면 안 되는가?
무엇을 변경할 수 있는가?
어떤 결과를 반드시 돌려줘야 하는가?
실패하면 어떤 상태로 남아야 하는가?

즉 확장점은 자유도가 아니라 계약입니다.

2. 에이전트 프레임워크의 핵심 경계면

개인 에이전트 프레임워크를 설계한다면 최소한 아래 경계면을 구분해야 합니다.

text

AgentRuntime
  model_adapter
  prompt_context_builder
  tool_registry
  tool_executor
  memory_provider
  session_store
  scheduler
  gateway_adapter
  artifact_store
  review_gate
  observability_sink

각 경계면의 책임은 다릅니다.

경계면	책임	열어도 되는 것	조심할 것
`model_adapter`	provider/model 호출	OpenAI, Anthropic, local model, router	도구 권한이나 memory write를 만지지 않기
`prompt_context_builder`	system/user/context 조립	skills, memory, environment hints	오래된 상태를 현재 사실처럼 넣지 않기

text

Cron Scheduler:
  run job -> create a session/run -> deliver final output

MCP Server:
  expose scoped tools/resources -> runtime chooses whether to call

Gateway Adapter:
  normalize incoming platform event -> runtime session message

Review Gate:
  inspect diff/checks -> pass/fail verdict -> blocks remote handoff

text

MCP can expose:
  - tools
  - resources
  - prompts
  - capabilities

MCP does not automatically solve:
  - which tool should be available now
  - whether the user allowed this action
  - how to store long-term memory
  - how to verify output
  - how to recover from partial failure

text

Ticket MCP Server:
  allowed:
    - read ticket summary
    - list active work
    - append scoped comment
  not allowed by default:
    - mark done without verification evidence
    - delete tickets
    - expose secrets or raw full session transcripts

text

웹앱/API:
  - 상태 조회
  - 파일/티켓/작업 목록
  - artifact 미리보기
  - 안전한 mutation

Gateway:
  - 사용자 메시지
  - voice/STT/TTS
  - approval/deny
  - clarification
  - platform-specific routing
  - final response delivery

text

App API:
  - read worker/session metadata
  - prepare draft
  - show linked artifacts
  - store local UI state

Gateway bridge:
  - turn confirmed draft into platform/session event
  - preserve approval/clarify/media/session routing
  - deliver final answer through the same conversation model

text

무엇을 기억할 것인가?
무엇은 기억하지 않을 것인가?
기억의 source와 freshness는 어떻게 남길 것인가?
사용자 선호와 작업 상태를 어떻게 분리할 것인가?

text

MemoryWriteRequest:
  kind: user_preference | stable_environment_fact | reusable_rule
  content: string
  source_ref: session | ticket | doc | user_correction
  freshness: durable | review_after_date
  forbidden_if:
    - task_progress
    - ticket_status
    - secret
    - temporary_error

text

ReviewGateInput:
  task_spec
  changed_files
  diff
  untracked_files
  checks
  external_review
  risk_level

ReviewGateOutput:
  passed: true | false
  blocking_issues: [...]
  skipped_checks_with_reason: [...]
  allowed_remote_action: commit | push | pr | none

text

bad:
  if review tool unavailable:
    push anyway

good:
  if OCR unavailable:
    run deterministic checks + focused fallback reviewer
    report review gap explicitly
    block if high-risk findings remain

text

ExtensionPointChecklist
  1. 이 확장점의 입력 타입은 무엇인가?
  2. 출력 타입은 무엇인가?
  3. 실패 상태는 어떻게 표현되는가?
  4. 어떤 저장소를 읽을 수 있는가?
  5. 어떤 저장소를 쓸 수 있는가?
  6. 사용자 승인 없이 가능한 행동은 어디까지인가?
  7. tool output / web content / external event는 데이터로 취급되는가?
  8. trace와 artifact가 남는가?
  9. no-user cron 상황에서도 멈추지 않는가?
  10. 제거해도 시스템이 망가지지 않는가?

text

facts/preferences -> memory
procedures -> skills
work state -> ticket/work ledger/cron output
conversations -> sessions
repeated execution -> cron
human-facing display -> Discord/dashboard/Local UI
secrets -> .env only
settings -> config.yaml
source-code framework changes -> Hermes Agent repo only when explicitly requested

text

interface ModelAdapter {
  generate(messages, tools, options) -> ModelResult
}

interface ToolProvider {
  list_tools(context) -> ToolSchema[]
  execute(tool_call, execution_context) -> ToolResult
}

interface MemoryPolicy {
  classify(candidate) -> allow | reject | skill | ticket | session
  write(memory_item) -> MemoryWriteResult
}

interface SessionStore {
  append(event)
  load(session_id)
  search(query)
}

interface ReviewGate {
  review(task, diff, checks) -> Verdict
}

text

모델은 도구를 직접 실행하지 않는다.
도구 제공자는 memory policy를 우회하지 않는다.
세션 저장소는 장기 기억이 아니다.
리뷰 게이트는 원격 handoff 전에 멈출 수 있다.

text

내 에이전트는 어떤 확장점을 열어 둘 것인가?
그 확장점은 어떤 권한을 절대 갖지 말아야 하는가?
그리고 실패했을 때 무엇을 증거로 남길 것인가?

tool_registry

에이전트 프레임워크 스터디 Day 9: 확장점은 플러그인이 아니라 경계면이다

에이전트 프레임워크 스터디 Day 9: 확장점은 플러그인이 아니라 경계면이다

오늘의 목표

1. 플러그인을 많이 열면 확장성이 좋아질까?

2. 에이전트 프레임워크의 핵심 경계면

오케이징에게 물어보기

포스트 목록

3. 확장점은 호출 방향을 정해야 한다

4. MCP는 도구 확장점이지 전체 운영체제가 아니다

5. 게이트웨이와 앱 API는 같은 것이 아니다

6. 메모리 확장점은 저장소 교체보다 정책이 먼저다

7. 리뷰 게이트는 확장점이지만 우회로가 아니다

8. 확장점 설계 체크리스트

9. OkayJing 관점에서 현재 적용 중인 기준

10. 직접 프레임워크를 만들 때의 최소 구조

마무리: 확장성은 많이 꽂는 능력이 아니라 안전하게 갈라놓는 능력이다