Skip to content

Commit c229207

Browse files
committed
fix(langgraph): keep JSON Schema semantics for object values and validate node I/O
The pydantic models generated from Agent Spec object schemas lost the semantics of the schemas they came from, and node executors never checked values against the declared schemas: - a bare object schema (or a typed dictionary) became an empty model that silently stripped every key (oracle#220); - additional properties were dropped even when the schema allowed them (oracle#239); - declared defaults of omitted nested properties were replaced by None (oracle#241, LangGraph part); - tools received pydantic model instances for object arguments instead of the plain dictionaries used by the other runtimes, and those instances leaked into flow outputs and client-tool interrupt payloads; - StartNode inputs and EndNode outputs violating their nested schema (missing required property, wrong type, unexpected key) were accepted (oracle#231, oracle#233); - a ToolNode without declared outputs raised "Unsupported multi-output mapping" for any tool return value that was not a dict or tuple. Generated object models now derive from AgentSpecObjectModel: bare object schemas map to Dict[str, Any] (typed when additionalProperties is a schema), extra keys are kept unless additionalProperties is false, declared defaults are applied and unset optional fields are omitted when converting back to JSON with to_json_value(). Tool callables are wrapped so they receive JSON values, and structured agent outputs are converted the same way. Node executors apply nested defaults and validate every input/output value against its JSON schema with the jsonschema package, reporting each violation with the node and property names. The zero-output ToolNode branch now short-circuits the mapping. One existing test declared an object output but expected the scalar 1 to come out of it; it now declares an untyped output. Fixes oracle#220, oracle#231, oracle#233, oracle#239. Fixes the LangGraph part of oracle#241. Signed-off-by: Federico Kamelhar <[email protected]>
1 parent ee111bb commit c229207

8 files changed

Lines changed: 1009 additions & 41 deletions

File tree

‎docs/pyagentspec/source/changelog.rst‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,25 @@ Bug fixes
5050
``anyOf`` appended the normalized types to the schema's own ``anyOf`` list. The schema is now
5151
left untouched.
5252

53+
* **LangGraph adapter: object schemas and I/O validation**
54+
55+
Values flowing through LangGraph agents and flows now keep the JSON Schema semantics of
56+
their Agent Spec properties:
57+
58+
- object schemas without declared properties (including typed dictionaries) are passed
59+
through as dictionaries instead of being validated by an empty model that dropped every key;
60+
- additional object properties are kept when the schema allows them (``additionalProperties``
61+
is ``true``, a schema, or not specified) and are still rejected when it is ``false``;
62+
- declared defaults of omitted nested properties are applied, and optional properties that were
63+
neither provided nor defaulted are no longer reported as ``null``;
64+
- tools receive their object arguments as plain dictionaries (as in the other runtimes) instead
65+
of pydantic model instances, and structured agent outputs are exposed as plain JSON values;
66+
- node inputs and outputs are validated against their declared JSON schema, so a flow run with
67+
a ``StartNode`` input or an ``EndNode`` output missing a nested required property, having a
68+
wrong type or an unexpected key now fails with an error naming the node, the property and
69+
each violation;
70+
- a ``ToolNode`` without declared outputs no longer fails when its tool returns a value.
71+
5372
Breaking Changes
5473
^^^^^^^^^^^^^^^^
5574

‎pyagentspec/src/pyagentspec/adapters/_utils.py‎

Lines changed: 123 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,10 @@
55
# (UPL) 1.0 (LICENSE-UPL or https://oss.oracle.com/licenses/upl), at your option.
66

77
import re
8-
from typing import Any, Dict, List, Literal, Tuple, Union
8+
from copy import deepcopy
9+
from typing import Any, ClassVar, Dict, FrozenSet, List, Literal, Tuple, Union
910

11+
from jsonschema import Draft202012Validator
1012
from pydantic import BaseModel, ConfigDict, Field, create_model
1113

1214
from pyagentspec.property import Property as AgentSpecProperty
@@ -100,6 +102,96 @@ def __init__(self) -> None:
100102
self.models: Dict[str, type[BaseModel]] = {}
101103

102104

105+
class AgentSpecObjectModel(BaseModel):
106+
"""Base class of the pydantic models generated from Agent Spec object schemas.
107+
108+
The generated models keep the JSON Schema semantics of the property they come from:
109+
additional keys are kept when the schema allows them, declared defaults are applied,
110+
and optional fields that were neither provided nor defaulted are omitted when the
111+
model is converted back to a plain JSON value with :func:`to_json_value`.
112+
"""
113+
114+
_agentspec_fields_with_default: ClassVar[FrozenSet[str]] = frozenset()
115+
116+
def to_json_value(self) -> Dict[str, Any]:
117+
"""Convert the model back to the plain JSON object it was validated from."""
118+
result: Dict[str, Any] = {}
119+
for field_name in type(self).model_fields:
120+
if (
121+
field_name in self.model_fields_set
122+
or field_name in self._agentspec_fields_with_default
123+
):
124+
result[field_name] = to_json_value(getattr(self, field_name))
125+
for extra_name, extra_value in (self.model_extra or {}).items():
126+
result[extra_name] = to_json_value(extra_value)
127+
return result
128+
129+
130+
class _AllowExtraObjectModel(AgentSpecObjectModel):
131+
"""Generated object model for schemas that allow additional properties."""
132+
133+
model_config = ConfigDict(extra="allow")
134+
135+
136+
class _ForbidExtraObjectModel(AgentSpecObjectModel):
137+
"""Generated object model for schemas with ``additionalProperties: false``."""
138+
139+
model_config = ConfigDict(extra="forbid")
140+
141+
142+
def to_json_value(value: Any) -> Any:
143+
"""Recursively convert generated object models (and tuples) into plain JSON values.
144+
145+
Pydantic models that do not come from Agent Spec schemas are left untouched so that
146+
runtime-specific tools keep receiving their own argument models.
147+
"""
148+
if isinstance(value, AgentSpecObjectModel):
149+
return value.to_json_value()
150+
if isinstance(value, dict):
151+
return {key: to_json_value(inner_value) for key, inner_value in value.items()}
152+
if isinstance(value, (list, tuple)):
153+
return [to_json_value(inner_value) for inner_value in value]
154+
return value
155+
156+
157+
def apply_json_schema_defaults(value: Any, json_schema: Dict[str, Any]) -> Any:
158+
"""Fill the declared defaults of missing object properties, recursively.
159+
160+
Only object ``properties`` and array ``items`` are traversed; ``anyOf`` alternatives are
161+
left untouched because the matching alternative cannot be determined reliably.
162+
"""
163+
if isinstance(value, dict):
164+
properties = json_schema.get("properties") or {}
165+
if not isinstance(properties, dict):
166+
return value
167+
result = dict(value)
168+
for property_name, property_schema in properties.items():
169+
if not isinstance(property_schema, dict):
170+
continue
171+
if property_name in result:
172+
result[property_name] = apply_json_schema_defaults(
173+
result[property_name], property_schema
174+
)
175+
elif "default" in property_schema:
176+
result[property_name] = deepcopy(property_schema["default"])
177+
return result
178+
if isinstance(value, list):
179+
items_schema = json_schema.get("items")
180+
if isinstance(items_schema, dict):
181+
return [apply_json_schema_defaults(item, items_schema) for item in value]
182+
return value
183+
184+
185+
def get_json_schema_validation_errors(value: Any, json_schema: Dict[str, Any]) -> List[str]:
186+
"""Return human-readable validation errors of ``value`` against ``json_schema``.
187+
188+
An empty list means the value conforms to the schema.
189+
"""
190+
validator = Draft202012Validator(json_schema)
191+
errors = sorted(validator.iter_errors(value), key=lambda error: error.json_path)
192+
return [f"{error.json_path}: {error.message}" for error in errors]
193+
194+
103195
def _build_type_from_schema(
104196
name: str,
105197
schema: Dict[str, Any],
@@ -137,6 +229,21 @@ def _build_type_from_schema(
137229
return List[item_type] # type: ignore
138230
# objects
139231
if t == "object" or ("properties" in schema or "required" in schema):
232+
props = schema.get("properties", {}) or {}
233+
# JSON Schema allows additional properties unless the schema says otherwise
234+
additional_properties = schema.get("additionalProperties", True)
235+
236+
if not props and additional_properties is not False:
237+
# Bare object schema (or a typed dictionary): any object is accepted, so the value
238+
# is passed through as a dictionary. An empty pydantic model would silently strip
239+
# every key instead.
240+
value_type = (
241+
_build_type_from_schema(f"{name}Value", additional_properties, registry)
242+
if isinstance(additional_properties, dict)
243+
else Any
244+
)
245+
return Dict[str, value_type] # type: ignore
246+
140247
# Create or reuse a Pydantic model for this object schema
141248
model_name = schema.get("title") or name
142249
unique_name = model_name
@@ -145,28 +252,30 @@ def _build_type_from_schema(
145252
suffix += 1
146253
unique_name = f"{model_name}_{suffix}"
147254

148-
props = schema.get("properties", {}) or {}
149255
required = set(schema.get("required", []))
150256

151257
fields: Dict[str, Tuple[Any, Any]] = {}
258+
fields_with_default = set()
152259
for prop_name, prop_schema in props.items():
153260
prop_type = _build_type_from_schema(f"{unique_name}_{prop_name}", prop_schema, registry)
154261
desc = prop_schema.get("description")
155-
default_field = (
156-
Field(..., description=desc)
157-
if prop_name in required
158-
else Field(None, description=desc)
159-
)
262+
if prop_name in required:
263+
default_field = Field(..., description=desc)
264+
elif "default" in prop_schema:
265+
# Omitted optional properties take their declared default
266+
default_field = Field(deepcopy(prop_schema["default"]), description=desc)
267+
fields_with_default.add(prop_name)
268+
else:
269+
default_field = Field(None, description=desc)
160270
fields[prop_name] = (prop_type, default_field)
161271

162-
# Enforce additionalProperties: False (extra=forbid)
163-
extra_forbid = schema.get("additionalProperties") is False
164-
model_kwargs: Dict[str, Any] = {}
165-
if extra_forbid:
166-
# Pydantic v2: pass a ConfigDict/dict into __config__
167-
model_kwargs["__config__"] = ConfigDict(extra="forbid")
272+
# additionalProperties: False -> extra=forbid, otherwise keep the extra keys (extra=allow)
273+
base_model = (
274+
_ForbidExtraObjectModel if additional_properties is False else _AllowExtraObjectModel
275+
)
168276

169-
model_cls = create_model(unique_name, **fields, **model_kwargs) # type: ignore
277+
model_cls = create_model(unique_name, __base__=base_model, **fields) # type: ignore
278+
model_cls._agentspec_fields_with_default = frozenset(fields_with_default)
170279
registry.models[unique_name] = model_cls
171280
return model_cls
172281

‎pyagentspec/src/pyagentspec/adapters/langgraph/_langgraphconverter.py‎

Lines changed: 60 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,7 @@
3535
SchemaRegistry,
3636
_build_type_from_schema,
3737
create_pydantic_model_from_properties,
38+
to_json_value,
3839
)
3940
from pyagentspec.adapters.langgraph._execution_span import patch_with_execution_span
4041
from pyagentspec.adapters.langgraph._managerworkers import (
@@ -787,10 +788,12 @@ def _remote_tool_convert_to_langgraph(
787788
) -> StructuredTool:
788789
tool_name = remote_tool.name
789790
tool_description = remote_tool.description or ""
790-
_remote_tool = _confirm_then(
791-
func=_create_remote_tool_func(remote_tool),
792-
tool_name=tool_name,
793-
requires_confirmation=remote_tool.requires_confirmation,
791+
_remote_tool = _with_json_arguments(
792+
_confirm_then(
793+
func=_create_remote_tool_func(remote_tool),
794+
tool_name=tool_name,
795+
requires_confirmation=remote_tool.requires_confirmation,
796+
)
794797
)
795798

796799
# Use a Pydantic model for args_schema
@@ -907,6 +910,9 @@ def _client_tool_convert_to_langgraph(
907910
requires_confirmation = agentspec_client_tool.requires_confirmation
908911

909912
def client_tool(*args: Any, **kwargs: Any) -> Any:
913+
# The client receives plain JSON values, not the generated argument models
914+
args = tuple(to_json_value(args))
915+
kwargs = to_json_value(kwargs)
910916
if requires_confirmation:
911917
if args:
912918
raise ValueError("Args are not supported, please only use kwargs")
@@ -1909,6 +1915,39 @@ async def _wrapped_async(*args: Any, **kwargs: Any) -> Any:
19091915
return _wrapped_async
19101916

19111917

1918+
@overload
1919+
def _with_json_arguments(
1920+
func: Callable[..., Awaitable[Any]],
1921+
) -> Callable[..., Awaitable[Any]]: ...
1922+
1923+
1924+
@overload
1925+
def _with_json_arguments(
1926+
func: Callable[..., Any],
1927+
) -> Callable[..., Any]: ...
1928+
1929+
1930+
def _with_json_arguments(func: Callable[..., Any]) -> Callable[..., Any]:
1931+
"""Wrap a tool callable so that it receives plain JSON values as arguments.
1932+
1933+
LangChain validates tool arguments with the pydantic models generated from the Agent Spec
1934+
input schemas and passes the model instances of nested objects to the callable. Agent Spec
1935+
tools are written against JSON values (as in the other runtimes), so those instances are
1936+
converted back to dictionaries before the call.
1937+
"""
1938+
if _is_async_callable(func):
1939+
1940+
async def _wrapped_async(*args: Any, **kwargs: Any) -> Any:
1941+
return await func(*to_json_value(args), **to_json_value(kwargs))
1942+
1943+
return _wrapped_async
1944+
1945+
def _wrapped_sync(*args: Any, **kwargs: Any) -> Any:
1946+
return func(*to_json_value(args), **to_json_value(kwargs))
1947+
1948+
return _wrapped_sync
1949+
1950+
19121951
class StructuredToolCallableKwargs(TypedDict, total=False):
19131952
func: Callable[..., Any]
19141953
coroutine: Callable[..., Awaitable[Any]]
@@ -1933,24 +1972,30 @@ def _get_structured_tool_callable_kwargs(
19331972
if isinstance(tool_obj, BaseTool):
19341973
tool_func = getattr(tool_obj, "func", None)
19351974
if tool_func is not None:
1936-
structured_tool_callable_kwargs["func"] = _confirm_then(
1937-
func=tool_func,
1938-
tool_name=tool_name,
1939-
requires_confirmation=requires_confirmation,
1975+
structured_tool_callable_kwargs["func"] = _with_json_arguments(
1976+
_confirm_then(
1977+
func=tool_func,
1978+
tool_name=tool_name,
1979+
requires_confirmation=requires_confirmation,
1980+
)
19401981
)
19411982

19421983
tool_coroutine = getattr(tool_obj, "coroutine", None)
19431984
if tool_coroutine is not None:
1944-
structured_tool_callable_kwargs["coroutine"] = _confirm_then(
1945-
func=tool_coroutine,
1985+
structured_tool_callable_kwargs["coroutine"] = _with_json_arguments(
1986+
_confirm_then(
1987+
func=tool_coroutine,
1988+
tool_name=tool_name,
1989+
requires_confirmation=requires_confirmation,
1990+
)
1991+
)
1992+
elif callable(tool_obj):
1993+
wrapped_tool = _with_json_arguments(
1994+
_confirm_then(
1995+
func=tool_obj,
19461996
tool_name=tool_name,
19471997
requires_confirmation=requires_confirmation,
19481998
)
1949-
elif callable(tool_obj):
1950-
wrapped_tool = _confirm_then(
1951-
func=tool_obj,
1952-
tool_name=tool_name,
1953-
requires_confirmation=requires_confirmation,
19541999
)
19552000
if _is_async_callable(wrapped_tool):
19562001
structured_tool_callable_kwargs["coroutine"] = wrapped_tool

0 commit comments

Comments
 (0)