Capabilities

Capabilities (능력 선언)

실행(run) 전에 에이전트가 자신에 대해 무엇을 선언하는지, 선언이 무엇을 의무화하고 무엇을 의무화하지 않는지 설명해 드릴게요 — 1.0 기준이에요. 실행은 컨슈머에게 에이전트가 무엇을 했는지 보여주고, capabilities는 에이전트가 무엇을 할 수 있는지를 요청 전에 알려줍니다.

출처: 문서

본문

실행은 컨슈머에게 에이전트가 무엇을 했는지 보여줘요. Capabilities는 컨슈머가 무엇이든 하게 요청하기 전에 에이전트가 무엇을 할 수 있는지 배우게 합니다: 추론을 스트리밍하는지, 승인을 위해 멈출지, 어떤 모달리티를 받아들이는지, 어떤 서브에이전트에 위임할 수 있는지. 애플리케이션은 시행착오로 지원을 알아내는 대신, 능력으로 제공할 인터페이스의 형태를 만듭니다 — 파일이 받아들여지는 곳에만 파일 선택기를, 인터럽트가 지원되는 곳에만 승인 장치(affordance)를.

schema가 그 형태를 정의해요: AgentCapabilities, 선택적 그룹의 집합, 각각 선택적 필드의 객체. 이 페이지는 선언이 무엇을 의무화하는지 명시합니다. 컨슈머가 선언을 어떻게 얻는지는 의도적으로 명시하지 않아요 — Retrieval을 참고하세요.

선언하기 (Declaring)

모든 그룹과 그룹 안의 모든 필드는 OPTIONAL이에요. 프로듀서는 말할 것이 있는 것만 선언하고 나머지는 생략합니다. 필드가 참조하는 레코드는 자기만의 요구사항을 유지해요: SubagentInfo는 name이 필요하고, tools.items의 항목은 Tool이에요.

생략된 필드는 지원되지 않음을 뜻하지, 선언되지 않음을 뜻해요. reasoning에 대해 아무 말도 하지 않은 에이전트는 추론할 수 없다고 말한 것이 아니에요; 컨슈머는 선언의 부재로부터 능력의 부재를 추론해서는 안 됩니다(MUST NOT). 에이전트가 어떤 것이 지원되지 않는다고 명시하려면, false를 명시적으로 담을 부울 필드가 존재합니다.

프로듀서는 자신이 실제로 하는 것만 선언해야 해요(SHOULD). 선언은 실행을 어떻게 준비할지에 대한 애플리케이션에게의 진술이에요; 에이전트가 지키지 않는 선언은 그것에 기반해 만들어진 인터페이스를 오도합니다. 모든 것이 참임을 선언할 의무는 없어요 — 최소 선언도 적합합니다 — 하지만 선언된 것은 지켜져야 해요(SHOULD).

선언은 정보 제공용이지, 구속력이 없어요. 이벤트 스트림이 권위가 있습니다: 컨슈머는 선언이 예상하지 못한 이벤트가 도착했거나, 선언된 능력이 행사되지 않았기 때문에 스트림을 거부하거나 실행을 실패로 취급해서는 안 됩니다(MUST NOT). reasoning: { supported: false } 아래서 추론 이벤트를 내보내는 실행은 불만을 살만한 프로듀서이지, 거부할 만한 스트림이 아닙니다.

그룹들 (The groups)

그룹들은 프로토콜의 기능을 분할해요. 그룹이 이벤트 패밀리를 서술하면, 그 패밀리의 페이지가 이벤트 자체가 무엇을 의무화하는지 통치하고, 선언은 그것들을 예상할 뿐입니다.

그룹 선언 내용 통치하는 곳
identity 이름, 프레임워크, 버전, 프로바이더, 문서, 그리고 열린 metadata 객체 이 페이지
transport 에이전트가 서빙하는 transport 바인딩 Transports
tools 에이전트가 도구를 호출하는지, 제공하는 도구, 애플리케이션의 도구를 받아들이는지 Tool calls
output 구조화된 출력과 생성 가능한 MIME 타입 —
state 스냅샷, 델타, 실행 간 지속성, 장기 메모리 State
multiAgent 위임, 핸드오프, 호출할 수 있는 subagents Subagents
reasoning 추론이 내보내지는지, 스트리밍되는지, 암호화되는지 Reasoning
multimodal input으로 받아들이고 output으로 생성하는 모달리티 input은 Run input; output은 주석 참고
execution 코드 실행, 샌드박싱, 반복과 시간 제한 —
humanInTheLoop 승인, 개입, 피드백, 인터럽트–재개 참여 Interrupts and Resume
custom 표준 그룹이 다루지 않는 무엇이든 —

스키마에서의 설명 너머로 주석이 필요한 필드들이 있어요.

output.structuredOutput는 에이전트가 자기 답을 스키마로 형태를 잡을 수 있다고 선언하지만, 이 버전의 프로토콜에는 컨슈머가 스키마를 공급할 필드도, 출력을 구조화된 것으로 식별하는 이벤트도 없어요. 그 선언은 애플리케이션에게 에이전트가 가능하다고 말해 줍니다; 스키마가 에이전트에 어떻게 도달하고 형태 잡힌 답이 어떻게 돌아오는지는 통합별로 다르며, 컨슈머는 표준 이벤트가 둘 중 무엇을 담으리라 기대해서는 안 됩니다(MUST NOT).

multimodal.output은 에이전트가 무엇을 생산할 수 있는지 선언하지만, 이 버전의 프로토콜은 이미지나 오디오 출력을 정의하지 않아요: 어시스턴트 메시지 콘텐츠와 TEXT_MESSAGE_CONTENT 델타는 텍스트입니다. 그 선언은 애플리케이션을 위한 것 — 그런 출력을 통합별 채널을 통해 받을 수도 있죠 — 이고, 이 스펙의 어떤 것도 그것이 어떻게 이동하는지 말하지 않아요. 컨슈머는 표준 이벤트가 그것을 담으리라 기대해서는 안 됩니다(MUST NOT).

tools.items는 에이전트가 제공하는 도구 — 자기 자신의 함수, 검색, 코드 실행 — 를 나열하고, 한 실행을 위해 애플리케이션이 제공하는 도구를 담는 RunAgentInput.tools와 구별됩니다. 둘은 결코 병합되지 않아요: 에이전트 자신의 도구는 애플리케이션이 실행할 것이 아니고, 애플리케이션의 도구는 여기 선언되지 않아요.

multiAgent.subagents는 선택 인터페이스를 위해 에이전트가 호출할 수 있는 서브에이전트를 이름 붙여요. 그것은 호출이 아니라 정의의 목록입니다: 컨슈머가 와이어에서 만나는 식별자는 실행마다 하나씩, 실행 시에 발행되는 subagentRunId 값이에요 — Subagents가 그것들을 통치하고, 여기 어떤 것도 그것들을 예측하지 않아요.

두 transport 플래그 또한 이 버전이 정의하지 않는 메커니즘을 서술해요. transport.resumable은 시퀀스 번호로 중단된 스트림을 재개하는 것을 말하고, transport.pushNotifications은 실행이 끝난 뒤의 전달을 말해요; 어느 HTTP 바인딩도 시퀀스 번호를 담지 않거나, 스트림을 재개하지 않거나, 실행 후 채널을 정의하지 않아요. 에이전트는 자기 자신의 전송을 위해 그것들을 선언할 수 있지만(MAY), 컨슈머는 표준 바인딩 중 하나가 그것들을 지키리라 기대해서는 안 됩니다(MUST NOT).

identity.metadata와 custom

두 개의 열린 객체가 표준 필드가 담지 않는 것을 실어 나릅니다. identity.metadata는 프로토콜의 Metadata 형태 — 키로 열리고, 키 아래 임의의 JSON 값 — 로 통합 특정 신원 정보를 실어 나릅니다. custom은 어떤 표준 그룹에도 맞지 않는 능력을 위한 탈출구입니다. 둘 다 키로 열려 있어요: 컨슈머는 그 안에서 인식하지 못하는 것을 제거하기보다 보존해야 합니다(MUST), metadata가 다른 곳에서 그러하듯이요. 프로토콜은 둘 중 어떤 것에도 의미를 부여하지 않아요.

획득 (Retrieval)

이 스펙은 선언의 형태와 그것이 무엇을 의무화하는지 정의합니다. 컨슈머가 하나를 어떻게 얻는지는 정의하지 않아요. 이 버전의 어떤 전송 바인딩도 capabilities 교환을 담지 않고, 이 페이지는 그것을 만들지도 않습니다: 에이전트의 capabilities가 클라이언트 측 에이전트 객체의 메서드에서 읽히든, 애플리케이션 정의 엔드포인트에서 가져오든, 정적으로 설정되든 그것은 구현의 몫입니다.

이것은 의도적이에요. 발견(discovery) 프로토콜은 선언 형태보다 더 큰 약속이고, 그 형태는 그것 없이도 유용합니다. 어떤 수단으로든 capabilities를 노출하는 구현은 그것들에 이 형태를 사용해야 합니다(MUST).

오류 처리 (Error Handling)

capabilities 객체는 이벤트 파이프라인에 실리지 않으므로, processing model의 제거 의무는 그것에 적용되지 않아요; 그 모델이 미인식(unrecognised) 과 형식 오류(malformed) 사이에 긋는 구분은 적용됩니다. 미인식 멤버 — 이 버전이 정의하지 않는 그룹이나 필드 — 는 컨슈머가 아니라 엄격 레이어의 관심사예요: 스키마가 모든 capability 객체를 닫으므로 그러한 문서는 그것에 대해 검증되지 않지만, 컨슈머는 그것을 담았다는 이유로 선언을 거부해서는 안 되므로(MUST NOT), 더 새 에이전트의 선언이 더 오래된 컨슈머에서 튕겨 나가지 않습니다. Capabilities는 이벤트 파이프라인의 강제 단계를 통과하지 않으므로, 컨슈머가 미인식 멤버를 유지하든 버리든 구현의 몫이며, 적합한 구현들은 다릅니다. 스키마가 거부하는 값을 담은 알려진 필드 — 부울이 와야 하는 데 문자열 — 는 형식 오류이고, 컨슈머는 검증할 수 없는 선언을 사용해서는 안 됩니다(MUST NOT).

선언은 정보 제공용이므로, 거부되거나 없는 선언이 실행을 막아서는 안 됩니다(MUST NOT). capabilities를 얻거나 검증할 수 없는 컨슈머는 아무것도 선언하지 않은 에이전트를 대하듯 진행합니다.

더 알아보기 (Learn more)