feat:OpenAPI: add web search tool schemas, tracking, includes, union#216
feat:OpenAPI: add web search tool schemas, tracking, includes, union#216
Conversation
WalkthroughUpdated OpenAPI spec to add first-class web search tool schemas (tool, tool call, approximate location), expose query and source tracking, expand include options for web search outputs, adjust tool union to include WebSearchTool, and tweak a conversation creation description. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
actor Client
participant API as OpenAI-compatible API
participant Tool as WebSearchTool
participant Web as Search Provider(s)
Client->>API: Create/continue conversation with tool use
API->>Tool: Invoke WebSearchToolCall<br/>query, filters, user_location
Tool->>Web: Perform web search
Web-->>Tool: Results (sources, snippets)
Tool-->>API: web_search_call + sources
API-->>Client: Response including includable web_search_call.sources
note over API,Client: Include options now support web_search_call.*sources
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Poem
Tip 🔌 Remote MCP (Model Context Protocol) integration is now available!Pro plan users can now connect to remote MCP servers from the Integrations page. Connect with popular remote MCPs such as Notion and Linear to add more context to your reviews and chats. ✨ Finishing Touches🧪 Generate unit tests
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. CodeRabbit Commands (Invoked using PR/Issue comments)Type Other keywords and placeholders
CodeRabbit Configuration File (
|
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
coderabbitai
Bot
changed the title
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (4)
src/libs/tryAGI.OpenAI/openapi.yaml (4)
1160-1160: Minor consistency nit: titles usually omit trailing periodsIn docs blocks we typically keep titles without trailing punctuation for consistency with the rest of the spec (“Create a conversation” vs. “Create a conversation.”). Optional, but it keeps generated docs tidy.
- title: Create a conversation. + title: Create a conversation
27246-27266: Strengthen source URL validation and clarify include key(s)
- Add format: uri to the url field to improve schema validation for source entries.
- Optional: add minItems and uniqueItems at the array level if duplicates aren’t meaningful.
- Note: You reference both web_search_call.action.sources and web_search_call.sources in descriptions elsewhere. This block defines action.sources. If a root-level sources also exists on the tool call, make sure that schema is added and linked; otherwise, remove the root-level include from docs.
url: - type: string - description: "The URL of the source.\n" + type: string + format: uri + description: "The URL of the source.\n" description: "A source used in the search.\n" - description: "The sources used in the search.\n" + description: "The sources used in the search.\n" + # Optional hardening: + # minItems: 1 + # uniqueItems: true
27275-27302: Approximate location schema looks solid; optional validation nicetiesSchema is clear and nullable is appropriate. If you want stricter validation, consider:
- country: pattern: ^[A-Z]{2}$
- timezone: keep as string but you could add a loose pattern like ^[A-Za-z_/+-]+$ to catch obvious mistakes.
country: type: string description: 'The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`.' nullable: true + pattern: '^[A-Z]{2}$' ... timezone: type: string description: 'The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`.' nullable: true + pattern: '^[A-Za-z_./+-]+$'
27353-27389: WebSearchTool: add small validation upgrades; confirm where ‘query’/‘sources’ live
- filters.allowed_domains: consider format: hostname and uniqueItems to prevent duplicates. If schemes are disallowed, state it explicitly (the example suggests hostnames only).
- Optional: additionalProperties: false on the tool object to catch typos in client configs.
- Clarify whether query and sources are intentionally only part of the tool call action. The AI summary implies WebSearchTool exposes them, but this block doesn’t. If they belong only to WebSearchToolCall.action, remove “web_search_call.sources” from include-docs and keep “web_search_call.action.sources” only. Otherwise, add the missing properties at the intended level.
filters: type: object properties: allowed_domains: title: Allowed domains for the search. type: array items: - type: string + type: string + format: hostname description: Allowed domain for the search. description: "Allowed domains for the search. If not provided, all domains are allowed. Subdomains of the provided domains are allowed as well. Example: `[\"pubmed.ncbi.nlm.nih.gov\"]` " nullable: true + uniqueItems: true description: "Filters for the search.\n" nullable: true + additionalProperties: falseIf query/sources are intended at the call level, ensure WebSearchToolCall (below) includes them and that include keys line up.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
⛔ Files ignored due to path filters (29)
src/libs/tryAGI.OpenAI/Generated/tryAGI.OpenAI..JsonSerializerContext.g.csis excluded by!**/generated/**src/libs/tryAGI.OpenAI/Generated/tryAGI.OpenAI.ConversationsClient.CreateConversation.g.csis excluded by!**/generated/**src/libs/tryAGI.OpenAI/Generated/tryAGI.OpenAI.IConversationsClient.CreateConversation.g.csis excluded by!**/generated/**src/libs/tryAGI.OpenAI/Generated/tryAGI.OpenAI.JsonConverters.Tool.g.csis excluded by!**/generated/**src/libs/tryAGI.OpenAI/Generated/tryAGI.OpenAI.JsonConverters.WebSearchActionSearchSourceType.g.csis excluded by!**/generated/**src/libs/tryAGI.OpenAI/Generated/tryAGI.OpenAI.JsonConverters.WebSearchActionSearchSourceTypeNullable.g.csis excluded by!**/generated/**src/libs/tryAGI.OpenAI/Generated/tryAGI.OpenAI.JsonConverters.WebSearchApproximateLocationType.g.csis excluded by!**/generated/**src/libs/tryAGI.OpenAI/Generated/tryAGI.OpenAI.JsonConverters.WebSearchApproximateLocationTypeNullable.g.csis excluded by!**/generated/**src/libs/tryAGI.OpenAI/Generated/tryAGI.OpenAI.JsonConverters.WebSearchToolSearchContextSize.g.csis excluded by!**/generated/**src/libs/tryAGI.OpenAI/Generated/tryAGI.OpenAI.JsonConverters.WebSearchToolSearchContextSizeNullable.g.csis excluded by!**/generated/**src/libs/tryAGI.OpenAI/Generated/tryAGI.OpenAI.JsonConverters.WebSearchToolType.g.csis excluded by!**/generated/**src/libs/tryAGI.OpenAI/Generated/tryAGI.OpenAI.JsonConverters.WebSearchToolTypeNullable.g.csis excluded by!**/generated/**src/libs/tryAGI.OpenAI/Generated/tryAGI.OpenAI.JsonSerializerContextTypes.g.csis excluded by!**/generated/**src/libs/tryAGI.OpenAI/Generated/tryAGI.OpenAI.Models.CreateResponseVariant3.g.csis excluded by!**/generated/**src/libs/tryAGI.OpenAI/Generated/tryAGI.OpenAI.Models.Includable.g.csis excluded by!**/generated/**src/libs/tryAGI.OpenAI/Generated/tryAGI.OpenAI.Models.Tool.g.csis excluded by!**/generated/**src/libs/tryAGI.OpenAI/Generated/tryAGI.OpenAI.Models.WebSearchActionSearch.g.csis excluded by!**/generated/**src/libs/tryAGI.OpenAI/Generated/tryAGI.OpenAI.Models.WebSearchActionSearchSource.Json.g.csis excluded by!**/generated/**src/libs/tryAGI.OpenAI/Generated/tryAGI.OpenAI.Models.WebSearchActionSearchSource.g.csis excluded by!**/generated/**src/libs/tryAGI.OpenAI/Generated/tryAGI.OpenAI.Models.WebSearchActionSearchSourceType.g.csis excluded by!**/generated/**src/libs/tryAGI.OpenAI/Generated/tryAGI.OpenAI.Models.WebSearchApproximateLocation.Json.g.csis excluded by!**/generated/**src/libs/tryAGI.OpenAI/Generated/tryAGI.OpenAI.Models.WebSearchApproximateLocation.g.csis excluded by!**/generated/**src/libs/tryAGI.OpenAI/Generated/tryAGI.OpenAI.Models.WebSearchApproximateLocationType.g.csis excluded by!**/generated/**src/libs/tryAGI.OpenAI/Generated/tryAGI.OpenAI.Models.WebSearchTool.Json.g.csis excluded by!**/generated/**src/libs/tryAGI.OpenAI/Generated/tryAGI.OpenAI.Models.WebSearchTool.g.csis excluded by!**/generated/**src/libs/tryAGI.OpenAI/Generated/tryAGI.OpenAI.Models.WebSearchToolFilters.Json.g.csis excluded by!**/generated/**src/libs/tryAGI.OpenAI/Generated/tryAGI.OpenAI.Models.WebSearchToolFilters.g.csis excluded by!**/generated/**src/libs/tryAGI.OpenAI/Generated/tryAGI.OpenAI.Models.WebSearchToolSearchContextSize.g.csis excluded by!**/generated/**src/libs/tryAGI.OpenAI/Generated/tryAGI.OpenAI.Models.WebSearchToolType.g.csis excluded by!**/generated/**
📒 Files selected for processing (1)
src/libs/tryAGI.OpenAI/openapi.yaml(8 hunks)
🔇 Additional comments (2)
src/libs/tryAGI.OpenAI/openapi.yaml (2)
1133-1133: Description tweak looks goodShortening the description to “Create a conversation.” matches the summary and avoids implying a caller-supplied ID. No issues.
25686-25693: Add missing discriminator.mapping to unambiguously resolve WebSearchTool vs WebSearchPreviewToolTo avoid ambiguous type resolution in code generators, extend the
components.schemas.Tool.discriminatorsection to include an explicitmappingfor each literal value defined in your tool schemas:• Confirm each schema’s exact
typeenum values by inspecting theproperties.type.enumarrays in:
#/components/schemas/WebSearchTool#/components/schemas/WebSearchPreviewTool• Under
components.schemas.Tool.discriminator, add amappingblock that points each literal to its schema, for example:components: schemas: Tool: anyOf: - $ref: '#/components/schemas/FunctionTool' … - $ref: '#/components/schemas/WebSearchTool' - $ref: '#/components/schemas/WebSearchPreviewTool' discriminator: - propertyName: type + propertyName: type + mapping: + web_search: '#/components/schemas/WebSearchTool' + <versioned_web_search_literal>: '#/components/schemas/WebSearchTool' + web_search_preview: '#/components/schemas/WebSearchPreviewTool' + <versioned_web_search_preview_literal>: '#/components/schemas/WebSearchPreviewTool'• Replace
<versioned_web_search_literal>and<versioned_web_search_preview_literal>with the actual versioned values found in each schema (e.g.,web_search_2025_08_26,web_search_preview_2025_03_11).
• Ensure that WebSearchPreviewTool’s default type (typicallyweb_search_preview) remains distinct.After applying, regenerate any client code to verify that the discriminator now cleanly differentiates between the two tool types.
| description: "Specify additional output data to include in the model response. Currently\nsupported values are:\n- `web_search_call.action.sources`: Include the sources of the web search tool call.\n- `code_interpreter_call.outputs`: Includes the outputs of python code execution\n in code interpreter tool call items.\n- `computer_call_output.output.image_url`: Include image urls from the computer call output.\n- `file_search_call.results`: Include the search results of\n the file search tool call.\n- `message.input_image.image_url`: Include image urls from the input message.\n- `message.output_text.logprobs`: Include logprobs with assistant messages.\n- `reasoning.encrypted_content`: Includes an encrypted version of reasoning\n tokens in reasoning item outputs. This enables reasoning items to be used in\n multi-turn conversations when using the Responses API statelessly (like\n when the `store` parameter is set to `false`, or when an organization is\n enrolled in the zero data retention program).\n" | ||
| schema: | ||
| type: array | ||
| items: |
There was a problem hiding this comment.
Docs mention new include values that aren’t in the Includable enum
You added “web_search_call.action.sources” (and also reference “web_search_call.sources” elsewhere), but the referenced schema for query param items is still components/schemas/Includable. Unless those values are added to the Includable enum, client validation and server-side request validation will reject them.
Action:
- Add the new include values to components/schemas/Includable (see suggested diff in Lines 16604-16604 comment), or
- If “web_search_call.sources” is not intended, remove it from docs here and in other places.
Also consider adding an explicit example array in this param to guide SDKs.
🤖 Prompt for AI Agents
In src/libs/tryAGI.OpenAI/openapi.yaml around lines 1322-1325, the docs
reference new include values ("web_search_call.action.sources" and
"web_search_call.sources") that are not present in
components/schemas/Includable, causing client and server validation failures;
update the Includable enum to include these new values (or remove the references
if "web_search_call.sources" is unintended) and add an explicit example array
for the include query parameter to guide SDK generation and users.
| description: "Specify additional output data to include in the model response. Currently\nsupported values are:\n- `web_search_call.action.sources`: Include the sources of the web search tool call.\n- `code_interpreter_call.outputs`: Includes the outputs of python code execution\n in code interpreter tool call items.\n- `computer_call_output.output.image_url`: Include image urls from the computer call output.\n- `file_search_call.results`: Include the search results of\n the file search tool call.\n- `message.input_image.image_url`: Include image urls from the input message.\n- `message.output_text.logprobs`: Include logprobs with assistant messages.\n- `reasoning.encrypted_content`: Includes an encrypted version of reasoning\n tokens in reasoning item outputs. This enables reasoning items to be used in\n multi-turn conversations when using the Responses API statelessly (like\n when the `store` parameter is set to `false`, or when an organization is\n enrolled in the zero data retention program).\n" | ||
| nullable: true | ||
| input: | ||
| anyOf: |
There was a problem hiding this comment.
Same issue: Includable description mentions new include(s) but enum not updated
This repeats the pattern from Lines 1322–1325. Please ensure components/schemas/Includable actually enumerates the new values to keep descriptions and validation in sync.
🤖 Prompt for AI Agents
In src/libs/tryAGI.OpenAI/openapi.yaml around lines 12642 to 12645, the
components/schemas/Includable description references newly added include values
but the enum array itself was not updated; update the Includable schema to add
the new include values into its enum list (and adjust any enum descriptions if
needed) so the documented descriptions and the schema validation match, then run
OpenAPI validation/linting to ensure no other enum mismatches remain.
| - reasoning.encrypted_content | ||
| type: string | ||
| description: "Specify additional output data to include in the model response. Currently\nsupported values are:\n- `code_interpreter_call.outputs`: Includes the outputs of python code execution\n in code interpreter tool call items.\n- `computer_call_output.output.image_url`: Include image urls from the computer call output.\n- `file_search_call.results`: Include the search results of\n the file search tool call.\n- `message.input_image.image_url`: Include image urls from the input message.\n- `message.output_text.logprobs`: Include logprobs with assistant messages.\n- `reasoning.encrypted_content`: Includes an encrypted version of reasoning\n tokens in reasoning item outputs. This enables reasoning items to be used in\n multi-turn conversations when using the Responses API statelessly (like\n when the `store` parameter is set to `false`, or when an organization is\n enrolled in the zero data retention program).\n" | ||
| description: "Specify additional output data to include in the model response. Currently\nsupported values are:\n- `web_search_call.action.sources`: Include the sources of the web search tool call.\n- `code_interpreter_call.outputs`: Includes the outputs of python code execution\n in code interpreter tool call items.\n- `computer_call_output.output.image_url`: Include image urls from the computer call output.\n- `file_search_call.results`: Include the search results of\n the file search tool call.\n- `message.input_image.image_url`: Include image urls from the input message.\n- `message.output_text.logprobs`: Include logprobs with assistant messages.\n- `reasoning.encrypted_content`: Includes an encrypted version of reasoning\n tokens in reasoning item outputs. This enables reasoning items to be used in\n multi-turn conversations when using the Responses API statelessly (like\n when the `store` parameter is set to `false`, or when an organization is\n enrolled in the zero data retention program).\n" |
There was a problem hiding this comment.
Add missing include enums (and decide whether root-level web_search_call.sources is supported)
Descriptions now list:
- web_search_call.action.sources
- web_search_call.sources
But Includable currently only shows previous items (e.g., message.output_text.logprobs, reasoning.encrypted_content). Add the new values to avoid schema/docs divergence. If only action-level sources are supported, drop the root-level variant from docs instead.
Here’s a concrete patch adding both values so the spec matches the current descriptions:
type: string
- description: "Specify additional output data to include in the model response. Currently
+ description: "Specify additional output data to include in the model response. Currently
supported values are:
- `web_search_call.action.sources`: Include the sources of the web search tool call.
+- `web_search_call.sources`: Include the sources of the web search tool call (root-level).
- `code_interpreter_call.outputs`: Includes the outputs of python code execution
in code interpreter tool call items.
...
"And (above in this schema where the enum item list is defined), add the items:
Includable:
title: Includable
type: string
enum:
+ - web_search_call.action.sources
+ - web_search_call.sources
- code_interpreter_call.outputs
- computer_call_output.output.image_url
- file_search_call.results
- message.input_image.image_url
- message.output_text.logprobs
- reasoning.encrypted_contentIf only one of the two web search include keys is intended, add just that one and update all descriptions accordingly.
<details>
<summary>🤖 Prompt for AI Agents</summary>
In src/libs/tryAGI.OpenAI/openapi.yaml around line 16604, the includable enum
list is missing the new keys referenced in descriptions
(web_search_call.action.sources and web_search_call.sources), causing
schema/docs divergence; update the enum definition to include both
"web_search_call.action.sources" and "web_search_call.sources" so the spec
matches descriptions, or if only one is intended, remove the incorrect
root-level mentions from descriptions and add only the intended key to the
enum—ensure descriptions and the includable enum stay consistent.
</details>
<!-- fingerprinting:phantom:triton:chinchilla -->
<!-- This is an auto-generated comment by CodeRabbit -->
1 participant
Summary by CodeRabbit