Ch1. Eve 멘탈 모델
Eve를 파일시스템 작성 표면, durable workflow, runtime harness, channel protocol로 나누어 이해한다.
핵심 요약
- Eve는 filesystem authoring, compile manifest, runtime harness, channel protocol로 나누어 봐야 합니다.
- Durable 실행은
session -> turn -> step단위로 checkpoint되며, 재실행 가능한 step은 idempotency 기준을 지켜야 합니다. - App runtime, sandbox, channel 책임을 섞지 않는 것이 엔터프라이즈 Eve 설계의 출발점입니다.
Eve를 처음 볼 때는 defineAgent, defineTool, eveChannel 같은 헬퍼가 먼저 눈에 들어옵니다. 하지만 엔터프라이즈 설계에서 더 중요한 건 어떤 코드가 언제 실행되고, 어떤 데이터가 어느 경계를 넘는가입니다.
Eve의 전체 구조는 네 계층으로 나눠 보는 게 가장 실용적입니다.
| 계층 | 담당 | 대표 파일/개념 | 운영자가 보는 질문 |
|---|---|---|---|
| Authoring Surface | 사람이 작성하는 에이전트 표면 | agent/agent.ts, instructions.md, tools/, skills/ | 무엇이 모델에게 보이고, 무엇이 실행 가능한가? |
| Compile Surface | 파일을 안정적인 manifest로 변환 | discoverAgent, compileAgent, .eve/* | 배포 산출물이 실제로 무엇을 포함하는가? |
| Runtime Surface | 한 turn을 모델/도구 루프로 실행 | resolveRuntimeAgentGraph, ToolLoopAgent, harness | 승인, 동적 기능, 컴팩션, 도구 실행은 어디서 일어나는가? |
| Delivery Surface | 외부 사용자가 세션을 시작/재개/관찰 | channels, client, NDJSON stream | 누가 호출했고, 어느 continuation token이 유효한가? |
파일시스템 우선 설계
Eve는 agent identity와 capability identity를 명시 필드가 아니라 경로에서 가져옵니다.
agent/tools/refund_charge.ts -> tool refund_charge
agent/skills/release/SKILL.md -> skill release
agent/connections/linear.ts -> connection linear
agent/subagents/researcher/agent.ts -> subagent researcher이렇게 하면 에이전트 표면이 코드 리뷰에 잘 걸린다는 장점이 있습니다. agent/tools/에 새 파일이 생기면 새 실행 권한이 생긴 것이고, agent/connections/에 새 파일이 생기면 외부 시스템 접근면이 생긴 것입니다. 운영 조직은 “프롬프트가 바뀌었다”와 “실행 권한이 추가되었다”를 파일 경계로 갈라 볼 수 있습니다.
단점도 분명합니다. 파일명이 곧 모델-visible 이름이라, 엔터프라이즈에서는 naming convention이 그대로 운영 표준이 됩니다. delete_user.ts, refund.ts, send_email.ts처럼 위험한 도구는 이름만 봐도 리뷰자가 알아챌 수 있어야 합니다.
내구성은 session, turn, step으로 나뉜다
Eve의 durable model은 세 단계입니다.
| 단위 | 의미 | 설계 포인트 |
|---|---|---|
| Session | 장기 대화 또는 장기 작업 전체 | history, state, sandbox state, continuation token이 이어짐 |
| Turn | 한 번의 사용자 입력과 그로 인한 모든 작업 | model call, tool call, subagent call을 포함 |
| Step | durable checkpoint 단위 | 한 model call과 그 call이 요청한 tool action 묶음 |
관건은 step입니다. 완료된 step은 다시 실행하지 않고 기록된 결과를 replay합니다. 하지만 step 실행 중 프로세스가 끊기면 그 step은 다시 돌 수 있습니다. 그래서 외부 부작용은 다음 중 하나로 막아야 합니다.
- provider idempotency key를 사용한다.
- Eve tool
needsApproval뒤에 둔다. - 외부 DB에 “이미 실행함” ledger를 남긴다.
- tool을 read-only와 write로 분리하고 write는 별도 승인한다.
App runtime과 sandbox를 분리해서 생각한다
Eve 보안 모델의 중심은 app runtime과 sandbox의 분리입니다.
| 항목 | App runtime | Sandbox |
|---|---|---|
process.env | 접근 가능 | 접근 불가 |
| 커스텀 tool 실행 | 여기서 실행 | 실행 안 됨 |
| shell/file built-in | proxy를 호출 | 효과가 여기서 발생 |
| 네트워크 | runtime 권한 | sandbox network policy |
| 비밀값 | 보관 가능 | 전달 금지 |
defineTool({ execute })는 sandbox에서 실행되지 않습니다. Stripe, Linear, 내부 API 같은 privileged call은 app runtime에서 이뤄지고, 모델은 그 결과만 봅니다. 반면 bash, read_file, write_file, glob, grep은 app runtime이 proxy하지만 효과는 /workspace sandbox에 남습니다.
엔터프라이즈 설계 기준은 단순합니다.
| 작업 유형 | 추천 표면 |
|---|---|
| 비밀값이 필요한 API 호출 | custom tool 또는 connection |
| 모델 주도 코드/파일 조작 | sandbox built-in tools |
| 민감한 외부 쓰기 작업 | tool + needsApproval + 감사 hook |
| 사내 데이터 조회 | connection allow-list + least-privilege token |
| 장기 분석/파일 생성 | sandbox workspace + subagent |
채널은 세션 큐가 아니다
Eve의 continuationToken은 일반 메시지 큐 주소가 아니라 “현재 session hook을 깨우는 resume handle”입니다. 같은 session에 여러 메시지를 동시에 보내면 Eve는 완전한 FIFO queue를 보장하지 않습니다. 문서와 구현 모두 session.waiting 이후에 다음 turn을 보내는 패턴을 권장합니다.
실무에서는 다음 구조가 필요합니다.
| 상황 | 설계 |
|---|---|
| Slack/Teams에서 사용자가 연속 입력 | channel/app 계층에서 per-session queue 운영 |
| 승인 버튼과 새 메시지가 동시에 도착 | approval 응답을 먼저 처리하고 새 메시지는 다음 step으로 defer |
| 백오피스 batch가 많은 요청을 밀어 넣음 | session을 나누거나 app-level job queue 사용 |
| tenant별 세션 소유권 필요 | route auth 외에 session ownership ACL 직접 구현 |
고급 사용자가 기억해야 할 한 줄
Eve는 “모델이 코드를 실행하는 프레임워크”가 아니라 파일로 선언한 권한 표면을 durable workflow 위에서 모델이 요청하고, Eve가 승인·격리·기록·재개하는 프레임워크입니다.
이렇게 보면 각 기능이 어디에 놓이는지 선명해집니다.
instructions.md: 항상 켜진 정체성skills/: 필요할 때 로드하는 절차tools/: app runtime에서 실행되는 typed actionconnections/: 외부 MCP/OpenAPI tool providersandbox/: 모델 주도 shell/file 작업의 격리된 workspacechannels/: session 시작, continuation token, delivery 책임hooks/: stream event 이후의 감사/메트릭/동기화evals/: 실제 HTTP session을 구동하는 regression gate
이후 장에서는 이 표면들이 내부 코드에서 어떻게 discovery, compile, runtime graph, workflow step으로 연결되는지 추적합니다.