[Feature] Support tool parameter injection

[GreatEugenius]

Linked issue: #853

Purpose of change

Support declarative tool parameter injection for function tools.

This change lets framework-owned arguments, such as tenant id or request context, be injected at tool execution time without exposing them to the model-facing tool schema. The injection source is declared together with the hidden tool parameter, and values are resolved by the built-in tool_call_action immediately before invoking the tool.

Main changes:

• Add Python API support:

  • @tool(injected_args={"tenant_id": InjectedArg.from_config("tenant_id")})
  • explicit injection sources for config, sensory memory, and short-term memory

• Add Java API support:

  • @ToolParam(injected = true, source = ToolParameterSource.CONFIG, key = "tenant_id")
  • explicit injection sources for config, sensory memory, and short-term memory

• Add YAML API support:

  • tools[].injected_args as an object mapping parameter names to injection specs

• Inject parameters in the built-in tool_call_action, after reading model arguments and before invoking the tool.

• Preserve injected argument metadata in the plan/runtime representation while filtering injected parameters from model-facing tool metadata.

• Keep cross-language tool calls supported by resolving injection before dispatching to the target tool implementation.

Tests

UT & E2E Test

API

Yes

Documentation

• doc-needed
• doc-not-needed
• doc-included

[GreatEugenius]

Hi, @Sxnan and @wenjin272. Could you please review this PR? Thank you!

[Sxnan]

Thanks for the work — the schema-hiding part (injected_args / @ToolParam(injected=true)) is clean and useful.

A step back on the API shape before line details: #853 asks for one narrow thing — inject a model-hidden, framework-owned arg at execution time. This PR does it via a general before/after hook mechanism (hook slots on Agent, plan fields, serializers, YAML keys, new ToolCallContext/ToolCallResult). That's a lot of machinery, and the generality makes injection harder, not easier:

• Two decoupled declarations (injected_args + a separate global hook matching on tool_name), no plan-time link — forget/typo the hook → silent crash.
• One hook per agent → a manual if tool_name == ... dispatch table as tools grow.
• after_tool_call (result rewriting) is unrelated to injection — a separate capability bundled in.

Suggestion:

1. Keep injected_args for schema hiding.
2. Make the value source declarative and co-located with the param, e.g. @tool(inject={"tenant_id": lambda ctx: ctx.tenant_id}), resolved right before the call — drops the decoupling, the dispatch table, and the "declared but never filled" gap.
3. Defer before_tool_call / after_tool_call to a separate issue if a real cross-cutting need shows up — and there, consider the existing event/action model over a parallel mechanism.

If there's a concrete need behind the general hooks that isn't in #853, worth surfacing here.

[GreatEugenius]

Thanks for the work — the schema-hiding part (injected_args / @ToolParam(injected=true)) is clean and useful.

A step back on the API shape before line details: #853 asks for one narrow thing — inject a model-hidden, framework-owned arg at execution time. This PR does it via a general before/after hook mechanism (hook slots on Agent, plan fields, serializers, YAML keys, new ToolCallContext/ToolCallResult). That's a lot of machinery, and the generality makes injection harder, not easier:

• Two decoupled declarations (injected_args + a separate global hook matching on tool_name), no plan-time link — forget/typo the hook → silent crash.
• One hook per agent → a manual if tool_name == ... dispatch table as tools grow.
• after_tool_call (result rewriting) is unrelated to injection — a separate capability bundled in.

Suggestion:

1. Keep injected_args for schema hiding.
2. Make the value source declarative and co-located with the param, e.g. @tool(inject={"tenant_id": lambda ctx: ctx.tenant_id}), resolved right before the call — drops the decoupling, the dispatch table, and the "declared but never filled" gap.
3. Defer before_tool_call / after_tool_call to a separate issue if a real cross-cutting need shows up — and there, consider the existing event/action model over a parallel mechanism.

If there's a concrete need behind the general hooks that isn't in #853, worth surfacing here.

Thanks, agreed with the direction here. Stepping back, #853 should stay focused on model-hidden framework-owned argument injection, and the generic before/after hook mechanism was too broad for that scope.

I’ve updated the PR accordingly:

• Removed the before/after tool-call hook API and the related Agent/Plan/YAML/serializer fields.
• Kept injected_args / @ToolParam(injected = true) for schema hiding.
• Made the injection source declarative and co-located with the parameter instead of relying on a separate global hook. The current API supports explicit sources such as config, sensory memory, and short-term memory.
• Kept resolution in the built-in tool_call_action, right before invoking the tool, so the injected value remains hidden from the model and is not written back to the tool request.

So the PR now covers only the narrow injection use case from #853. Any general before_tool_call / after_tool_call capability can be discussed separately if a concrete cross-cutting need shows up.

[GreatEugenius]

Hi @Sxnan and @weiqingy, thank you for your comments. I have addressed all of them. Please take a look.

[wenjin272]

@GreatEugenius, thanks for taking this on. Overall looks good to me, I left two comments.

Besides, I think we also need add e2e case for YAML API.

[Sxnan]

Two follow-ups, verified against the implementations. Neither blocks the common scalar-injection path.

[GreatEugenius]

Hi @wenjin272 and @Sxnan, I have addressed your comment. Please review it once more.

[Sxnan]

One more cross-language gap, verified against the implementations: injected-arg declarations don't travel across the language bridge — schema hiding and injection only honor the host-language declaration.

[GreatEugenius]

Hi @Sxnan and @wenjin272. Thanks for pointing this out. I fixed this by carrying injected tool args through the cross-language metadata bridge in both directions.

For Python host -> Java tool, FunctionTool.set_java_resource_adapter() now passes the descriptor-declared injected arg names into JavaResourceAdapter.getJavaToolMetadata(...). The Java side uses those names when generating the model-facing schema, and also returns annotation-declared injected args from @ToolParam(injected = true). The Python FunctionTool then merges the descriptor declarations and Java annotation declarations, so tool_call_action can see the complete injected_args set at execution time.

For Java host -> Python tool, get_python_tool_metadata(...) now reads the callable’s _injected_args, hides those params from the schema together with any Java/YAML-declared injected args, and returns the callable-declared injected args back to Java. Java FunctionTool.setPythonResourceAdapter() merges them into the tool descriptor before execution.

So the cross-language behavior is now aligned: injected params are hidden from the model schema and are also available to the host-language tool_call_action for runtime injection, regardless of whether they were declared in YAML/API or on the tool annotation/decorator.