Class DefaultMcpClientBuilder<T>
- All Implemented Interfaces:
InternalAgent, McpClientBuilder<T>, AgentInstance, InvocationHandler
-
Method Summary
Modifier and TypeMethodDescriptionThe condition under which this agent runs when it is invoked as a subagent, ornullwhen it always runs.activationCondition(String description, Predicate<AgenticScope> activationCondition) Sets the condition, with its description, under which the agent runs when it is invoked as a subagent of an agentic system.agentId()voidThe arguments never contact the MCP server, because every workflow reads them when it is built: they are the local ones until the tool is resolved, and carry the types, optionality and descriptions of its input schema afterwards.booleanasync()async(boolean async) Sets whether the agent should be invoked asynchronously, allowing the workflow to continue without waiting for the agent's result.build()The explicit description, else the one of the MCP tool, which is resolved at this point if not yet done.description(String description) Sets the description of the agent, used by the supervisor and the other planners to decide when to invoke it.Sets the names of the input parameters of the MCP tool, read from the agentic scope when the agent is invoked.listener()listener(AgentListener agentListener) name()The name, fixed bybuild(), is always known locally, without contacting the MCP server: it is the explicit one, else the one of the annotation of the agent method, else the name of that method for a typed agent, else the configured tool name for an untyped agent, else a placeholder.Sets the name of the agent, from which its id in the reports, in the agents list sent to a supervisor and in the error handler context is derived.parent()voidregisterInheritedParentListener(AgentListener parentListener) resolutionTimeout(Duration resolutionTimeout) Sets the time given to the resolution of the MCP tool, that is the creation of the MCP client by its supplier and the listing of the tools of the MCP server, which happens the first time the tool is needed, normally on the first invocation of the agent.voidsetParent(InternalAgent parent) Sets the name of the MCP tool bound by the agent.topology()Class<?> type()Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, waitMethods inherited from interface AgentInstance
as, leaf, optionalMethods inherited from interface InternalAgent
allowChatMemory, allowStreamingOutput, compensateOnError, enableCrossAgentCompensation, setAgentIdMethods inherited from interface McpClientBuilder
activationCondition
-
Method Details
-
toolName
Description copied from interface:McpClientBuilderSets the name of the MCP tool bound by the agent. When not set, the agent binds the single tool of the MCP server, and fails at its first invocation when the server exposes more than one. The tool is looked up on the server the first time it is needed, not when the agent is built.- Specified by:
toolNamein interfaceMcpClientBuilder<T>
-
name
Description copied from interface:McpClientBuilderSets the name of the agent, from which its id in the reports, in the agents list sent to a supervisor and in the error handler context is derived. When not set, a typed agent takes the name of the annotation of its agent method or, when that is not set either, the name of the method, and an untyped one takes its configured tool name or, without one, the placeholdermcp-agent, so that the name is known without contacting the MCP server, which happens only on the first invocation. The placeholder logs a warning when the agent is built, and an agentic system can contain at most one agent named with it, otherwise its construction fails with anAgenticSystemConfigurationException, since those agents could not be told apart. The name never changes once the agent is built, even after the tool has been resolved.- Specified by:
namein interfaceMcpClientBuilder<T>- Parameters:
name- the name of the agent, ignored when null or blank- Returns:
- this builder for method chaining
-
description
Description copied from interface:McpClientBuilderSets the description of the agent, used by the supervisor and the other planners to decide when to invoke it. When neither this method nor the annotation of the agent method set it, the description is the one of the MCP tool, which is resolved on the first call toAgentInstance.description(): for a subagent of a supervisor this happens on the first invocation of the supervisor, which then depends on the availability of the MCP server, so an explicit description is recommended there.- Specified by:
descriptionin interfaceMcpClientBuilder<T>- Parameters:
description- the description of the agent, ignored when null or blank- Returns:
- this builder for method chaining
-
inputKeys
Description copied from interface:McpClientBuilderSets the names of the input parameters of the MCP tool, read from the agentic scope when the agent is invoked. They are mandatory for an untyped agent, which could not report any argument without them until its tool is resolved, soMcpClientBuilder.build()fails with anIllegalArgumentExceptionwhen they are not set, while a typed agent takes them from the parameters of its agent method when they are not set.- Specified by:
inputKeysin interfaceMcpClientBuilder<T>- Parameters:
inputKeys- the names of the input keys- Returns:
- this builder for method chaining
-
outputKey
- Specified by:
outputKeyin interfaceMcpClientBuilder<T>
-
async
Description copied from interface:McpClientBuilderSets whether the agent should be invoked asynchronously, allowing the workflow to continue without waiting for the agent's result. The result is awaited only where it is read: by another agent taking it as an argument, or by the output function or output key of the agentic system.When nothing reads the result, the call to the agentic system returns while the agent is still running, and the result or the failure of the agent is then reported only to its
AgentListener. The next call on the same memory id waits for these agents to complete before it starts.- Specified by:
asyncin interfaceMcpClientBuilder<T>- Parameters:
async-truefor asynchronous invocation- Returns:
- this builder
-
listener
- Specified by:
listenerin interfaceMcpClientBuilder<T>
-
activationCondition
public McpClientBuilder<T> activationCondition(String description, Predicate<AgenticScope> activationCondition) Description copied from interface:McpClientBuilderSets the condition, with its description, under which the agent runs when it is invoked as a subagent of an agentic system. When the condition is false the MCP tool is not called and the agent is skipped. It can be evaluated more than once, so it must be free of side effects.- Specified by:
activationConditionin interfaceMcpClientBuilder<T>
-
resolutionTimeout
Description copied from interface:McpClientBuilderSets the time given to the resolution of the MCP tool, that is the creation of the MCP client by its supplier and the listing of the tools of the MCP server, which happens the first time the tool is needed, normally on the first invocation of the agent. It does not limit the execution of the tool. With such a limit the resolution runs on a thread of the LangChain4j executor, so that it can be abandoned: when the tool is not resolved within this time the resolution is interrupted and the invocation fails with anMcpToolResolutionExceptioncaused by aTimeoutException. Concurrent first invocations wait on the same resolution, so none of them waits longer than this time, and they all fail when it fails. An invocation arriving before the interrupted resolution has ended fails at once with the same timeout, so the supplier should respond to the interruption, and the next one after that resolves the tool again.By default the resolution has no such limit, is made by the first invocation needing the tool, on its own thread, so that interrupting that thread fails the invocations waiting on it too, and takes as long as the MCP client allows: a
DefaultMcpClienthas its own timeouts, which still apply to each of its steps when this one is set, so that the resolution ends at the first of them that expires.- Specified by:
resolutionTimeoutin interfaceMcpClientBuilder<T>- Parameters:
resolutionTimeout- the time given to the resolution of the MCP tool, orDuration.ZEROornullfor no such limit- Returns:
- this builder for method chaining
-
build
- Specified by:
buildin interfaceMcpClientBuilder<T>
-
invoke
-
setParent
- Specified by:
setParentin interfaceInternalAgent
-
registerInheritedParentListener
- Specified by:
registerInheritedParentListenerin interfaceInternalAgent
-
appendId
- Specified by:
appendIdin interfaceInternalAgent
-
listener
- Specified by:
listenerin interfaceInternalAgent
-
type
- Specified by:
typein interfaceAgentInstance
-
plannerType
- Specified by:
plannerTypein interfaceAgentInstance
-
name
The name, fixed bybuild(), is always known locally, without contacting the MCP server: it is the explicit one, else the one of the annotation of the agent method, else the name of that method for a typed agent, else the configured tool name for an untyped agent, else a placeholder. It never changes afterwards, not even when the tool is resolved, because the agent id is derived from it.- Specified by:
namein interfaceAgentInstance
-
agentId
- Specified by:
agentIdin interfaceAgentInstance
-
description
The explicit description, else the one of the MCP tool, which is resolved at this point if not yet done.- Specified by:
descriptionin interfaceAgentInstance
-
outputType
- Specified by:
outputTypein interfaceAgentInstance
-
outputKey
- Specified by:
outputKeyin interfaceAgentInstance
-
async
public boolean async()- Specified by:
asyncin interfaceAgentInstance
-
activationCondition
Description copied from interface:AgentInstanceThe condition under which this agent runs when it is invoked as a subagent, ornullwhen it always runs. When the condition is false, the agent is skipped: it is not invoked, it writes nothing to theAgenticScopeand its parent's planner is notified of the skip. The condition is ignored when the agent is invoked directly, as the root of an agentic system.The condition can be evaluated more than once for a single invocation, by the planner of the parent while selecting its next agents and again when the agent is invoked, so it must be cheap and free of side effects.
- Specified by:
activationConditionin interfaceAgentInstance
-
arguments
The arguments never contact the MCP server, because every workflow reads them when it is built: they are the local ones until the tool is resolved, and carry the types, optionality and descriptions of its input schema afterwards.- Specified by:
argumentsin interfaceAgentInstance
-
parent
- Specified by:
parentin interfaceAgentInstance
-
subagents
- Specified by:
subagentsin interfaceAgentInstance
-
topology
- Specified by:
topologyin interfaceAgentInstance
-