@devries-cameron20 / composio Mirror · read-only / commits / 5d2325f12
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 09:45 UTC

feat(openai-agents): add strict-mode support to the Python provider (#4721)

`OpenAIAgentsProvider` had no constructor and hardcoded `strict_json_schema=False`, unlike the TS `OpenAIAgentsProvider`'s `{ strict }` option and this package's own `OpenAIResponsesProvider`'s `strict` param — the docs explicitly called this out as a known Python-only gap. Fixes #4719 ## Changes - Wires the existing `to_strict_json_schema`/`omit_null_tool_arguments` utilities (already used by `OpenAIResponsesProvider`) into `OpenAIAgentsProvider.wrap_tool`: when `strict=True` and the tool's schema can be expressed as strict structured outputs, register it with the normalized schema and `strict_json_schema=True`, stripping null arguments the tool's own schema doesn't accept before execution. - A schema strict mode can't express (e.g. an object with arbitrary keys) falls back to the existing non-strict path unchanged — no behavior change for the default (`strict=False`) case. - New tests in `providers/openai_agents/tests/test_provider.py`: a supported-schema case (optional properties become required-nullable, mirroring the TS test), an unsupported-schema fallback case, a null-argument-omission execution case (driven via `asyncio.run` against the real `on_invoke_tool` callback), and a default-stays-non-strict case. ## Type of change - [ ] Bug fix - [x] New feature - [ ] Refactor/Chore - [ ] Documentation - [ ] Breaking change ## How Has This Been Tested? `uv run pytest providers/openai_agents/tests/test_provider.py tests/test_type_inference_openai_agents.py` — 15 passed, no regressions. `ruff check`/`ruff format --check` (project-pinned `config/ruff.toml`): clean. `mypy --config-file config/mypy.ini providers/openai_agents/`: same 2 pre-existing, unrelated errors as unmodified `next` (confirmed via `git stash`), none on the changed file. ## Checklist - [x] I have read the Code of Conduct and this PR adheres to it - [x] I have read and understand every line of this diff, including any LLM-generated code - [x] Any third-party docs links or promotional content follow the third-party links policy — n/a, no docs links added - [x] I ran linters/tests locally and they passed - [ ] I updated documentation as needed — n/a, the docs page already documents this as a known gap and needs no change beyond removing that caveat, which I'll leave to a maintainer's discretion - [x] I added tests or explain why not applicable - [ ] I added a changeset if this change affects published packages — **not applicable**: this repo's changesets are TS-only (`.changeset/config.json` only references `@composio/*` npm packages); Python releases go out via separate `chore(release): prepare Python X.Y.Z` commits, confirmed by checking that PR #4675's own Python-side change got no changeset entry either. --------- Co-authored-by: jkomyno <alberto@composio.dev>

Avanish Garg committed Oct 12, 2026 at 16:20 UTC 5d2325f12dad886cec91b919a34a2641e6079fda
3 files changed +232 -3
docs/content/docs/providers/openai.mdx
+1 -1
@@ -406,7 +406,7 @@ The OpenAI integration ships three providers, one per API surface:
406 - **`OpenAIProvider`** for the Chat Completions API. This is the SDK default, so `new Composio()` with no provider uses it. You keep the full message list and append each assistant message plus its `tool` results yourself.
407 - **`OpenAIAgentsProvider`** for the Agents SDK. Tools come with execution wired in, so the SDK runs the loop for you.
408
409 -**Strict mode.** Pass `strict: true` or `strict=True` to `OpenAIResponsesProvider`, or pass `strict: true` to the TypeScript `OpenAIAgentsProvider`, to normalize each tool's input schema for [structured outputs](https://platform.openai.com/docs/guides/structured-outputs). The Python Agents SDK provider does not support strict mode yet. Every object lists all of its properties in `required` and is closed, while optional properties stay available but accept `null`. A `null` is dropped before the tool runs unless the tool's own schema accepts `null` for that parameter. Tools whose schema strict mode cannot express, such as objects that accept arbitrary keys, `allOf`, `prefixItems`, or unresolved `$ref`s, are sent without strict mode and log a warning.
409 +**Strict mode.** Pass `strict: true` or `strict=True` to `OpenAIResponsesProvider` or `OpenAIAgentsProvider` to normalize each tool's input schema for [structured outputs](https://platform.openai.com/docs/guides/structured-outputs). Every object lists all of its properties in `required` and is closed, while optional properties stay available but accept `null`. A `null` is dropped before the tool runs unless the tool's own schema accepts `null` for that parameter. Tools whose schema strict mode cannot express, such as objects that accept arbitrary keys, `allOf`, `prefixItems`, or unresolved `$ref`s, are sent without strict mode and log a warning.
410
411 <Tabs groupId="language" items={["Python", "TypeScript"]} persist>
412 <Tab value="Python">
python/providers/openai_agents/composio_openai_agents/provider.py
+76 -2
@@ -8,9 +8,22 @@ from agents import FunctionTool
8
9 from composio.core.provider import AgenticProvider
10 from composio.core.provider.agentic import AgenticProviderExecuteFn
11 +from composio.core.provider.base import BaseProviderConfig
12 from composio.types import Tool
13 +from composio.utils.logging import get as get_logger
14 from composio.utils.pydantic import parse_pydantic_error
15 from composio.utils.shared import normalize_tool_arguments
16 +from composio.utils.strict_schema import omit_null_tool_arguments, to_strict_json_schema
17 +
18 +logger = get_logger(__name__)
19 +
20 +# Parameters registered for a tool without input parameters under strict mode.
21 +_EMPTY_OBJECT_SCHEMA: t.Dict[str, t.Any] = {
22 + "type": "object",
23 + "properties": {},
24 + "required": [],
25 + "additionalProperties": False,
26 +}
27
28
29 # Recursively remove unsupported annotation/validation keys from schema properties.
@@ -66,6 +79,22 @@ class OpenAIAgentsProvider(
79 Composio toolset for OpenAI Agents framework.
80 """
81
82 + def __init__(
83 + self, strict: bool = False, **kwargs: t.Unpack[BaseProviderConfig]
84 + ) -> None:
85 + """
86 + :param strict: Emit wrapped tools with ``strict: true`` and normalize
87 + their parameter schemas for OpenAI structured outputs (every
88 + object fully required and closed, optional properties widened to
89 + accept ``null``, local ``$ref``/``$defs`` kept). Mirrors the
90 + TypeScript ``OpenAIAgentsProvider({ strict })`` option and this
91 + package's own ``OpenAIResponsesProvider({ strict })``. Tools
92 + whose schema strict mode cannot express are registered without
93 + strict mode instead. Defaults to ``False``.
94 + """
95 + super().__init__(**kwargs)
96 + self.strict = strict
97 +
98 def wrap_tool(
99 self,
100 tool: Tool,
@@ -73,18 +102,28 @@ class OpenAIAgentsProvider(
102 ) -> FunctionTool:
103 """Wrap a tool as a FunctionTool."""
104
105 + # Under strict mode optional parameters are emitted as
106 + # required-nullable, so a ``null`` the tool's own schema does not
107 + # accept means "omitted". ``strict_source`` is the schema the strict
108 + # rewrite was computed from, or ``None`` when this tool isn't
109 + # registered under strict mode.
110 + strict_source: t.Optional[t.Dict[str, t.Any]] = None
111 +
112 # Create a function that accepts explicit JSON string for parameters
113 # This avoids the issue with **kwargs in schema validation
114 async def execute_tool_wrapper(_ctx, payload):
115 """Execute Composio action with the given arguments."""
116 try:
117 + # Models occasionally emit arguments as a JSON string (issue #2406).
118 + arguments = normalize_tool_arguments(payload)
119 + if strict_source is not None:
120 + arguments = omit_null_tool_arguments(arguments, strict_source)
121 return json.dumps(
122 obj=(
123 await asyncio.to_thread( # Running a thread since `execute_tool` is not async
124 execute_tool,
125 slug=tool.slug,
86 - # Models occasionally emit arguments as a JSON string (issue #2406).
87 - arguments=normalize_tool_arguments(payload),
126 + arguments=arguments,
127 )
128 )
129 )
@@ -105,6 +144,41 @@ class OpenAIAgentsProvider(
144 }
145 )
146
147 + if self.strict:
148 + source = (
149 + tool.input_parameters
150 + if tool.input_parameters is not None
151 + else dict(_EMPTY_OBJECT_SCHEMA)
152 + )
153 + strict = to_strict_json_schema(source)
154 + if not strict.unsupported:
155 + if strict.total_changes:
156 + logger.debug(
157 + 'OpenAIAgentsProvider: strict mode rewrote %d node(s) of tool "%s": %s',
158 + strict.total_changes,
159 + tool.slug,
160 + "; ".join(f"{c.path}: {c.reason}" for c in strict.changes),
161 + )
162 + strict_source = strict.source
163 + return FunctionTool(
164 + name=tool.slug,
165 + description=tool.description,
166 + params_json_schema=strict.schema,
167 + on_invoke_tool=execute_tool_wrapper,
168 + strict_json_schema=True,
169 + )
170 + reasons = "; ".join(
171 + f"{entry.path or '<root>'}: {entry.keyword} ({entry.detail})"
172 + for entry in strict.unsupported
173 + )
174 + logger.warning(
175 + 'OpenAIAgentsProvider: tool "%s" is registered without strict '
176 + "mode because its schema cannot be expressed as strict "
177 + "structured outputs: %s",
178 + tool.slug,
179 + reasons,
180 + )
181 +
182 # Ensure the schema has additionalProperties set to false
183 # this is required by OpenAI's function validation.
184 # Deep-copy so the in-place edits below (additionalProperties + the
python/providers/openai_agents/tests/test_provider.py
+155
@@ -1,5 +1,6 @@
1 """Tests for the OpenAI Agents provider."""
2
3 +import asyncio
4 import copy
5 from unittest.mock import MagicMock
6
@@ -110,3 +111,157 @@ def test_wrap_tool_preserves_array_item_schemas(items_schema):
111 wrapped_tool.params_json_schema["properties"]["records"]["items"]
112 == items_schema
113 )
114 +
115 +
116 +def test_strict_mode_registers_a_strict_schema_with_optional_params_nullable():
117 + """Optional properties become required-nullable under strict mode.
118 +
119 + Mirrors the TypeScript OpenAIAgentsProvider's own strict-mode test.
120 + """
121 + tool = MagicMock(
122 + slug="CONFIGURE",
123 + description="Configure something",
124 + input_parameters={
125 + "type": "object",
126 + "properties": {
127 + "input": {"type": "string"},
128 + "cfg": {
129 + "type": "object",
130 + "properties": {
131 + "url": {"type": "string"},
132 + "note": {"type": "string"},
133 + },
134 + "required": ["url"],
135 + },
136 + },
137 + "required": ["input"],
138 + },
139 + )
140 +
141 + wrapped_tool = OpenAIAgentsProvider(strict=True).wrap_tool(
142 + tool, lambda **kwargs: {}
143 + )
144 +
145 + assert wrapped_tool.strict_json_schema is True
146 + assert wrapped_tool.params_json_schema == {
147 + "type": "object",
148 + "properties": {
149 + "input": {"type": "string"},
150 + "cfg": {
151 + "type": ["object", "null"],
152 + "properties": {
153 + "url": {"type": "string"},
154 + "note": {"type": ["string", "null"]},
155 + },
156 + "required": ["url", "note"],
157 + "additionalProperties": False,
158 + },
159 + },
160 + "required": ["input", "cfg"],
161 + "additionalProperties": False,
162 + }
163 +
164 +
165 +def test_strict_mode_optional_enum_param_can_still_be_omitted():
166 + """An optional enum is widened to accept null, so the model can leave it out."""
167 + tool = MagicMock(
168 + slug="SORT",
169 + description="Sort something",
170 + input_parameters={
171 + "type": "object",
172 + "properties": {
173 + "query": {"type": "string"},
174 + "order": {"type": "string", "enum": ["asc", "desc"]},
175 + },
176 + "required": ["query"],
177 + },
178 + )
179 +
180 + wrapped_tool = OpenAIAgentsProvider(strict=True).wrap_tool(
181 + tool, lambda **kwargs: {}
182 + )
183 +
184 + assert wrapped_tool.strict_json_schema is True
185 + assert wrapped_tool.params_json_schema["properties"]["order"] == {
186 + "anyOf": [{"type": "string", "enum": ["asc", "desc"]}, {"type": "null"}]
187 + }
188 +
189 +
190 +def test_strict_mode_falls_back_when_schema_cannot_be_expressed_strict():
191 + """A schema strict mode can't express (arbitrary-key object) is
192 + registered without strict mode instead, using the existing non-strict
193 + schema-building path.
194 + """
195 + tool = MagicMock(
196 + slug="SET_HEADERS",
197 + description="Set request headers",
198 + input_parameters={
199 + "type": "object",
200 + "properties": {
201 + "headers": {
202 + "type": "object",
203 + "additionalProperties": {"type": "string"},
204 + }
205 + },
206 + "required": ["headers"],
207 + },
208 + )
209 +
210 + wrapped_tool = OpenAIAgentsProvider(strict=True).wrap_tool(
211 + tool, lambda **kwargs: {}
212 + )
213 +
214 + assert wrapped_tool.strict_json_schema is False
215 + assert wrapped_tool.params_json_schema == {
216 + "type": "object",
217 + "properties": {
218 + "headers": {"type": "object", "additionalProperties": {"type": "string"}}
219 + },
220 + "required": ["headers"],
221 + "additionalProperties": False,
222 + }
223 +
224 +
225 +def test_strict_mode_omits_null_arguments_the_tool_schema_rejects():
226 + """Under strict mode, a null the tool's own schema doesn't accept is
227 + treated as omitted before the tool actually executes.
228 + """
229 + tool = MagicMock(
230 + slug="CONFIGURE",
231 + description="Configure something",
232 + input_parameters={
233 + "type": "object",
234 + "properties": {
235 + "input": {"type": "string"},
236 + "label": {"type": "string"},
237 + "clearable": {"type": ["string", "null"]},
238 + },
239 + "required": ["input"],
240 + },
241 + )
242 + execute_tool = MagicMock(return_value={})
243 +
244 + wrapped_tool = OpenAIAgentsProvider(strict=True).wrap_tool(tool, execute_tool)
245 +
246 + asyncio.run(
247 + wrapped_tool.on_invoke_tool(
248 + MagicMock(), '{"input": "x", "label": null, "clearable": null}'
249 + )
250 + )
251 +
252 + execute_tool.assert_called_once_with(
253 + slug="CONFIGURE", arguments={"input": "x", "clearable": None}
254 + )
255 +
256 +
257 +def test_strict_defaults_to_false():
258 + """The default constructor keeps today's non-strict behavior."""
259 + tool = MagicMock(
260 + slug="GITHUB_GET_REPO",
261 + description="Get a repository",
262 + input_parameters={"type": "object", "properties": {}, "required": []},
263 + )
264 +
265 + wrapped_tool = OpenAIAgentsProvider().wrap_tool(tool, lambda **kwargs: {})
266 +
267 + assert wrapped_tool.strict_json_schema is False