From 594b35e180ec0435f860acabdd16a0a3ccba68f4 Mon Sep 17 00:00:00 2001 From: Isaac Date: Tue, 1 Sep 2026 09:43:07 -0700 Subject: [PATCH 1/4] Document `@request` namespace and clarify node `.input`/`.output` usage in agent script reference --- .../ROOT/pages/af-agent-script-reference.adoc | 46 +++++++++++++++++-- 1 file changed, 41 insertions(+), 5 deletions(-) diff --git a/agent-network/2.0/modules/ROOT/pages/af-agent-script-reference.adoc b/agent-network/2.0/modules/ROOT/pages/af-agent-script-reference.adoc index ca8b6a10c..ca065124e 100644 --- a/agent-network/2.0/modules/ROOT/pages/af-agent-script-reference.adoc +++ b/agent-network/2.0/modules/ROOT/pages/af-agent-script-reference.adoc @@ -1234,6 +1234,9 @@ These references are used. Every node has `.output` (the value it produced) and `.input` (the output of whichever node transitioned into it). +* If a node doesn't produce a value (for example, a router), its `.output` is `None`. +* If the preceding node is a trigger, `.input` is `None`. + *Example* ---- @@ -1241,17 +1244,50 @@ Every node has `.output` (the value it produced) and `.input` (the output of whi @generator.writeEmailContent.output # returns the string generated by the `writeEmailContent` node ---- -* Use `.output` when you know exactly which upstream node you're referencing. -* Use `.input` when multiple nodes transition into the current one and you want to decouple it from the specific path taken. +==== When to Use `.output` vs `.input` -In this example, `@generator.generate_email.input` returns whichever of `node_a`, `node_b`, or `node_c` actually transitioned into it. +Use `.output` when you know exactly which upstream node you need data from. In a straight-line graph, this is the simplest approach: ---- -node_a ──┐ -node_b ──┼──► generate_email ──► send_email +process ──► generate_email ──► send_email +---- + +* `generate_email` accesses the content to write about using `@subagent.process.output`. +* `send_email` obtains its content using `@generator.generate_email.output`. + +You can target any preceding node in the graph, not only the one immediately before the current node. + +Use `.input` when multiple nodes can transition into the current one and you want to decouple the node from the specific path taken. In this example, `@generator.generate_email.input` returns the output from whichever of `node_a`, `node_b`, or `node_c` actually transitioned into it: + +---- +node_a ──┐ +node_b ──┼──► generate_email ──► send_email node_c ──┘ ---- +=== Accessing Trigger Data + +The `@request` namespace provides access to the trigger's incoming request data. Because a workflow can support multiple interface types, `@request` decouples your nodes from the specific trigger that fired. + +* `@request.payload`: Returns the request payload. For the `on_message` handler of the A2A trigger, this expression returns a `SendMessageRequest` object. +* `@request.interface`: Returns the name of the interface that produced the message (for example, `a2a`). + +For A2A triggers, these additional references are also available: + +* `@request.headers`: A case-insensitive dictionary of the HTTP request headers. For example, `@request.headers["Authorization"]` and `@request.headers["authorization"]` return the same value. +* `@request.taskId`: The current A2A task ID, either provided in the request or automatically generated by the trigger. +* `@request.contextId`: The current A2A context ID, either provided in the request or automatically generated by the trigger. + +*Example* + +[source,yaml] +---- +reasoning: + instructions: -> @request.payload.message.parts[0].text + actions: + concur: @actions.concur-agent with http_headers = {"Authorization": @request.headers["Authorization"]} +---- + === Setting Action Headers Any actions that connect to an external system often need to set custom headers. Use cases range from propagating authorization headers (for example, in OBO authentication) to adding custom correlation information. From a925391353cbc5498b6fac145941889a5c30e129 Mon Sep 17 00:00:00 2001 From: Isaac Date: Thu, 10 Sep 2026 13:46:58 -0700 Subject: [PATCH 2/4] Clarify usage of `@request` namespace in accessing trigger data in agent script reference --- .../2.0/modules/ROOT/pages/af-agent-script-reference.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/agent-network/2.0/modules/ROOT/pages/af-agent-script-reference.adoc b/agent-network/2.0/modules/ROOT/pages/af-agent-script-reference.adoc index ca065124e..8b59b866c 100644 --- a/agent-network/2.0/modules/ROOT/pages/af-agent-script-reference.adoc +++ b/agent-network/2.0/modules/ROOT/pages/af-agent-script-reference.adoc @@ -1267,7 +1267,7 @@ node_c ──┘ === Accessing Trigger Data -The `@request` namespace provides access to the trigger's incoming request data. Because a workflow can support multiple interface types, `@request` decouples your nodes from the specific trigger that fired. +The `@request` namespace provides access to the trigger's incoming request data. Use `@request` expressions to read the payload, headers, and other properties of the request that started the workflow. * `@request.payload`: Returns the request payload. For the `on_message` handler of the A2A trigger, this expression returns a `SendMessageRequest` object. * `@request.interface`: Returns the name of the interface that produced the message (for example, `a2a`). From a2fd676e8c3ec0b77d842c7bfd4278dd6e32b625 Mon Sep 17 00:00:00 2001 From: Isaac Eldridge Date: Thu, 10 Sep 2026 15:06:31 -0700 Subject: [PATCH 3/4] Apply batched suggestions from peer review Co-authored-by: Valkyrie Hunter --- .../2.0/modules/ROOT/pages/af-agent-script-reference.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/agent-network/2.0/modules/ROOT/pages/af-agent-script-reference.adoc b/agent-network/2.0/modules/ROOT/pages/af-agent-script-reference.adoc index 8b59b866c..62930617d 100644 --- a/agent-network/2.0/modules/ROOT/pages/af-agent-script-reference.adoc +++ b/agent-network/2.0/modules/ROOT/pages/af-agent-script-reference.adoc @@ -1246,7 +1246,7 @@ Every node has `.output` (the value it produced) and `.input` (the output of whi ==== When to Use `.output` vs `.input` -Use `.output` when you know exactly which upstream node you need data from. In a straight-line graph, this is the simplest approach: +Use `.output` when you know exactly which upstream node you need data from. In a straight-line graph, `.output` is the simplest approach: ---- process ──► generate_email ──► send_email @@ -1255,7 +1255,7 @@ process ──► generate_email ──► send_email * `generate_email` accesses the content to write about using `@subagent.process.output`. * `send_email` obtains its content using `@generator.generate_email.output`. -You can target any preceding node in the graph, not only the one immediately before the current node. +An expression can target any preceding node in the graph, not only the node immediately before the current node. Use `.input` when multiple nodes can transition into the current one and you want to decouple the node from the specific path taken. In this example, `@generator.generate_email.input` returns the output from whichever of `node_a`, `node_b`, or `node_c` actually transitioned into it: From 950c469d39e4b8242f7be299df09af48bbe91eb6 Mon Sep 17 00:00:00 2001 From: Isaac Date: Thu, 10 Sep 2026 15:10:28 -0700 Subject: [PATCH 4/4] Refine descriptions of node content access in agent script reference --- .../2.0/modules/ROOT/pages/af-agent-script-reference.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/agent-network/2.0/modules/ROOT/pages/af-agent-script-reference.adoc b/agent-network/2.0/modules/ROOT/pages/af-agent-script-reference.adoc index 62930617d..1efa6f1d9 100644 --- a/agent-network/2.0/modules/ROOT/pages/af-agent-script-reference.adoc +++ b/agent-network/2.0/modules/ROOT/pages/af-agent-script-reference.adoc @@ -1252,12 +1252,12 @@ Use `.output` when you know exactly which upstream node you need data from. In a process ──► generate_email ──► send_email ---- -* `generate_email` accesses the content to write about using `@subagent.process.output`. -* `send_email` obtains its content using `@generator.generate_email.output`. +* `generate_email` reads `@subagent.process.output` as the source content. +* `send_email` reads `@generator.generate_email.output` as its content. An expression can target any preceding node in the graph, not only the node immediately before the current node. -Use `.input` when multiple nodes can transition into the current one and you want to decouple the node from the specific path taken. In this example, `@generator.generate_email.input` returns the output from whichever of `node_a`, `node_b`, or `node_c` actually transitioned into it: +To decouple a node from the path that reached it, use `.input`. In this example, `@generator.generate_email.input` returns the output from whichever of `node_a`, `node_b`, or `node_c` transitioned into `generate_email`: ---- node_a ──┐