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
approval뒤에 둔다. - 외부 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 + approval + 감사 hook |
| 사내 데이터 조회 | connection allow-list + least-privilege token |
| 장기 분석/파일 생성 | sandbox workspace + subagent |
채널은 세션 큐가 아니다
현재 메시지 전송은 기본 turnPolicy: "steer"로 진행 중 turn을 조정하며, "queue"로 현재 turn 이후 처리를 선택할 수 있습니다. 구조화된 inputResponses로 승인 요청을 지정합니다. 0.11 계열의 continuation token만으로 현재 메시지 계약을 설명하지 않습니다. 현재 세션 문서를 기준으로 client와 server 버전을 함께 맞춥니다.
실무에서는 다음 구조가 필요합니다.
| 상황 | 설계 |
|---|---|
| Slack/Teams에서 사용자가 연속 입력 | steer/queue 선택과 현재 요청자의 메시지 순서 확인 |
| 승인 버튼과 새 메시지가 동시에 도착 | inputResponses의 대상과 새 메시지의 승인 취소·steering 동작 검증 |
| 백오피스 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으로 연결되는지 추적합니다.