feat(tools): support tool search (defer_loading=true) in typed function helpers

[apcha-oai]

Summary

Configure deferred loading without rebuilding a class-derived function schema or separating an Agents tool definition from its typed handler.

Responses, before:

.addTool(LookupItem.class) // No place to configure the generated definition.

After, including structured-response builders:

.addTool(ToolSearchTool.builder().build())
.addTool(LookupItem.class, tool -> tool.deferLoading(true))

Agents, before:

var definition = AgentToolParam.ofFunction(
    lookup.definition().asFunction().toBuilder().deferLoading(true).build());
// Keep this separate definition paired with lookup.handler().

After:

var lookup = AgentFunctionTool.of(LookupItem.class, catalog::lookup)
    .withDeferLoading(true);
// Use lookup.definition() and lookup.handler() together.

withDeferLoading returns an immutable binding and also supports ofAsync. Explicit true/false values are preserved; existing defaults, schema validation, argument parsing, and handler execution remain unchanged. Tool-search configuration is validated by the API.

[apcha-oai]

@codex review pls

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-05T16:43:30.064201Z	65a5cda	Manual request
🔒 Security Review	✅ Completed 2026-10-05T16:42:55.668588Z	65a5cda	Manual request

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

Codex Review: Something went wrong. Try again later by commenting “@codex review”.

Unknown error

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[openai-sdks]

OkTest Summary

✅ 236/236 SDK tests passed in 17.678s for Java SDK PR #1144.

Test results — 42 files

Test	Result	Time
tests/chat-completions-complex-body.test.ts	✅ Passed	248ms
tests/chat-completions-create.test.ts	✅ Passed	597ms
tests/chat-completions-stream.test.ts	✅ Passed	719ms
tests/files-content-binary.test.ts	✅ Passed	255ms
tests/files-create-multipart.test.ts	✅ Passed	272ms
tests/files-list-pagination.test.ts	✅ Passed	259ms
tests/initialize-config.test.ts	✅ Passed	176ms
tests/instance-isolation.test.ts	✅ Passed	191ms
tests/models-list.test.ts	✅ Passed	354ms
tests/responses-background-lifecycle.test.ts	✅ Passed	277ms
tests/responses-body-method-errors.test.ts	✅ Passed	800ms
tests/responses-cancel-timeout.test.ts	✅ Passed	243ms
tests/responses-cancel.test.ts	✅ Passed	253ms
tests/responses-compact-retries.test.ts	✅ Passed	354ms
tests/responses-compact.test.ts	✅ Passed	326ms
tests/responses-create-advanced-stream.test.ts	✅ Passed	706ms
tests/responses-create-advanced.test.ts	✅ Passed	1.545s
tests/responses-create-disconnect.test.ts	✅ Passed	1.079s
tests/responses-create-errors.test.ts	✅ Passed	367ms
tests/responses-create-malformed-api-responses.test.ts	✅ Passed	354ms
tests/responses-create-retries.test.ts	✅ Passed	334ms
tests/responses-create-stream-failures.test.ts	✅ Passed	1.607s
tests/responses-create-stream-timeout.test.ts	✅ Passed	217ms
tests/responses-create-stream-wire.test.ts	✅ Passed	6.336s
tests/responses-create-stream.test.ts	✅ Passed	349ms
tests/responses-create-terminal-states.test.ts	✅ Passed	386ms
tests/responses-create-timeout.test.ts	✅ Passed	252ms
tests/responses-create.test.ts	✅ Passed	384ms
tests/responses-delete.test.ts	✅ Passed	248ms
tests/responses-input-items-errors.test.ts	✅ Passed	346ms
tests/responses-input-items-list.test.ts	✅ Passed	373ms
tests/responses-input-items-options.test.ts	✅ Passed	479ms
tests/responses-input-tokens-count-timeout.test.ts	✅ Passed	326ms
tests/responses-input-tokens-count.test.ts	✅ Passed	268ms
tests/responses-malformed-inputs.test.ts	✅ Passed	5.238s
tests/responses-not-found-errors.test.ts	✅ Passed	535ms
tests/responses-parse.test.ts	✅ Passed	692ms
tests/responses-retrieve-retries.test.ts	✅ Passed	325ms
tests/responses-retrieve.test.ts	✅ Passed	266ms
tests/responses-stored-method-errors.test.ts	✅ Passed	1.137s
tests/retry-behavior.test.ts	✅ Passed	3.373s
tests/sdk-error-shape.test.ts	✅ Passed	442ms

View OkTest run #37342596743

_{SDK merge (e02a5d2fe4f6) · head (65a5cda20685) · base (c50d94b56e76) · OkTest (505ac0e34283)}

[apcha-oai]

@codex review pls

[github-actions]

Castiron custom code

Evaluated main: c50d94b56e76317888b7018fd51c6704c89865b5.

✅ No new custom-code files detected.

91 mixed files remain; 1 existing customization changed.

Compared c50d94b56e76 → 65a5cda20685. Generated baselines verified.

File	Result	Current custom patch
openai-java-core/src/main/kotlin/com/openai/models/responses/ResponseCreateParams.kt	Existing customization changed	+76 / −0

90 existing customizations unchanged

• openai-java-core/src/main/kotlin/com/openai/models/audio/AudioResponseFormat.kt
• openai-java-core/src/main/kotlin/com/openai/models/beta/agents/vaults/credentials/CredentialAuth.kt
• openai-java-core/src/main/kotlin/com/openai/models/beta/agents/vaults/credentials/CredentialAuthCreateParam.kt
• openai-java-core/src/main/kotlin/com/openai/models/beta/agents/vaults/credentials/CredentialAuthRotateParam.kt
• openai-java-core/src/main/kotlin/com/openai/models/beta/responses/BetaResponse.kt
• openai-java-core/src/main/kotlin/com/openai/models/beta/responses/BetaResponseStreamEvent.kt
• openai-java-core/src/main/kotlin/com/openai/models/beta/responses/BetaResponsesServerEvent.kt
• openai-java-core/src/main/kotlin/com/openai/models/chat/completions/ChatCompletionCreateParams.kt
• openai-java-core/src/main/kotlin/com/openai/models/chat/completions/ChatCompletionMessageFunctionToolCall.kt
• openai-java-core/src/main/kotlin/com/openai/models/chat/completions/ChatCompletionToolMessageParam.kt
• openai-java-core/src/main/kotlin/com/openai/models/embeddings/Embedding.kt
• openai-java-core/src/main/kotlin/com/openai/models/embeddings/EmbeddingCreateParams.kt
• openai-java-core/src/main/kotlin/com/openai/models/responses/Response.kt
• openai-java-core/src/main/kotlin/com/openai/models/responses/ResponseFunctionToolCall.kt
• openai-java-core/src/main/kotlin/com/openai/models/responses/ResponseFunctionWebSearch.kt
• openai-java-core/src/main/kotlin/com/openai/models/responses/ResponseInputItem.kt
• openai-java-core/src/main/kotlin/com/openai/models/responses/ResponseStreamEvent.kt
• openai-java-core/src/main/kotlin/com/openai/models/responses/ResponseTextConfig.kt
• openai-java-core/src/main/kotlin/com/openai/models/responses/ResponsesServerEvent.kt
• openai-java-core/src/main/kotlin/com/openai/models/videos/Video.kt
• openai-java-core/src/main/kotlin/com/openai/models/webhooks/UnwrapWebhookEvent.kt
• openai-java-core/src/main/kotlin/com/openai/models/webhooks/WebhookEndpointWithSecret.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/BetaServiceAsync.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/BetaServiceAsyncImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/ImageServiceAsyncImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/ResponseServiceAsync.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/ResponseServiceAsyncImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/SkillServiceAsyncImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/VideoServiceAsyncImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/WebhookServiceAsync.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/WebhookServiceAsyncImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/audio/TranscriptionServiceAsyncImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/audio/TranslationServiceAsyncImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/audio/VoiceServiceAsyncImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/beta/agents/SessionServiceAsync.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/beta/agents/SessionServiceAsyncImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/chat/ChatCompletionServiceAsync.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/finetuning/checkpoints/PermissionServiceAsyncImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/skills/VersionServiceAsyncImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/blocking/BetaService.kt

50 more in the full report.

A changed generated baseline means this report cannot reliably identify which handwritten lines changed.

Inspect the custom-code diff

Download the exact patch produced by this run (requires repository access):

gh run download 37345178918 --repo openai/openai-java \
  --name castiron-custom-code-37345178918-1 --dir /tmp/castiron-custom-code-37345178918-1
git apply --stat /tmp/castiron-custom-code-37345178918-1/custom-code.patch
cat /tmp/castiron-custom-code-37345178918-1/custom-code.patch

Or reproduce it from an SDK checkout containing the vendored reporter:

git fetch --no-tags origin c50d94b56e76317888b7018fd51c6704c89865b5 65a5cda206859e904eabacfeca7c5752bc06f4b6
python3 scripts/castiron/custom_code_report.py report \
  --base c50d94b56e76317888b7018fd51c6704c89865b5 \
  --head 65a5cda206859e904eabacfeca7c5752bc06f4b6 --fetch --require-head-hash --public \
  --out /tmp/castiron-custom-code-65a5cda20685
cat /tmp/castiron-custom-code-65a5cda20685/custom-code.patch

This is the current full custom patch for mixed files, not an attribution of only the handwritten lines changed by this PR.

Full report and patch

[chatgpt-codex-connector]

🛡️ Codex Security Review · Automatically triggered

Security review completed. No security issues were found in this pull request.

Reviewed commit: e274f19895

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

• You comment "@codex security review"
• A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. 🚀

Reviewed commit: e274f19895

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[apcha-oai]

@codex review pls

[chatgpt-codex-connector]

🛡️ Codex Security Review · Automatically triggered

Security review completed. No security issues were found in this pull request.

Reviewed commit: 0ba7695133

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

• You comment "@codex security review"
• A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.

[apcha-oai]

@codex review pls

[chatgpt-codex-connector]

🛡️ Codex Security Review · Automatically triggered

Security review completed. No security issues were found in this pull request.

Reviewed commit: 65a5cda206

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

• You comment "@codex security review"
• A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. 🚀

Reviewed commit: 65a5cda206

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[markstuart-oai]

Reviewed 65a5cda206859e904eabacfeca7c5752bc06f4b6. The class-derived Responses tool customizer reuses schema generation and validation, including through the structured builder. Agents withDeferLoading returns a new definition while retaining the typed sync/async handler and the existing default. The request and streaming tests cover the option and typed argument decoding.

Hosted tests, API compatibility, Jackson compatibility, Java 8/25 runtime checks, build and lint passed on this head. Source review only; no local tests or live API calls were run. The live smoke results in the request are author-reported.