daierenao commented on code in PR #1261:
URL: https://github.com/apache/flink-agents/pull/1261#discussion_r4289640103
##########
docs/content/docs/development/calling-llms/tool_use.md:
##########
@@ -311,61 +334,109 @@ public static String lookupOrder(
{{< /tabs >}}
-The supported sources are `config`, `sensory_memory`, and `short_term_memory`.
-If `source` is omitted, it defaults to `sensory_memory`.
-For Java annotation-based tools, `@ToolParam(injected = true)` is what marks
the
-parameter as framework-injected and hidden from the model; `source` and `key`
only
-configure where the value is read from.
-If the same injected parameter is declared both on the tool function and by a
-descriptor such as YAML, the declarations must resolve to the same source and
key;
-conflicting declarations fail during agent plan construction.
+Choose the source according to where the value is available when the tool runs:
-Injected parameters are part of the tool execution contract, not the model
contract:
+| Source | Runtime value | Python declaration |
+| --- | --- | --- |
+| `config` | A value in the agent execution environment configuration |
`InjectedArg.from_config("tenant_id")` |
+| `sensory_memory` | A value at a path in the current run's sensory memory |
`InjectedArg.from_sensory_memory("request.trace_id")` |
+| `short_term_memory` | A value at a path in the agent's short-term memory |
`InjectedArg.from_short_term_memory("session.tenant_id")` |
-- They are not included in the JSON schema sent to the model.
-- They are not written back to the original `ToolRequestEvent`.
-- If a model supplies an argument with the same name, the framework-provided
value takes precedence.
+For memory sources, write the value to the selected path before requesting the
+tool call. The path must exist and refer to a value, rather than a nested
memory
+object. The injection key identifies the configuration entry or memory path;
+it can differ from the tool parameter name.
+
+In Java annotations, set `@ToolParam(injected = true)` to hide the parameter
from
+the model, and use `source` and `key` to bind its value. The default source is
+`sensory_memory`; an omitted key uses the parameter name. For YAML
declarations,
+see the [`injected_args` reference]({{< ref
"docs/development/create-agent/yaml#resources" >}}),
+which covers the configuration shape, defaults, and examples.
+
+### Overrides and failures
+
+The built-in `tool_call_action` resolves injection before invoking a function
tool:
+
+- Injected parameters are excluded from the model-facing JSON schema.
+- A framework value overrides any model-supplied value for the same parameter.
+ The original `ToolRequestEvent` arguments remain unchanged.
+- A missing configuration entry, missing memory path, or invalid injected value
+ fails the tool call without invoking the function. Model-supplied values are
+ never used as a fallback.
+- If the function and a descriptor such as YAML both declare an injected
+ parameter, their source and key must agree. A conflict fails during agent
plan
+ construction, before the tool can run.
+
+This resolution is part of the built-in tool-call flow. When calling a function
+tool directly, supply its required arguments yourself.
Review Comment:
Good point, Moved the injection source and configuration guidance before the
examples in 5a51ecb6. Thanks!
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
