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

0.82.0 사용량 제한: sessionUsage

기존 maxInputTokensPerSession, maxOutputTokensPerSession, maxTokenCostUsdPerSession은 limits.sessionUsage로 교체합니다. true를 반환하면 다음 모델 호출 전에 중단합니다.

import { defineAgent } from "eve";

export default defineAgent({
  model: "anthropic/claude-sonnet-5.5",
  limits: {
    sessionUsage: ({ window }) =>
      window.inputTokens - window.cacheReadTokens >= 200_000 ||
      window.outputTokens >= 20_000 ||
      (window.costUsd ?? 0) >= 1.5,
  },
});

• total은 누적 사용량, window는 마지막 Continue 승인 이후 사용량입니다. Continue는 window만 초기화합니다.
• inputTokens는 캐시를 포함합니다. 새 입력량은 cacheReadTokens를 뺍니다. costUsd는 Gateway가 보고한 모델 토큰 비용이며 없을 수 있습니다. 도구·인프라 비용은 포함하지 않습니다.
• 한도를 넘긴 호출은 완료될 수 있습니다. 따라서 위 숫자는 정확한 결제 상한이 아니며 외부 지출 통제도 필요합니다.
• 사람 입력이 가능한 경우 turn.waiting에서 Continue/Stop을 받습니다. Stop은 현재 turn과 위임 트리를 취소하며 세션은 재개 가능합니다. 입력 불가능한 schedule 등은 SESSION_USAGE_LIMIT_REACHED로 실패합니다.
• child는 자기 정책 또는 root 정책을 쓰며 부모 잔여 예산을 자동 배분받지 않습니다. 부모에 합산되는 시점과 취소 시 예외를 함께 검증합니다.

Agent config: limits.

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

기본 형태

import { defineAgent } from "eve";

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

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

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

아래 모델은 라우팅 예입니다. scaffold와 기본 모델은 버전에 따라 달라지므로 운영 배포에서는 검증한 모델 ID와 옵션을 명시합니다.

모델 라우팅 전략

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

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

모델 선택 매트릭스

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

modelOptions는 provider tuning 계층이다

현재 modelOptions는 providerOptions와 promptCache를 받습니다. 공통 reasoning effort는 defineAgent의 별도 reasoning 필드로 설정하고, provider별 제어가 필요하면 modelOptions.providerOptions를 사용합니다.

운영 규칙:

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

outputSchema: 호출 turn의 계약

0.82.0의 defineAgent에는 outputSchema 필드가 없습니다. 구조화 출력은 client의 session 생성/메시지 turn 또는 workflow에서 여는 child session의 send()에 요청합니다. 이 schema는 해당 turn에만 적용됩니다. 도구 자체의 outputSchema는 별도 반환값 검증 계약입니다.

import { Client } from "eve/client";
import { z } from "zod";

const riskSchema = z.object({
  risk: z.enum(["low", "medium", "high"]),
  requiredApprovals: z.array(z.string()),
  rationale: z.string(),
});
type RiskReview = z.infer<typeof riskSchema>;
const client = new Client({ host: "http://127.0.0.1:2000" });
const { response } = await client.sessions.create<RiskReview>({
  message: "Review the proposed operation.",
  outputSchema: riskSchema,
});
const result = await response.result();
if (!result.data) throw new Error("No structured result was produced.");
console.log(result.data.risk);

서버가 schema를 검증합니다. client의 generic 타입 지정 자체가 별도 런타임 재검증은 아니며, 결과가 없으면 data는 undefined일 수 있습니다. 실제 원격 host는 route 인증을 구성한 뒤 사용합니다.

Client output schema.

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

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

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

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

Compaction 정책 설계

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

Experimental flags

0.11 계열의 experimental.codeMode와 ExperimentalWorkflow를 현재 설정·export로 복사하지 않습니다. 현재 모델 생성 오케스트레이션은 eve/tools/workflow의 소문자 workflow() factory를 사용합니다. 작성자가 만든 durable 작업은 defineWorkflowTool과 "use workflow"로 정의합니다.

experimental.workflow의 world·retention·checkpoint batching은 현재 타입과 호환 World 버전을 대조합니다. replay되는 workflow body와 외부 부작용을 실행하는 step의 경계를 지키고 승인은 별도 정책으로 구성합니다.

Workflow tools · Agent config.

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 변경으로 다뤄야 합니다.