Fix Bug: Tools Convert Failing

[Iamsdt]

This pull request introduces several improvements to how tool arguments and return values are handled, especially focusing on type coercion and serialization for structured and scalar types. It adds robust mechanisms to ensure that arguments passed to tools are validated and converted according to their declared types, and that return values containing non-JSON-native types (like datetime, UUID, or Decimal) are serialized in a readable and lossless way. The changes also enhance the @tool decorator to allow explicit JSON Schema for parameters, giving users more control over schema generation and validation.

Tool argument coercion and validation

• Introduced a new coercion.py module that ensures tool arguments are validated and coerced into their declared types using Pydantic, covering dataclasses, enums, and various scalar types. This prevents silent failures when models pass plain JSON that doesn't match the function's type hints. (agentflow/core/graph/tool_node/coercion.py)
• Updated the tool execution pipeline to use this coercion logic, so arguments are always validated and converted before the tool function runs. (agentflow/core/graph/tool_node/local_exec.py) [1] [2] [3]

Tool return value serialization

• Enhanced _safe_serialize to walk nested structures and serialize scalar types (like datetime, date, time, UUID, Decimal, enum.Enum, set, bytes) into readable strings, preserving the original structure for the model and preventing collapse into Python repr strings. (agentflow/core/graph/tool_node/_helpers.py) [1] [2]
• Added comprehensive tests to ensure that serialization works as expected for all supported scalar types and nested containers. (tests/graph/test_tool_node_helpers.py) [1] [2] [3]

Explicit parameter schemas for tools

• Extended the @tool decorator to accept a parameters argument, allowing users to specify an explicit JSON Schema for tool parameters. This bypasses automatic schema generation and is useful for advanced or provider-specific schemas. (agentflow/utils/decorators.py) [1] [2] [3] [4] [5] [6]

Schema and API consistency

• Updated the schema generation and tests to ensure that defaults are not redundantly included in item schemas, and that required/optional status is accurately conveyed. (tests/graph/test_tool_node.py)
• Exposed UnsupportedToolParameterError in the tool node module's public API for better error handling. (agentflow/core/graph/tool_node/__init__.py)

Linting and code quality

• Added a code quality exception for the new type dispatcher logic in the schema builder. (pyproject.toml)

These changes make tool integration safer, more robust, and more flexible, especially when dealing with complex types and model-generated input.

[Copilot]

Pull request overview

This pull request improves the local tool integration layer by (1) generating portable JSON Schemas for structured tool parameters (Pydantic models, dataclasses, enums, nested containers), (2) coercing provider-returned JSON arguments into the tool’s declared Python types before execution, and (3) serializing non-JSON-native return scalars (e.g., datetime, UUID, Decimal) without collapsing nested structures.

Changes:

• Added schema generation support for nested objects and stricter rejection of unsupported annotations, with an @tool(parameters=...) escape hatch.
• Added argument coercion via Pydantic TypeAdapter to validate/convert structured + scalar stdlib types prior to tool invocation.
• Improved tool return serialization to preserve nested structure while formatting scalar leaves; added/expanded tests for schema, coercion, and serialization behavior.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/graph/test_tool_schema_objects.py	New coverage for nested object schemas, unsupported-type errors, explicit schema override, and argument coercion.
tests/graph/test_tool_node.py	Updates expectations around default propagation in nested schemas (dropping redundant/null defaults).
tests/graph/test_tool_node_helpers.py	Adds tests ensuring _safe_serialize formats scalars and walks nested containers correctly.
pyproject.toml	Adds a Ruff complexity-rule exception for the schema type-dispatch table.
agentflow/utils/decorators.py	Extends @tool to accept explicit parameters JSON Schema override and exposes it via metadata.
agentflow/core/graph/tool_node/schema.py	Reworks schema generation to inline nested objects, avoid non-portable JSON Schema keywords, and raise on unsupported annotations.
agentflow/core/graph/tool_node/local_exec.py	Integrates argument coercion into local tool execution, using resolved type hints.
agentflow/core/graph/tool_node/coercion.py	New module implementing Pydantic-based coercion/validation for structured + scalar types.
agentflow/core/graph/tool_node/_helpers.py	Enhances _safe_serialize to preserve structure while serializing non-JSON-native scalar types.
agentflow/core/graph/tool_node/init.py	Exposes UnsupportedToolParameterError in the tool node public API.

[codecov]

Codecov Report

❌ Patch coverage is 90.00000% with 27 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
agentflow/core/graph/tool_node/schema.py	90.11%	8 Missing and 9 partials ⚠️
agentflow/core/graph/tool_node/coercion.py	84.84%	8 Missing and 2 partials ⚠️

📢 Thoughts on this report? Let us know!

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 1 comment.

Suppressed comments (2)

agentflow/core/graph/tool_node/_helpers.py:43

• Byte serialization uses errors="replace", which is lossy (non-UTF8 bytes will be irreversibly replaced). The PR description calls for readable and lossless serialization; consider emitting UTF-8 when possible and a deterministic hex fallback otherwise.

    (enum.Enum, lambda o: o.value),
    ((set, frozenset), _stable_members),
    ((bytes, bytearray), lambda o: o.decode("utf-8", errors="replace")),
)

pyproject.toml:222

• The PR title says it updates the version to 0.9.1, but this PR's diff doesn't include a version change (and pyproject.toml already has version = "0.9.1"). Consider updating the PR title to reflect the tool schema/coercion changes (or adjust the PR description if the title is authoritative).

# Type dispatchers: one return per supported annotation reads better as a flat table.
"agentflow/core/graph/tool_node/schema.py" = ["PLR0911"]