주요 변경사항

주요 변경사항 (Key Changes)

1.0이 0.x 계열의 프로토콜에 비해 무엇을 바꾸는지 설명해 드릴게요 — 1.0 기준이에요. 0.x를 알고 있고 전체 문서보다 차이점을 원하는 리뷰어를 위한 페이지예요. 정보 제공용이며, 연결된 페이지들이 바로 스펙입니다.

출처: 문서

본문

이 페이지는 1.0이 0.x 계열의 프로토콜에 비해 만드는 행동 변경을 나열해요. 0.x를 알고 차이점을 원하는 리뷰어를 위한 것이지, 전체 문서를 위한 게 아니에요. 정보 제공용이며, 연결된 페이지들이 바로 스펙입니다.

주요 변경

  1. 스펙이 존재해요. 0.x는 형태를 정의했고, 행동은 TypeScript 클라이언트에 살았어요. 이 페이지들의 규칙 — 순서, 알 수 없음 대 형식 오류, 경고, 귀속 — 은 이제 규범적이며, BCP 14 언어로 쓰였고, schema가 구조에 권위가 있고 이 문서가 행동에 권위가 있어요.

  2. 실행이 어떻게 끝났는지 보고합니다. RUN_FINISHED는 선택적 outcome을 담아요: 없거나 success면 성공이고, 인터럽트 outcome은 실행이 무엇을 기다리는지 담으며, cancelled outcome은 완료 전에 의도적으로 멈춘 실행을 표시합니다. 그것과 함께 Interrupt, run input의 재개 항목, interrupt–resume 패턴이 옵니다. outcomes가 존재하기 전에 쓰인 모든 프로듀서는 이미 적합해요.

  3. 서브에이전트. 위임된 작업은 그것을 담을 수 있는 이벤트의 subagentRunId로 귀속되고, 선택적으로 SUBAGENT_STARTED로 발표되고 SUBAGENT_FINISHED나 SUBAGENT_ERROR로 닫히며, 소유·중첩·병렬·종료 규칙이 따라옵니다.

  4. 추론이 thinking을 대체해요. 0.x의 THINKING_* 이벤트는 reasoning 패밀리로 은퇴합니다: 스팬, messageId로 짝지어지는 스트리밍 추론 메시지, 컨슈머가 읽지 않고 저장·반환하는 프로바이더 산출물을 위한 REASONING_ENCRYPTED_VALUE. 은퇴된 형태는 버려지는 것이 아니라 호환성 경계에서 번역됩니다.

  5. 액티비티 이벤트. ACTIVITY_SNAPSHOT과 ACTIVITY_DELTA는 콘텐츠가 객체인 메시지로 구조화된 진행을 실어 나르며, JSON Patch로 수정됩니다.

  6. 알 수 없음 대 형식 오류, 규범적으로. 인식되지 않은 이벤트, 필드, 유니언 멤버는 번역에서 강제까지 살아남는데, 강제가 알 수 없는 이벤트를 버리고 알 수 없는 멤버를 떼어내며 가면서 경고합니다; 형식이 잘못된 알려진 값은 치명적이에요. 번역자들이 기회를 가지기 전에 아무것도 제거되지 않고, 두 전송이 하나의 처리 파이프라인을 먹이며, 그 파이프라인이 청크 필드에 대한 유일하게 인정된 좁아짐도 명시합니다.

  7. 청크 형태에 규칙이 있어요. 첫 청크는 여는 데 요구되는 것을 담아야 합니다(MUST)(텍스트의 messageId와 역할 의미론, 도구 호출의 toolCallId와 toolCallName); 이후 청크는 그것들을 생략할 수 있어요(MAY); 충돌하는 값으로 오프너 필드를 반복하는 연속은 치명적이에요(streaming pattern).

  8. 이진 와이어. HTTP + Protobuf 바인딩이 명시됩니다 — 미디어 타입으로 협상되고, 4바이트 길이 프리픽스 프레임, 같은 스키마에서 생성되며, 공유 바이트 코퍼스로 구현 간 패리티가 고정됩니다.

  9. Capabilities가 스키마 안에 있어요. SDK들이 세 개의 손으로 쓴 사본으로 담던 AgentCapabilities 선언은 이제 한 번, 스키마에 정의되고 모든 SDK를 위해 생성됩니다. 그 의미론이 명시됩니다: 생략은 미선언이고, 선언은 정보 제공용이며 스트림이 권위가 있고, 획득은 의도적으로 구현에 맡겨집니다(Capabilities). 서브에이전트 목록은 subagentRunId와 일치하도록 subagents로 철자되며; 이전 subAgents 키는 읽히지 않아요.

  10. 도구 결과가 콘텐츠 파트를 담아요. TOOL_CALL_RESULT.content와 그것이 만드는 도구 메시지는 사용자 메시지가 담는 문자열이나 같은 파트의 정렬된 목록을 받아, 도구가 그것을 문자열로 인코딩하지 않고 문서, 이미지, 검색 히트를 반환할 수 있게 해요(Tool calls). 파트들은 그것을 위해 이름이 바뀝니다 — InputContent → ContentPart, TextInputContent → TextPart, ImageInputContent → ImagePart 등, InputContentSource → PartSource와 DataSource, UrlSource — 방향으로 이름 붙은 파트는 다른 방향으로 여행하는 순간 잘못 이름 붙은 것이기 때문이에요. 와이어는 변하지 않아요: 모든 type 값은 같고, 정의 이름과 앵커만 움직이며, SDK들은 옛 이름을 별칭으로 유지합니다. 모든 파트는 선택적 id를 얻고, 텍스트 파트는 미디어 파트가 이미 가졌던 metadata를 얻어요. ReasoningPart, ToolCallPart, AssistantPart는 어시스턴트 메시지도 파트를 담게 되는 릴리스에 예약됩니다.

사소한 변경

  1. 실행 입력의 tools와 context는 선택적이에요: 없음과 빈 것은 같은 것을 뜻해요(Run input).
  2. 메타데이터 병합 의미론이 규범적이에요: 키별로, 마지막 쓰기가 이기고, 재귀 없음, 패밀리별 병합 대상; ag-ui 키는 예약됩니다(Metadata).
  3. 없음은 없음: 선택적 필드는 생략되고, 절대 null이 아니에요(The event model).
  4. RUN_FINISHED와 RUN_ERROR는 프로바이더별 토큰 사용량을 하나의 회계로 담을 수 있어요(MAY): 입력과 출력 수는 총계이고, 캐시·추론 토큰은 그것의 일부이며, 캐시 읽기와 캐시 쓰기는 별도로 보고되고, 사용량은 실행 경계를 따라요 — 서브에이전트의 호출은 포함하고, 자식·재개된 실행의 호출은 제외(Runs and steps).
  5. 프런트엔드 도구 호출에서 멈추는 실행은 인터럽트가 아니라 성공으로 끝나고, 성공 outcome은 답하지 않은 채 둔 호출을 pendingToolCallIds에 이름 붙일 수 있어요(MAY)(Tool calls).
  6. 입력 메시지는 멀티모달 콘텐츠 파트(텍스트, 이미지, 오디오, 비디오, 문서)를 URL, 인라인 데이터, 또는 모델 프로바이더에 이미 업로드된 바이트를 위한 1.0의 새 file 소스로 담을 수 있어요(MAY)(Run input).
  7. TOOL_CALL_RESULT는 그 자체로 메시지이고, 그것이 답하는 호출을 재열지 않아요(Tool calls).
  8. RUN_FINISHED 이후의 늦은 RUN_ERROR가 인정됩니다 — 성공이 이미 보고된 뒤 표면화된 실패를 보고하죠(Runs and steps).
  9. 컨슈머는 그것이 거부한 스트림을 자기 실패를 보고하는 실행과 분리하고, "실행을 실패로 취급"이 정의됩니다: 표면화하고, 절대 성공을 보고하지 않으며, API 형태는 구현에 맡겨집니다(Runs and steps).
  10. 프로토콜 버전은 밴드 내(in-band)로 여행해요: 컨슈머는 RunAgentInput.protocolVersion에 자기 것을 선언하고, 프로듀서는 RUN_STARTED.protocolVersion에 자기 것으로 답하며, 부재는 버전 관리 이전의 피어를 식별합니다(Versioning).

더 알아보기 (Learn more)