Class DefaultMcpClientBuilder<T>

java.lang.Object
dev.langchain4j.agentic.mcp.DefaultMcpClientBuilder<T>
All Implemented Interfaces:
InternalAgent, McpClientBuilder<T>, AgentInstance, InvocationHandler

public class DefaultMcpClientBuilder<T> extends Object implements McpClientBuilder<T>, InternalAgent, InvocationHandler
  • Method Details

    • toolName

      public McpClientBuilder<T> toolName(String toolName)
      Description copied from interface: McpClientBuilder
      Sets 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:
      toolName in interface McpClientBuilder<T>
    • name

      public McpClientBuilder<T> name(String name)
      Description copied from interface: McpClientBuilder
      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. 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 placeholder mcp-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 an AgenticSystemConfigurationException, 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:
      name in interface McpClientBuilder<T>
      Parameters:
      name - the name of the agent, ignored when null or blank
      Returns:
      this builder for method chaining
    • description

      public McpClientBuilder<T> description(String description)
      Description copied from interface: McpClientBuilder
      Sets 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 to AgentInstance.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:
      description in interface McpClientBuilder<T>
      Parameters:
      description - the description of the agent, ignored when null or blank
      Returns:
      this builder for method chaining
    • inputKeys

      public McpClientBuilder<T> inputKeys(String... inputKeys)
      Description copied from interface: McpClientBuilder
      Sets 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, so McpClientBuilder.build() fails with an IllegalArgumentException when they are not set, while a typed agent takes them from the parameters of its agent method when they are not set.
      Specified by:
      inputKeys in interface McpClientBuilder<T>
      Parameters:
      inputKeys - the names of the input keys
      Returns:
      this builder for method chaining
    • outputKey

      public McpClientBuilder<T> outputKey(String outputKey)
      Specified by:
      outputKey in interface McpClientBuilder<T>
    • async

      public McpClientBuilder<T> async(boolean async)
      Description copied from interface: McpClientBuilder
      Sets 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:
      async in interface McpClientBuilder<T>
      Parameters:
      async - true for asynchronous invocation
      Returns:
      this builder
    • listener

      public McpClientBuilder<T> listener(AgentListener agentListener)
      Specified by:
      listener in interface McpClientBuilder<T>
    • activationCondition

      public McpClientBuilder<T> activationCondition(String description, Predicate<AgenticScope> activationCondition)
      Description copied from interface: McpClientBuilder
      Sets 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:
      activationCondition in interface McpClientBuilder<T>
    • resolutionTimeout

      public McpClientBuilder<T> resolutionTimeout(Duration resolutionTimeout)
      Description copied from interface: McpClientBuilder
      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. 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 an McpToolResolutionException caused by a TimeoutException. 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 DefaultMcpClient has 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:
      resolutionTimeout in interface McpClientBuilder<T>
      Parameters:
      resolutionTimeout - the time given to the resolution of the MCP tool, or Duration.ZERO or null for no such limit
      Returns:
      this builder for method chaining
    • build

      public T build()
      Specified by:
      build in interface McpClientBuilder<T>
    • invoke

      public Object invoke(Object proxy, Method method, Object[] args) throws Exception
      Specified by:
      invoke in interface InvocationHandler
      Throws:
      Exception
    • setParent

      public void setParent(InternalAgent parent)
      Specified by:
      setParent in interface InternalAgent
    • registerInheritedParentListener

      public void registerInheritedParentListener(AgentListener parentListener)
      Specified by:
      registerInheritedParentListener in interface InternalAgent
    • appendId

      public void appendId(String idSuffix)
      Specified by:
      appendId in interface InternalAgent
    • listener

      public AgentListener listener()
      Specified by:
      listener in interface InternalAgent
    • type

      public Class<?> type()
      Specified by:
      type in interface AgentInstance
    • plannerType

      public Class<? extends Planner> plannerType()
      Specified by:
      plannerType in interface AgentInstance
    • name

      public String name()
      The name, fixed by build(), 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:
      name in interface AgentInstance
    • agentId

      public String agentId()
      Specified by:
      agentId in interface AgentInstance
    • description

      public String description()
      The explicit description, else the one of the MCP tool, which is resolved at this point if not yet done.
      Specified by:
      description in interface AgentInstance
    • outputType

      public Type outputType()
      Specified by:
      outputType in interface AgentInstance
    • outputKey

      public String outputKey()
      Specified by:
      outputKey in interface AgentInstance
    • async

      public boolean async()
      Specified by:
      async in interface AgentInstance
    • activationCondition

      public AgentCondition activationCondition()
      Description copied from interface: AgentInstance
      The condition under which this agent runs when it is invoked as a subagent, or null when it always runs. When the condition is false, the agent is skipped: it is not invoked, it writes nothing to the AgenticScope and 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:
      activationCondition in interface AgentInstance
    • arguments

      public List<AgentArgument> 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:
      arguments in interface AgentInstance
    • parent

      public AgentInstance parent()
      Specified by:
      parent in interface AgentInstance
    • subagents

      public List<AgentInstance> subagents()
      Specified by:
      subagents in interface AgentInstance
    • topology

      public AgenticSystemTopology topology()
      Specified by:
      topology in interface AgentInstance