feat(provider/google): support pass-through for Gemini agentic video understanding (processing: "agentic")

Area

Provider adapters

What are you trying to accomplish?

I need to route Gemini 3.7 Flash / 3.6 Flash multimodal video understanding requests from client agents (e.g. Hermes or custom AI agents) through the OpenCodeX local proxy, allowing requests that utilize Google's new Agentic Video Understanding protocol (processing: "agentic").

What prevents this today?

Google has recently released Agentic Video Understanding (Developer Guide). In this mode, video objects carry processing: "agentic" and pass lightweight URIs or YouTube URLs instead of pre-extracted Base64 frames.
Currently, proxy schema validation and sanitizers may not recognize the processing: "agentic" attribute or URI-based video pointers on Google/Antigravity providers, risking stripping the field or raising payload validation errors.

What should OpenCodex do?

When a client sends a request containing a video object with processing: "agentic" and a video URI/URL:

The OpenCodeX proxy adapter for Google / Antigravity endpoints should preserve and forward the processing property in the upstream payload without filtering.
Support pass-through for video input items using file URIs and public YouTube URLs.
Smoothly handle server-side iterative Think → Act tool deliberations in the streaming / response loop and return the final grounded timestamps and token usage properly.

Example usage or interface

{
  "model": "google-antigravity/gemini-3.7-flash",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "video_url",
          "video_url": {
            "url": "https://www.youtube.com/watch?v=example",
            "processing": "agentic"
          }
        },
        {
          "type": "text",
          "text": "Locate the timestamp where the robot arms pick up the gear and summarize the key actions."
        }
      ]
    }
  ]
}

Alternatives or workarounds

Currently fallback to static 1 FPS frame decoding, which is token-heavy (up to 88% higher token consumption) and frequently hits proxy payload size limits on long clips.

Additional context

Upstream Google Developer Guide: https://aistudio.google.com/learn/agentic-video-understanding-with-gemini
Note: Distinct from PR fix(export): preserve Hermes vision capabilities #3151 (model capabilities export); this is purely a request payload schema & protocol pass-through enhancement.

Checks

I searched existing issues and documentation.
This request describes a concrete OpenCodex workflow rather than merely naming a desired technology.
I removed secrets and personal data.

Issue reopened

The report now contains the information required by the automated check. Thanks for updating it.

리뷰 · 우선순위 54 / 80

설명

이 이슈는 Google이 새로 연 Agentic Video Understanding 모드를 OpenCodex 프록시가 그대로 통과시켜 달라는 요청입니다. 클라이언트(Hermes 등)가 Chat Completions 형태로 video_url 파트에 YouTube/파일 URI와 함께 processing: "agentic" 을 실어 보내면, Google/Antigravity 쪽 Gemini 요청에도 그 정보가 살아 있어야 합니다. 지금처럼 영상을 1FPS로 잘라 Base64 프레임으로 넣는 우회는 토큰이 많이 들고, 긴 클립에서는 프록시 페이로드 한도에 자주 걸립니다. 닫힌 PR #3151(Hermes vision capability export)과는 다른 축입니다. 그쪽은 카탈로그/능력 표시였고, 여기는 요청 본문 스키마와 Google 어댑터 와이어입니다.

현재 dev HEAD ee24bab40 (package.json 2.41.0) 를 보면, 구멍이 세 겹입니다. 첫째, Chat 인바운드 src/chat/inbound.ts 의 videoUrlFromPart 는 type === "video_url" 일 때 URL 문자열만 꺼냅니다. video_url.processing 같은 추가 필드는 읽지도 않고, input_video 블록으로 넘길 때도 URL만 넣습니다. 둘째, Responses 쪽 src/responses/schema.ts 의 inputVideoBlockSchema 는 video_url: string 한 칸뿐이고, src/responses/parser.ts 도 { type: "video", videoUrl } 만 만듭니다. 셋째, 내부 타입 src/types/request.ts 의 OcxVideoContent 주석 자체가 “OpenAI 호환 video_url 에서 온 base64 data: URL” 이라고 적혀 있어, 원격 URI + processing 메타를 담을 자리가 없습니다.

Google 어댑터는 그 위에서 원격 영상을 사실상 버립니다. src/adapters/google.ts messagesToGeminiFormat (대략 285–289행) 은 p.type === "video" 일 때 parseDataUrl(p.videoUrl) 로 Base64만 inline_data 로 넣고, 아니면 짧은 텍스트 마커 [video: …] 로 바꿉니다. 주석에도 “임의 원격 URL은 유효한 fileData 참조가 아니라서 마커만 남긴다”고 적혀 있습니다. Antigravity(googleMode === "cloud-code-assist")도 같은 messagesToGeminiFormat 경로를 타므로, 이슈에 적힌 google-antigravity/gemini-… 모델도 동일하게 막힙니다. 즉 “검증기가 processing을 모른다 / sanitizer가 지운다”는 체감은 맞고, 코드상으로는 필드를 보존할 타입·스키마가 없고, 원격 URI는 의도적으로 텍스트로 강등되는 상태입니다.

이슈 후반의 “서버 쪽 Think → Act 도구 루프까지 부드럽게”는 범위가 한 단계 큽니다. 지금 Google 어댑터는 이미 functionCall / functionResponse 와 thought signature 재생(google-antigravity-replay)을 갖고 있지만, Agentic Video Understanding이 업스트림에서 돌리는 전용 도구·중간 스텝을 프록시가 그대로 중계해야 하는지는 제품 결정이 필요합니다. 1차는 스키마 보존 + Gemini ``file_data/file_uri`(또는 문서가 정한 agentic 와이어)로 YouTube/허용 URI 전달만 해도 이슈의 핵심 막힘은 풀립니다. types.ts/config.ts 대분할로 무효화될 종류의 작업도 아닙니다. 다만 URI를 열면 destination-policy·SSRF·허용 호스트 목록 문제가 바로 붙습니다.

라인 56-60 - src/chat/inbound.ts videoUrlFromPart가 URL만 반환해 video_url.processing(agentic)이 입구에서 사라진다
라인 85-86 - 같은 파일에서 input_video 블록에 video_url 문자열만 넣어 processing을 실을 칸이 없다
라인 15-17 - src/responses/schema.ts inputVideoBlockSchema가 video_url 문자열만 허용해 Responses 경로도 동일하게 잘린다
라인 84-86 - src/responses/parser.ts가 { type: "video", videoUrl }만 만들어 내부 모델로 processing이 전달되지 않는다
경로/심볼 src/types/request.ts OcxVideoContent - videoUrl 한 필드뿐이고 주석도 data: URL 전제라 원격 URI·processing을 표현할 수 없다
라인 285-289 - src/adapters/google.ts messagesToGeminiFormat이 원격 비디오를 [video: url] 텍스트로 강등하고 file_data/file_uri·processing을 만들지 않는다(Antigravity 공용 경로)

메인테이너의 판단이 필요한 지점

1차 범위를 “Chat/Responses 스키마에 processing 보존 + Google 어댑터에서 YouTube/https URI를 Gemini file_data로 패스스루”로 둘지, Agentic Video의 서버측 Think/Act 중계까지 같은 PR에 넣을지
허용 URI 정책: YouTube만, Google Files API URI만, 아니면 설정 가능한 allowlist인지(임의 URL 패스스루는 SSRF/destination-policy와 충돌)
processing 값을 내부 타입에 optional 필드로 둘지, Google 전용 providerMetadata에만 실을지
AI Studio 직통 어댑터와 Antigravity(cloud-code-assist) 둘 다 같은 와이어를 쓰는지, 모드별로 문서/테스트가 갈라지는지
클라이언트가 쓰는 video_url.processing 형태가 Google 공개 가이드의 Chat 호환 확장인지 확인하고, OpenAI 스키마에 없는 필드를 공식 지원으로 약속할지

너의 추천
help wanted로 두고, 좁은 PR을 받는 편이 좋습니다. (1) inbound·Responses 스키마·OcxVideoContent에 processing?: "agentic" | string (또는 동등 메타)를 보존하고, (2) messagesToGeminiFormat에서 data URL은 기존 inline_data, processing === "agentic" 이면서 허용된 http(s)/YouTube/Files URI는 Gemini file_data.file_uri(+필요 시 processing 필드)로내며, (3) 단위 테스트로 “agentic+YouTube → 텍스트 마커로 강등되지 않음”와 “비허용 호스트는 거부/마커”를 고정하세요. Think→Act 중계는 별 이슈/후속 PR로 쪼개세요. types/config 대분할과 겹치지 않으니 close-don't-rebase 대상이 아닙니다. 중복 이슈가 보이면 이쪽에 묶고 나머지는 닫으면 됩니다.

이 댓글은 grok-bot이 작성했습니다

@GoldenLoaf24h

Closing in favor of #3377, which carries the remaining scope forward.

Thank you @GoldenLoaf24h — the request for Gemini agentic video understanding pass-through is valid and still unimplemented.

Verified current state. src/chat/inbound.ts preserves only the video URL, src/responses/schema.ts has no processing field, and src/adapters/google.ts converts non-data video URLs to text markers.

All three open requests of this kind are blocked at the same layer: the provider/model row has nowhere to declare what the model can do, so each one would otherwise land as a separate bespoke flag. #3377 asks for the capability block that all three populate, names this issue, and credits you for the original analysis.

Please follow #3377; if the consolidation lost a detail you asked for, say so there and it will be added.

feat(google): pass Gemini agentic video through instead of flattening it

Navigation Menu

Repository navigation

feat(provider/google): support pass-through for Gemini agentic video understanding (processing: "agentic") #3271

Area

What are you trying to accomplish?

What prevents this today?

What should OpenCodex do?

Example usage or interface

Alternatives or workarounds

Additional context

Checks

Issue reopened

리뷰 · 우선순위 54 / 80

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

feat(provider/google): support pass-through for Gemini agentic video understanding (processing: "agentic") #3271

Description

Area

What are you trying to accomplish?

What prevents this today?

What should OpenCodex do?

Example usage or interface

Alternatives or workarounds

Additional context

Checks

Activity

github-actions commented on Sep 2, 2026

Issue reopened

lidge-jun commented on Sep 2, 2026

리뷰 · 우선순위 54 / 80

lidge-jun commented on Sep 3, 2026

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions