Federico Mariani created CAMEL-25985:
----------------------------------------
Summary: camel-ai-tool: Expose JSON arguments in the body and
propagate invocation identifiers
Key: CAMEL-25985
URL: https://issues.apache.org/jira/browse/CAMEL-25985
Project: Camel
Issue Type: Improvement
Reporter: Federico Mariani
Assignee: Federico Mariani
h2. Current behavior
The ai-tool component exposes tool-call arguments as individual message headers
and leaves the message body untouched. This is convenient for Simple
expressions and SQL bindings, but requires reconstructing the complete
arguments document for tools such as Kaoto Data Mapper.
For example, given this tool call:
{code}
{
"customerName": "Alice",
"items": [
{ "sku": "TSHIRT", "quantity": 2 },
{ "sku": "MUG", "quantity": 1 }
]
}
{code}
The route receives a customerName String header and an items List of maps
header. The arguments are not populated into the body. A route requiring JSON
must reconstruct the object from these headers, including nested objects and
arrays.
For example, the current workaround is:
{code}
- setBody:
simple: "${header.items}"
- marshal:
json: {}
- setHeader:
name: itemsJson
simple: "${bodyAs(String)}"
- setBody:
constant: "{}"
- unmarshal:
json: {}
- setBody:
jq: '{customerName: header("customerName"), items: (header("itemsJson") |
fromjson)}'
- marshal:
json: {}
{code}
h2. Requested improvements
h3. Populate tool arguments into the body
Add an endpoint option, tentatively named argumentsAsBody, to populate the body
with the complete accepted tool arguments as a JSON string.
{code}
- from:
uri: ai-tool:place_order
parameters:
description: Place a merchandise order
argSchema: classpath:place-order.args.schema.json
argumentsAsBody: true
steps:
- log:
message: "${body}"
{code}
At route entry, the body would contain the complete JSON document shown above,
ready to use as a Data Mapper source.
* Default the option to false to preserve existing behavior, including any body
supplied by the calling adapter.
* Retain individual argument headers for existing expressions and bindings.
* Preserve nested objects, arrays and JSON value types.
* Build the body from arguments accepted by the executor's existing filtering,
with consistent handling of reserved argument names.
* Use an empty JSON object for a call with no arguments when the option is
enabled.
h3. Propagate invocation identifiers
As part of this improvement, expose both of the following headers whenever the
calling adapter supplies the corresponding identifier:
* CamelAiToolCallId: identifies a particular tool invocation and correlates it
with its result.
* CamelAiToolConversationId: associates tool invocations with their
conversation.
For example:
{code}
CamelAiToolCallId: call_abc123
CamelAiToolConversationId: conversation_456
{code}
Propagate the identifiers from the calling framework through the adapter to the
tool route. Omit a header when its identifier is unavailable; do not generate a
replacement identifier. Metadata propagation should be independent of the
argumentsAsBody option.
h2. Acceptance criteria
* Enabling argumentsAsBody exposes the complete accepted arguments as a
JSON-string body, including nested objects and multiple array entries.
* Existing individual argument headers remain available.
* Leaving argumentsAsBody disabled preserves the current body behavior.
* Both invocation identifier headers are propagated when available,
independently of argumentsAsBody.
* Tests cover body population, compatibility, argument filtering, empty
arguments, and identifier propagation and absence.
* Component documentation describes the body option and both headers.
--
This message was sent by Atlassian Jira
(v10.3.26#10030026)
