기능(Capabilities)과 훅

에이전트에 붙거나 realtime(capabilities=...)로 전달된 기능은 그 라이프사이클이 영구 연결에 매핑되는 realtime 세션에 참여해요. 서드파티 기능은 일반 실행에서와 정확히 같은 방식으로 로드돼요. 실시간 특화된 것이 요구되지 않아요.

출처: 문서

본문

세션의 기능 단계

기능 단계	세션 동작
`for_agent`, `for_run`, `get_instructions`	설정 중에 실행; 동적 인스트럭션은 연결 시 한 번 평가됨
`get_toolset`, `get_wrapper_toolset`, `prepare_tools`	연결 전에 로컬 툴을 제공, 감싸고, 준비함
`get_native_tools`	연결 전에 네이티브 툴을 제공; 동적 네이티브 툴 함수는 동적 인스트럭션처럼 연결 시점 컨텍스트에 대해 한 번 해석됨
툴 검증/실행 훅	각 로컬 함수 툴 호출 주변에서 실행
`handle_deferred_tool_calls`	지연 요청을 인라인으로 해결; 지연 및 승인 필요 툴 참고
그래프 노드, 모델 요청, 출력 처리 훅	실행되지 않음; 에이전트 그래프나 출력 처리 단계가 존재하지 않음

모든 일반 툴 검증과 툴 실행 훅 — 두 단계 모두의 before, after, wrap, on_error — 은 표준 실행에서와 정확히 같이 모든 로컬 함수 툴 호출 주변에서 (재시도까지 포함해) 실행돼요. 실행되지 않는 것은 요청-응답 그래프에 묶인 것이에요. 노드 훅, before_model_request 같은 모델 요청 훅, 그리고 출력 검증과 출력 처리 훅이요. 세션에는 그래프 노드도, 요청별 경계도, 출력 단계도 없어요.

실행 훅

before_run, after_run, wrap_run, on_run_error 실행 훅은 세션 주변에서 한 번 실행돼요. realtime 세션은 실행(run)이니까요. iter()와 같은 닫힘 경계 복구와 결과 변환 시맨틱을 가져요.

이벤트 스트림

wrap_run_event_stream은 소비자 대면 세션 이터레이터를 감싸요. 이력이나 툴 실행을 바꾸지 않고 공유 AgentStreamEvent 멤버와 realtime 전용 RealtimeEvent 멤버를 관찰하거나 변환할 수 있어요(이벤트 참조 참고). realtime()에는 event_stream_handler 매개변수가 없어요. 핸들러 스타일 소비자는 이 같은 스트림을 통해 작동하는 ProcessEventStream 기능으로 붙여요.

모델 설정과 `RunContext`

get_model_settings()는 기능 설정 중에 실행될 수 있지만, 일반 모델 설정은 realtime 모델을 구성하지 않아요. 대신 realtime(model_settings=...)를 통해 RealtimeModelSettings를 전달하세요. 세션 훅과 툴 안에서 RunContext는 세션을 반영해요:

`RunContext` 필드	realtime 세션에서의 값
`ctx.model_settings`	세션이 연결된 병합된 `RealtimeModelSettings`
`ctx.realtime`	연결이 존재하기 전에 실행되는 `for_run`과 인스트럭션 함수를 포함해 전체 실행 동안 `True`
`ctx.realtime_session`	툴과 `on_event` 컨텍스트에서 라이브 `RealtimeSession`; 실행 훅에서는 `None`

참고

ctx.realtime_session은 wrap_run 전체에서(handler() 전후 모두) None이에요. 훅이 세션이 존재하기 전에 캡처된 컨텍스트 복사본을 유지하기 때문이에요. before_run과 인스트럭션 함수에서도 None이에요. 기능이 라이브 세션을 필요로 하면 툴 훅이나 on_event를 사용하세요.

시드된 이력은 처리되지 않음

이력 처리 기능은 message_history가 세션에 시드되기 전에 그것을 변환하지 않아요. 필터링이나 리댁션이 필요하면 세션을 열기 전에 이력을 전처리하세요.

지연 기능 로딩

지연 기능은 일반 실행에서처럼 세션에서 로드돼요. 기능 카탈로그는 세션의 인스트럭션 일부이고, load_capability 툴을 호출하면 로드된 기능의 인스트럭션을 결과로 반환해요. 이것은 모든 프로바이더에서 작동해요. 세션이 할 수 없는 것은 대화 중간에 새 툴 을 광고하는 것뿐이에요(연결의 툴은 열릴 때 고정돼요. #7288 참고). 그래서 툴이나 네이티브 툴에 기여하는 defer_loading=True 기능으로 세션을 열면 연결 전에 UserError가 발생해요. 그것을 받아들이면 요청된 것보다 덜 제공하는 것을 조용히 하게 되니까요. Realtime의 턴별/교환별 훅이 향후 이 경계를 넓힐 것으로 기대돼요. #7190과 #7191 참고.

기능(Capabilities)과 훅