da-daken commented on code in PR #1261:
URL: https://github.com/apache/flink-agents/pull/1261#discussion_r4285677035
##########
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.
## Parallel tool-call batches
-When `tool-call.async` is enabled, the built-in `tool_call_action` runs all
tool calls from one
-`ToolRequestEvent` as a single durable batch. Set `async.batch.parallelism` to
control concurrency:
+A model may request several tool calls in one `ToolRequestEvent`. The built-in
+`tool_call_action` can execute ordinary function or MCP tool calls as a
parallel
Review Comment:
```suggestion
`tool_call_action` can execute the tools registered by the agent, possibly
including ordinary functions or MCP tool calls, as parallel operations.
```
nit:This way, the context might be more relevant.
##########
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:
nit: Maybe the configuration instructions could be placed before the
examples, which would make it more intuitive and prevent users from being
confused when they see the examples first.
--
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]
