[jira] [Commented] (CAMEL-25985) camel-ai-tool: Expose JSON arguments in the body and propagate invocation identifiers

["Claus Ibsen (Jira)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/CAMEL-25985?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=18130588#comment-18130588 ] 

Claus Ibsen commented on CAMEL-25985:
-------------------------------------

Merged to main via https://github.com/apache/camel/pull/28295 (commit 50234ed92c59).

> 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
>            Priority: Major
>             Fix For: 4.24.0
>
>
> 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)