[ 
https://issues.apache.org/jira/browse/CAMEL-27251?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
 ]

Federico Mariani updated CAMEL-27251:
-------------------------------------
    Fix Version/s: 4.25.0
      Description: 
Some tools change things that a person should approve first, such as cancelling 
an order, refunding a payment or deleting data. A human-in-the-loop step for 
them: the model asks for the tool, the call does not run, and the exchange ends 
with the pending calls. A later request with the decisions (allow, or deny with 
a message) runs the allowed calls and continues the conversation. Nothing waits 
in Camel while the decision is pending, so it can come much later, from another 
route or instance: a mail, a chat message, a REST call, a task list.

Spring AI 2.1.0 supports this in its tool loop ("tool call confirmation": 
{{ToolMetadata.requiresConfirmation}}, {{ToolCallConfirmationPolicy}}, 
{{ToolCallDecision}}, {{ToolCallingManager.executeToolCalls(prompt, reply, 
decisions)}}). camel-openai runs its own tool loop and camel-langchain4j-agent 
runs it through LangChain4j, so each needs its own pause and resume.

h3. Same behaviour in every AI component

The components that run ai-tool routes (spring-ai-chat, openai, 
langchain4j-agent) and camel-mcp-server behave the same way, rather than one of 
them having the feature:

* One way to mark a tool: an ai-tool route option such as 
{{requiresConfirmation}}, and an endpoint option naming tools, for MCP tools 
and tools that are not routes.
* The same pause headers in every component (a waiting flag, and the pending 
calls with id, name and arguments) and the same resume headers (the decisions, 
the deny message), defined once in {{AiToolConstants}} instead of with a prefix 
per component.
* The paused reply is kept by the conversation memory of the component and read 
back on resume, never taken from the request. A new message instead of a 
decision closes the pause, and its calls do not run.
* {{AiToolExecutor}} refuses to run a marked tool outside a resume, so a 
runtime that does not know about confirmation never runs it.

h3. Per component

* *spring-ai-chat*: Spring AI's default tool calling manager already pauses on 
a callback whose metadata says {{requiresConfirmation}}, also in a 
{{ChatClient}} built by the user, so the component mostly has to mark the 
callbacks and resume. Spring AI's {{JdbcChatMemoryRepository}} does not store 
assistant messages with tool calls, nor tool responses, so resume needs session 
memory (CAMEL-27243) or another store that keeps them.
* *openai*: Camel runs the tool loop, so it can pause and resume the same way. 
With the Responses API the conversation is kept by OpenAI.
* *langchain4j-agent*: LangChain4j cannot pause its tool loop before a tool 
runs ({{BeforeToolExecution}} is only an event, {{HumanInTheLoop}} works 
between agents). Until it can, the component leaves a marked tool out of what 
it offers to the model and logs a WARN.
* *mcp-server*: MCP 2026-07-28 has Multi Round-Trip Requests: the server 
answers {{tools/call}} with an {{InputRequiredResult}} that carries a form 
elicitation and a {{requestState}}, the client asks the user and calls the tool 
again with the answer. The MCP Java SDK 2.2.0 supports it; the Camel MCP server 
turns it off today. The {{requestState}} must be signed with a key that every 
replica shares (a new secret option) and be bound to the principal, an expiry 
and a digest of the arguments: the SDK's {{HmacRequestStateCodec}} does not 
bind the arguments, and the client sends them again on the retry. A client that 
does not declare elicitation, or that opens with {{initialize}} (protocol 
2025-11-25 and older), gets an error for the call; the tool stays listed. 
Vert.x engine first, the Spring Boot engine after CAMEL-27174, the Quarkus 
engine after quarkus-mcp-server 2.1 ({{InputRequiredException}}).

h3. Several replicas

Nothing waits in memory, so any replica can resume, as long as the conversation 
memory is shared (an in-memory one only works on the same instance) and every 
replica has the same MCP request state key.

Running a decision only once (a double click, a redelivery, two replicas 
getting the same decisions) is left to the route, and documented with an 
idempotent consumer on a shared repository:

{code:java}
from("ai-tool:refund?tags=billing&requiresConfirmation=true&description=Refund 
an order")
    // shared by every replica: JDBC, Redis, Infinispan, Hazelcast... not the 
in-memory one
    .idempotentConsumer(
            
simple("${header.CamelAiToolConversationId}:${header.CamelAiToolCallId}"),
            jdbcIdempotentRepository)
        .skipDuplicate(false)
        .choice()
            .when(exchangeProperty(Exchange.DUPLICATE_MESSAGE).isEqualTo(true))
                .setBody(constant("This refund was already done."))
            .otherwise()
                .to("direct:refund");
{code}

For this, every component sets {{CamelAiToolCallId}} on a confirmed call: 
openai and langchain4j-agent do today, spring-ai-chat passes none, and 
camel-mcp-server would use an id kept in the request state. The key includes 
the conversation id because some providers give no call id, and the call is 
then named by its position ({{#0}}).

h3. Out of scope

* Treating the MCP {{destructiveHint}} of remote tools as "needs confirmation".
* Resume when the caller keeps the conversation ({{CHAT_MULTIPLE_MESSAGES}}), 
and a configurable confirmation policy.
* Who is allowed to decide: the job of the route that receives the decisions.
* Approvals that take hours over MCP (the MCP tasks extension).

A first spike on spring-ai-chat exists (CAMEL-27244, not merged).

_Claude Code on behalf of Croway_

  was:
Some tools change things that a person should approve first, such as cancelling 
an order, refunding a payment or deleting data. A human-in-the-loop step for 
them: the model asks for the tool, the call does not run, and the exchange ends 
with the pending calls. A later request with the decisions (allow, or deny with 
a message) runs the allowed calls and continues the conversation. Nothing waits 
in Camel while the decision is pending, so it can come much later, from another 
route or instance: a mail, a chat message, a REST call, a task list.

Spring AI 2.1.0 supports this in its tool loop ("tool call confirmation": 
{{ToolMetadata.requiresConfirmation}}, {{ToolCallConfirmationPolicy}}, 
{{ToolCallDecision}}, {{ToolCallingManager.executeToolCalls(prompt, reply, 
decisions)}}). camel-openai runs its own tool loop and camel-langchain4j-agent 
runs it through LangChain4j, so each needs its own pause and resume.

It would be nice to have an aligned behaviour in the AI components that run 
ai-tool routes (spring-ai-chat, openai, langchain4j-agent), rather than a 
feature of one of them:

* One way to mark a tool: an ai-tool route option such as 
{{requiresConfirmation}}, and maybe an endpoint option naming tools, for MCP 
tools and tools that are not routes.
* The same pause headers in every component (a waiting flag, and the pending 
calls with id, name and arguments) and the same resume headers (the decisions, 
the deny message).
* The paused reply is kept by the conversation memory of the component and read 
back on resume, never taken from the request. A new message instead of a 
decision closes the pause, and its calls do not run.
* A component that cannot pause never runs a marked tool: it leaves the tool 
out of what it offers to the model. camel-mcp-server does not publish it, or 
later supports it with MCP elicitation.

h3. Notes from a first spike on spring-ai-chat (CAMEL-27244, not merged)

* Spring AI's default tool calling manager already pauses on a callback whose 
metadata says {{requiresConfirmation}}, also in a {{ChatClient}} built by the 
user, so spring-ai-chat mostly has to mark the callbacks and resume.
* Spring AI's {{JdbcChatMemoryRepository}} does not store assistant messages 
with tool calls, nor tool responses. Resume then needs session memory 
(CAMEL-27243) or another store that keeps them.
* A wrapper on the marked callbacks that refuses to run them outside a resume 
protects against a tool calling manager that ignores the flag.
* Left out of the spike: resume when the caller keeps the conversation 
({{CHAT_MULTIPLE_MESSAGES}}), a configurable confirmation policy, two 
concurrent resumes of one conversation, and who is allowed to decide.

_Claude Code on behalf of Croway_


> camel-ai - ask a person to confirm a tool call before it runs, with the same 
> behaviour in spring-ai-chat, openai and langchain4j-agent
> --------------------------------------------------------------------------------------------------------------------------------------
>
>                 Key: CAMEL-27251
>                 URL: https://issues.apache.org/jira/browse/CAMEL-27251
>             Project: Camel
>          Issue Type: New Feature
>          Components: camel-ai, camel-langchain4j-agent, camel-openai, 
> camel-spring-ai
>            Reporter: Federico Mariani
>            Priority: Major
>             Fix For: 4.25.0
>
>
> Some tools change things that a person should approve first, such as 
> cancelling an order, refunding a payment or deleting data. A 
> human-in-the-loop step for them: the model asks for the tool, the call does 
> not run, and the exchange ends with the pending calls. A later request with 
> the decisions (allow, or deny with a message) runs the allowed calls and 
> continues the conversation. Nothing waits in Camel while the decision is 
> pending, so it can come much later, from another route or instance: a mail, a 
> chat message, a REST call, a task list.
> Spring AI 2.1.0 supports this in its tool loop ("tool call confirmation": 
> {{ToolMetadata.requiresConfirmation}}, {{ToolCallConfirmationPolicy}}, 
> {{ToolCallDecision}}, {{ToolCallingManager.executeToolCalls(prompt, reply, 
> decisions)}}). camel-openai runs its own tool loop and 
> camel-langchain4j-agent runs it through LangChain4j, so each needs its own 
> pause and resume.
> h3. Same behaviour in every AI component
> The components that run ai-tool routes (spring-ai-chat, openai, 
> langchain4j-agent) and camel-mcp-server behave the same way, rather than one 
> of them having the feature:
> * One way to mark a tool: an ai-tool route option such as 
> {{requiresConfirmation}}, and an endpoint option naming tools, for MCP tools 
> and tools that are not routes.
> * The same pause headers in every component (a waiting flag, and the pending 
> calls with id, name and arguments) and the same resume headers (the 
> decisions, the deny message), defined once in {{AiToolConstants}} instead of 
> with a prefix per component.
> * The paused reply is kept by the conversation memory of the component and 
> read back on resume, never taken from the request. A new message instead of a 
> decision closes the pause, and its calls do not run.
> * {{AiToolExecutor}} refuses to run a marked tool outside a resume, so a 
> runtime that does not know about confirmation never runs it.
> h3. Per component
> * *spring-ai-chat*: Spring AI's default tool calling manager already pauses 
> on a callback whose metadata says {{requiresConfirmation}}, also in a 
> {{ChatClient}} built by the user, so the component mostly has to mark the 
> callbacks and resume. Spring AI's {{JdbcChatMemoryRepository}} does not store 
> assistant messages with tool calls, nor tool responses, so resume needs 
> session memory (CAMEL-27243) or another store that keeps them.
> * *openai*: Camel runs the tool loop, so it can pause and resume the same 
> way. With the Responses API the conversation is kept by OpenAI.
> * *langchain4j-agent*: LangChain4j cannot pause its tool loop before a tool 
> runs ({{BeforeToolExecution}} is only an event, {{HumanInTheLoop}} works 
> between agents). Until it can, the component leaves a marked tool out of what 
> it offers to the model and logs a WARN.
> * *mcp-server*: MCP 2026-07-28 has Multi Round-Trip Requests: the server 
> answers {{tools/call}} with an {{InputRequiredResult}} that carries a form 
> elicitation and a {{requestState}}, the client asks the user and calls the 
> tool again with the answer. The MCP Java SDK 2.2.0 supports it; the Camel MCP 
> server turns it off today. The {{requestState}} must be signed with a key 
> that every replica shares (a new secret option) and be bound to the 
> principal, an expiry and a digest of the arguments: the SDK's 
> {{HmacRequestStateCodec}} does not bind the arguments, and the client sends 
> them again on the retry. A client that does not declare elicitation, or that 
> opens with {{initialize}} (protocol 2025-11-25 and older), gets an error for 
> the call; the tool stays listed. Vert.x engine first, the Spring Boot engine 
> after CAMEL-27174, the Quarkus engine after quarkus-mcp-server 2.1 
> ({{InputRequiredException}}).
> h3. Several replicas
> Nothing waits in memory, so any replica can resume, as long as the 
> conversation memory is shared (an in-memory one only works on the same 
> instance) and every replica has the same MCP request state key.
> Running a decision only once (a double click, a redelivery, two replicas 
> getting the same decisions) is left to the route, and documented with an 
> idempotent consumer on a shared repository:
> {code:java}
> from("ai-tool:refund?tags=billing&requiresConfirmation=true&description=Refund
>  an order")
>     // shared by every replica: JDBC, Redis, Infinispan, Hazelcast... not the 
> in-memory one
>     .idempotentConsumer(
>             
> simple("${header.CamelAiToolConversationId}:${header.CamelAiToolCallId}"),
>             jdbcIdempotentRepository)
>         .skipDuplicate(false)
>         .choice()
>             
> .when(exchangeProperty(Exchange.DUPLICATE_MESSAGE).isEqualTo(true))
>                 .setBody(constant("This refund was already done."))
>             .otherwise()
>                 .to("direct:refund");
> {code}
> For this, every component sets {{CamelAiToolCallId}} on a confirmed call: 
> openai and langchain4j-agent do today, spring-ai-chat passes none, and 
> camel-mcp-server would use an id kept in the request state. The key includes 
> the conversation id because some providers give no call id, and the call is 
> then named by its position ({{#0}}).
> h3. Out of scope
> * Treating the MCP {{destructiveHint}} of remote tools as "needs 
> confirmation".
> * Resume when the caller keeps the conversation ({{CHAT_MULTIPLE_MESSAGES}}), 
> and a configurable confirmation policy.
> * Who is allowed to decide: the job of the route that receives the decisions.
> * Approvals that take hours over MCP (the MCP tasks extension).
> A first spike on spring-ai-chat exists (CAMEL-27244, not merged).
> _Claude Code on behalf of Croway_



--
This message was sent by Atlassian Jira
(v10.3.26#10030026)

Reply via email to