[
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)