하위 에이전트

하위 에이전트 (1.0) (Subagents)

귀속, 소유, 중첩, 병렬 실행, 상태, 종료를 다루는 페이지예요. 에이전트는 실행의 일부를 다른 에이전트에게 위임할 수 있는데, 위임이 만든 모든 것이 같은 스트림으로 이동하므로 소비자는 실행을 재생하지 않고도 어느 일이 누구 것인지 알아야 합니다.

출처: 문서

본문

에이전트는 실행의 일부를 다른 에이전트에게 위임할 수 있습니다. 위임이 만든 모든 것이 같은 스트림으로 이동하므로, 소비자는 실행을 재생하지 않고도 어느 작업이 누구에게 속하는지 알아야 합니다.

귀속 (Attribution)

subagentRunId는 하위 에이전트의 한 호출을 식별합니다. 하위 에이전트가 만든 이벤트는 그것을 담고, 부모 에이전트가 만든 이벤트는 담지 않습니다. 없는 subagentRunId는 부모 에이전트를 의미하며, null로 철자되면 안 됩니다(MUST NOT).

id는 에이전트가 아니라 호출을 식별합니다. 생산자는 실행 안에서 같은 하위 에이전트라도 두 번째 호출에 subagentRunId를 재사용하면 안 됩니다(MUST NOT) — 두 번째 호출은 자신만의 id를 얻습니다. 일시 중단된 호출이 이어질 때 id는 나중 실행에 다시 나타날 수 있습니다(MAY).

어떤 이벤트가 귀속을 담을 수 있는지는 구조적 질문이고, 스키마가 답합니다. 독립 이벤트 — STEP_*, CUSTOM, RAW, 상태 이벤트 — 의 태그를 출처(provenance)로 읽으세요: 그것은 누가 이벤트를 만들었는지 기록하지, 생산자가 이벤트가 건드리는 것의 개인 사본을 소유한다는 뜻이 아닙니다.

수명주기 (Lifecycle)

SUBAGENT_STARTED는 호출을 알리고, SUBAGENT_FINISHED는 그것을 닫으며, SUBAGENT_ERROR는 실패를 보고합니다. 셋 다 그들이 다루는 subagentRunId를 담고, 생산자는 그것을 생략하면 안 됩니다(MUST NOT).

  • 호출을 알리는 생산자는 그 호출에 귀속되는 어떤 이벤트보다 먼저 그렇게 해야 합니다(MUST).
  • 이미 활성인 id의 호출을 알리면 안 됩니다(MUST NOT).
  • 이 실행에서 이미 끝난 호출의 id를 재사용하면 안 됩니다(MUST NOT).
  • 생산자가 알리는 모든 호출은 실행이 끝나기 전에 SUBAGENT_FINISHED 또는 SUBAGENT_ERROR로 닫혀야 합니다(MUST).

생산자는 아무것도 알리지 않고 이벤트에 귀속을 붙일 수 있습니다(MAY). 그런 스트림은 소비자에게 어떤 작업이 함께 속하는지는 말하지만 호출이 언제 시작·끝났는지는 말하지 않으며, 소비자는 그것을 받아들여야 합니다(MUST). subagentRunId는 그 자체로 의미가 있고, 수명주기 이벤트를 요구하면 보고할 수 없는 생산자에게 그룹화가 불가능해지기 때문입니다. 수명주기를 보고할 수 있는 생산자는 그렇게 해야 합니다(SHOULD), 그러면 소비자는 호출을 도착하는 이벤트에서 추론하는 대신 실행 중으로 표시할 수 있습니다.

SUBAGENT_ERROR는 실행이 아니라 호출을 끝냅니다. 부모 에이전트는 실패한 하위 에이전트를 처리하고 계속할 수 있습니다(MAY). 그게 RUN_ERROR가 아닌 이유입니다.

하위 에이전트의 모델 호출은 실행의 것입니다. 어떤 하위 에이전트 이벤트도 토큰 사용량을 담지 않고, 실행의 종료 이벤트가 하위 에이전트를 포함한 전체 실행의 사용량을 보고합니다.

SUBAGENT_FINISHED는 세그먼트가 왜 끝났는지 보고합니다. 없는 outcome은 성공을 의미합니다. 일시 중단(suspended) outcome은 호출이 외부 입력을 기다리며 멈춘다는 뜻입니다 — 이 스트림에서는 종료지만 호출을 위해서는 아니며, 나중 실행이 같은 id로 계속할 수 있습니다(MAY). 생산자는 스키마가 설명하지 않는 outcome 값을 보내면 안 되고(MUST NOT), 성공 outcome에 인터럽트 id를 붙이면 안 됩니다(MUST NOT).

소유 (Ownership)

귀속은 조언이 아닙니다. 어떤 항목이 소유자 아래에서 열리면, 그것을 이어가는 모든 이벤트는 그 소유자에 동의해야 합니다(MUST).

  • TEXT_MESSAGE_CONTENT 또는 TEXT_MESSAGE_END는 메시지를 연 TEXT_MESSAGE_START와 불일치하는 subagentRunId를 담으면 안 됩니다(MUST NOT). 태그를 생략할 수 있습니다(MAY). 태그 없는 이어짐은 연 사람이 소유하는 무엇이든 이어가고, 연 사람만 태그하는 생산자도 여전히 적합합니다.
  • 같은 규칙이 추론 메시지, 그 TOOL_CALL_START에 대한 도구 호출, 그리고 이를 연 스냅샷에 대한 activity 메시지에도 성립합니다.
  • STEP_FINISHED는 그것이 닫는 STEP_STARTED와 같은 귀속을 담아야 합니다(MUST). 단계는 소유자별입니다. 부모와 하위 에이전트는 각자 같은 이름의 단계를 동시에 열 수 있고(MAY), 각자 자기 것을 닫습니다.

소비자는 연 사람과 불일치하는 태그를 가진 이어짐을 거부해야 합니다(MUST). 받아들이면 한 생산자의 콘텐츠를 다른 생산자의 메시지에 덧붙이게 되는데, 소비자가 이후에 그것을 감지할 방법이 없습니다. 태그가 없는 이어짐은 불일치가 아니며 받아들여져야 합니다(MUST).

도구 호출은 그것을 담은 메시지의 귀속을 상속합니다. 생산자는 그 메시지가 다른 소유자에게 귀속되는 동안 도구 호출을 한 소유자에게 귀속시키면 안 됩니다(MUST NOT).

중첩과 병렬 (Nesting and parallelism)

하위 에이전트는 스스로 위임할 수 있습니다(MAY). SUBAGENT_STARTED의 parentSubagentRunId는 이 호출을 만든 호출을 이름 붙입니다. 없으면 부모 에이전트가 직접 만들었습니다. 생산자는 이 실행에서 알리지 않은 부모 호출을 이름 붙이면 안 됩니다(MUST NOT).

호출들은 병렬로 실행될 수 있고(MAY), 그 이벤트는 임의로 인터리브될 수 있습니다(MAY). 각 호출의 항목은 따로 추적되므로, 두 하위 에이전트가 동시에 메시지를 스트리밍할 수 있습니다. 소비자는 한 호출의 이벤트가 연속적이라고 가정하면 안 되고(MUST NOT), 다른 호출이 끝났다고 해서 한 호출의 항목을 닫으면 안 됩니다(MUST NOT).

상태 (State)

상태는 실행 범위(run-scoped)입니다. 하위 에이전트가 보내는 STATE_SNAPSHOT이나 STATE_DELTA는 부모 에이전트의 것과 정확히 같이 실행의 상태를 갱신하고, 소비자는 그렇게 적용해야 합니다(MUST).

상태 이벤트의 subagentRunId는 출처입니다. 어떤 호출이 업데이트를 만들었는지 기록하지, 하위 에이전트가 자신만의 개인 상태를 소유한다는 뜻은 아닙니다. 소비자는 하위 에이전트가 보냈기 때문에 실행의 상태에서 업데이트를 보류하면 안 됩니다(MUST NOT). 이 프로토콜에는 하위 에이전트별 상태가 없습니다.

종료 (Termination)

호출이 여전히 활성인 동안 실행이 끝나면 안 됩니다(MUST). 열린 호출을 두고 작업 끝에 도달하는 생산자는 버그가 있습니다. 호출이 끝났는데 보고되지 않았거나, 끝나지 않았는데 실행이 끝난 것이죠.

RUN_ERROR는 모든 것을 끝냅니다. 실행이 오류가 나면 소비자는 모든 열린 호출이 버려진 것으로 취급해야 하며(MUST), 그 어떤 것에도 닫는 이벤트를 기대하면 안 됩니다(MUST NOT).

실행이 인터럽트 outcome으로 끝날 때, 그것이 운반하는 인터럽트는 귀속될 수 있습니다(MAY). subagentRunId로 태그된 인터럽트는 그 호출 안에서 발생했습니다. 태그 없는 것은 부모 에이전트의 것입니다. 자손이 인터럽트해서 일시 중단된 호출은 자기 인터럽트를 소유하지 않으므로, 일시 중단 outcome은 인터럽트 id를 전혀 담지 않을 수 있습니다(MAY).

더 알아보기 (Learn more)