Ch10. Subagents, Workflows, Remote Agents

Eve의 subagent는 단순 함수 호출이 아니라 별도 session에서 도는 delegation 단위입니다. 고급 설계에서는 subagent를 병렬 처리 도구이자 권한 축소 경계로 사용합니다.

두 종류의 subagent

built-in agent는 같은 파일 작업을 병렬로 나누는 데 좋습니다. declared subagent는 역할과 권한을 분리하는 데 좋습니다.

Built-in agent tool

모든 agent에는 기본적으로 agent tool이 있습니다.

{
  message: string;
  outputSchema?: object;
}

특징:

• parent history를 자동으로 보지 않습니다.
• parent가 message에 필요한 정보를 넣어야 합니다.
• parent sandbox를 공유합니다.
• child가 쓴 파일은 parent에게 보입니다.
• state는 fresh합니다.

코딩 에이전트에서 이 도구가 특히 쓸모 있습니다. 파일 A/B/C 수정 작업을 병렬 child에게 나눠 주고 parent가 결과를 합칠 수 있습니다.

Declared subagent

import { defineAgent } from "eve";

export default defineAgent({
  description: "Investigate ambiguous questions before the parent responds.",
  model: "anthropic/claude-opus-4.8",
});

description은 필수입니다. parent model은 이 설명을 보고 delegation 여부를 결정합니다.

구조:

agent/subagents/researcher/
├── agent.ts
├── instructions.md
├── tools/
├── skills/
├── connections/
├── hooks/
├── sandbox/
└── subagents/

Declared subagent에는 channels/와 schedules/가 없습니다. entrypoint는 root agent가 소유합니다.

격리 경계

보안상 declared subagent가 더 중요합니다. 예를 들어 researcher에는 read-only connection만 주고, operator에는 approval-gated write tool만 주는 구조가 가능합니다.

Parent가 보는 것

Parent stream에는 subagent.called와 subagent.completed가 나타납니다. child의 자세한 progress는 subagent.called.data.childSessionId로 child stream에 attach해야 합니다.

운영 UI에서 parent trace만 보여주면 부족합니다. 멀티에이전트 UI는 child session tree를 펼칠 수 있어야 합니다.

Output schema로 delegation 계약 만들기

Subagent 호출은 outputSchema를 받을 수 있습니다. parent가 downstream 로직을 해야 한다면 string summary 대신 structured output을 요구합니다.

const riskSchema = {
  type: "object",
  properties: {
    risk: { enum: ["low", "medium", "high"] },
    reason: { type: "string" },
  },
  required: ["risk", "reason"],
};

패턴:

Remote agents

defineRemoteAgent는 다른 Eve deployment를 subagent처럼 호출합니다.

import { defineRemoteAgent } from "eve";
import { vercelOidc } from "eve/agents/auth";

export default defineRemoteAgent({
  url: "https://weather-agent.example.com",
  description: "Answers weather and forecast questions.",
  auth: vercelOidc(),
});

Remote dispatch는 비동기입니다.

1. parent가 remote POST /eve/v1/session에 task-mode session을 시작한다.
2. parent turn은 durable하게 park된다.
3. remote가 terminal callback을 post한다.
4. parent가 resume되어 결과를 tool result로 받는다.

원격 호출은 조직/도메인 경계에 적합합니다. 예를 들어 보안팀이 소유한 risk agent, 데이터팀이 소유한 warehouse agent를 각각 별도 배포로 운영할 수 있습니다.

Remote auth

Outbound auth helper:

Receiving side도 route auth를 올바르게 구성해야 합니다. defineRemoteAgent의 auth는 outbound header일 뿐, remote가 이를 검증하지 않으면 의미가 없습니다.

Experimental Workflow

ExperimentalWorkflow는 모델이 JavaScript로 subagent orchestration을 작성하게 하는 opt-in tool입니다.

export { ExperimentalWorkflow as default } from "eve/tools";

이 tool이 할 수 있는 일은 subagent orchestration뿐입니다. 파일, shell, network, arbitrary import는 없습니다. QuickJS sandbox 안에서 tools.<subagent>()만 호출하는 구조입니다.

사용하기 좋은 경우:

• metric 목록을 먼저 결정하고 각 metric을 analyst subagent에 fan-out
• 여러 reviewer 결과를 취합해 final recommendation 생성
• remote agent 여러 개를 map-reduce처럼 호출

피해야 할 경우:

• 외부 side effect tool orchestration
• shell/file 작업을 JS로 제어하려는 목적
• deterministic workflow가 필요한 regulated process

오케스트레이션 패턴

평가 기준

Subagent는 eval에서 반드시 별도 검증해야 합니다.

Subagent는 품질을 높이지만 그만큼 복잡도도 키웁니다. “역할이 다른가, 권한이 다른가, 병렬성이 필요한가” 중 하나가 명확할 때만 분리합니다.