Ch5. agent.ts, 모델, 컴팩션

agent/agent.ts는 Eve 에이전트의 런타임 config입니다. 기본 사용자는 여기서 모델만 고릅니다. 엔터프라이즈 운영자는 여기서 모델 라우팅, 출력 계약, 장기 세션 메모리 정책, experimental 기능 허용 여부를 결정합니다.

기본 형태

import { defineAgent } from "eve";

export default defineAgent({
  model: "anthropic/claude-sonnet-4.6",
});

root agent.ts가 없으면 Eve는 기본 모델을 씁니다. 다만 프로덕션에서는 명시적으로 작성하는 편이 낫습니다. 모델은 품질, 비용, 데이터 처리 경로, provider tool 지원, context window를 가르는 핵심 운영 변수입니다.

공식 agent.ts 문서가 명확히 하는 규칙은 두 가지입니다.

공식 getting-started 기준 scaffold default는 anthropic/claude-sonnet-4.6이고, 공식 예제의 고성능 작업은 anthropic/claude-opus-4.8을 자주 사용합니다. 이 책의 모델 표기는 특정 모델 추천이 아니라 라우팅 방식과 운영 기준을 설명하기 위한 예입니다.

모델 라우팅 전략

Eve는 두 형태의 model definition을 지원합니다.

엔터프라이즈 기본값은 Gateway routed model입니다. 팀 단위로 모델 사용량, fallback, BYOK, 정책을 한곳에 모으기 쉽기 때문입니다. 다만 self-hosted거나 특정 provider option이 필요하면 direct model도 합리적입니다.

모델 선택 매트릭스

기준은 “가장 똑똑한 모델”이 아니라 “해당 tool surface에서 실패 비용이 낮은 모델”입니다.

modelOptions는 provider tuning 계층이다

modelOptions는 provider로 전달되는 옵션 override입니다. temperature, reasoning effort, provider-specific metadata 등이 여기에 들어갈 수 있습니다.

운영 규칙:

• reasoning-heavy agent와 transactional agent를 분리한다.
• 모델 옵션 변경은 prompt 변경과 같은 release gate를 탄다.
• eval result에 모델 id와 옵션을 함께 남긴다.
• provider-specific option은 portability risk로 문서화한다.

outputSchema: task-mode 계약

outputSchema는 interactive conversation의 모든 응답을 강제하는 장치가 아닙니다. Eve 문서 기준으로는 agent/subagent/schedule/remote job 같은 task-mode run에서 structured output을 강제하는 설정입니다. client가 per-turn으로 outputSchema를 보내기도 합니다.

사용하기 좋은 곳:

예:

import { defineAgent } from "eve";
import { z } from "zod";

export default defineAgent({
  description: "Review a proposed operation and return risk level and required approvals.",
  model: "anthropic/claude-opus-4.8",
  outputSchema: z.object({
    risk: z.enum(["low", "medium", "high"]),
    requiredApprovals: z.array(z.string()),
    rationale: z.string(),
  }),
});

Compaction은 장기 세션 운영 정책이다

Eve의 default harness는 context window에 가까워지면 과거 turns를 요약합니다. 기본 threshold는 90%이고, agent.ts에서 낮출 수 있습니다.

export default defineAgent({
  model: "anthropic/claude-opus-4.8",
  compaction: {
    thresholdPercent: 0.75,
  },
});

컴팩션은 비용 절감 기능이면서 동시에 risk surface입니다. summary가 잘못되면 장기 세션의 사실 기반이 통째로 흔들립니다.

Compaction 정책 설계

Eve는 framework tool state 일부를 컴팩션 후 재주입합니다. 하지만 domain-specific memory까지 자동으로 보장하지는 않습니다. defineState, external DB, artifact files를 함께 써야 합니다.

Experimental flags

공식 agent.ts 문서는 experimental.codeMode를 언제든 사라지거나 바뀔 수 있는 opt-in flag로 설명합니다. ExperimentalWorkflow는 Dynamic Workflows 문서가 다루는 별도 도구입니다. 둘 다 쓸모는 크지만 안정성 계약은 약합니다.

실무 기준:

• feature flag로 제한한다.
• eval을 일반 tool-call agent보다 더 촘촘히 둔다.
• code-generated orchestration 결과를 trace로 저장한다.
• 외부 side effect tool은 workflow/code mode에서 직접 닿지 않게 설계한다.

Hosted build packaging

build.externalDependencies는 hosted output packaging을 제어합니다. 특정 package를 bundle하지 않고 runtime dependency로 남깁니다.

주의할 점:

• dependency를 external로 둔다고 권한 검토가 끝나는 것은 아니다.
• third-party SDK의 network/data behavior는 별도 보안 리뷰 대상이다.
• Vercel/self-host 환경에서 같은 package가 설치되는지 확인해야 한다.

agent.ts 리뷰 체크리스트

agent.ts는 작아 보여도 운영상 가장 무게 있는 config 파일입니다. 모델 변경은 UI 문구 수정이 아니라 서비스 behavior 변경으로 다뤄야 합니다.