Annotation Interface McpClientAgent


@Retention(RUNTIME) @Target(METHOD) public @interface McpClientAgent
Marks a method as an MCP client agent that wraps a single MCP tool as a non-AI agent. The MCP client is obtained from the McpClientSupplier method and the tool is looked up on the MCP server the first time they are needed, which is normally the first invocation of the agent, never when the agentic system is built.
  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    boolean
    If true, the agent will be invoked in an asynchronous manner, allowing the workflow to continue without waiting for the agent's result.
    Description of the agent.
    Name of the agent.
    Key of the output variable that will be used to store the result of the agent's invocation.
    int
    Number of seconds given to the resolution of the MCP tool, that is the creation of the MCP client by the McpClientSupplier method 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.
    Name of the MCP tool to bind and invoke as non-AI agent.
    Class<? extends TypedKey<?>>
    Strongly typed key of the output variable that will be used to store the result of the agent's invocation.
    Description of the agent.
  • Element Details

    • toolName

      String toolName
      Name of the MCP tool to bind and invoke as non-AI agent. If not provided, the single tool exposed by the MCP server is bound, and the first invocation of the agent fails when the server exposes more than one.
      Returns:
      name of the MCP tool.
      Default:
      ""
    • name

      String name
      Name of the agent. If not provided, method name will be used. The name is known without contacting the MCP server and never changes, not even after the tool has been resolved.
      Returns:
      name of the agent.
      Default:
      ""
    • value

      String value
      Description of the agent. This is an alias of the description attribute, and it is possible to use either. It should be clear and descriptive to allow language model to understand the agent's purpose and its intended use. If not provided, the description of the MCP tool is used, which is read from the MCP server the first time the description is requested.
      Returns:
      description of the agent.
      Default:
      ""
    • description

      String description
      Description of the agent. This is an alias of the value attribute, and it is possible to use either. It should be clear and descriptive to allow language model to understand the agent's purpose and its intended use. If not provided, the description of the MCP tool is used, which is read from the MCP server the first time the description is requested.
      Returns:
      description of the agent.
      Default:
      ""
    • outputKey

      String outputKey
      Key of the output variable that will be used to store the result of the agent's invocation.
      Returns:
      name of the output variable.
      Default:
      ""
    • typedOutputKey

      Class<? extends TypedKey<?>> typedOutputKey
      Strongly typed key of the output variable that will be used to store the result of the agent's invocation. It enforces type safety when retrieving the output from the agent's state and can be used in alternative to the outputKey() attribute. Note that only one of those two attributes can be used at a time.
      Returns:
      class representing the typed output variable.
      Default:
      dev.langchain4j.agentic.Agent.NoTypedKey.class
    • async

      boolean async
      If true, the agent will be invoked in an asynchronous manner, 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.

      Returns:
      true if the agent should be invoked in an asynchronous manner, false otherwise.
      Default:
      false
    • resolutionTimeoutSeconds

      int resolutionTimeoutSeconds
      Number of seconds given to the resolution of the MCP tool, that is the creation of the MCP client by the McpClientSupplier method 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. When the tool is not resolved within this time 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.
      Returns:
      the number of seconds given to the resolution of the MCP tool, 0 for no limit other than the timeouts of the MCP client itself, or -1, which is the default, for the default of an MCP client agent, which is no limit either. Any other negative value is rejected when the agent is built.
      Since:
      1.24.0
      Default:
      -1