Package com.scivicslab.turingworkflow.plugins.llm

Class LlmActor

java.lang.Object
com.scivicslab.pojoactor.core.ActorRef<LlmActor>
com.scivicslab.turingworkflow.workflow.IIActorRef<LlmActor>
com.scivicslab.turingworkflow.plugins.llm.LlmActor
All Implemented Interfaces:
com.scivicslab.pojoactor.core.CallableByActionName, AutoCloseable
public class LlmActor extends com.scivicslab.turingworkflow.workflow.IIActorRef<LlmActor>
Actor that calls an LLM service via MCP (Model Context Protocol) Streamable HTTP transport.

Default target: quarkus-chat-ui-claude at localhost:8090. Can be dynamically loaded via loader.loadMaven in workflow YAML.

Supported actions:

  • setUrl - Configure the MCP server base URL
  • prompt - Send a prompt to the LLM and receive a response
  • status - Query the LLM service status
  • listTools - List available tools on the MCP server
Since:
1.0.0
Author:
devteam@scivicslab.com

  • Field Summary

    Fields inherited from class com.scivicslab.pojoactor.core.ActorRef

    actorName, actorSystem, object

  • Constructor Summary

    Constructors
    Constructor
    Description
    LlmActor(String name, com.scivicslab.turingworkflow.workflow.IIActorSystem system)
    Creates a new LlmActor with the given name and actor system.

  • Method Summary

    Modifier and Type
    Method
    Description
    com.scivicslab.pojoactor.core.ActionResult
    callAgent(String args)
    Calls the call_agent tool on the MCP Gateway, which routes the prompt to a named agent and blocks until the reply arrives (up to 5 minutes).
    com.scivicslab.pojoactor.core.ActionResult
    listTools(String args)
    Lists available tools on the MCP server via the tools/list JSON-RPC method.
    com.scivicslab.pojoactor.core.ActionResult
    prompt(String promptText)
    Sends a prompt to the LLM via the MCP tools/call method.
    void
    setOutputListener(Consumer<String> listener)
    Sets an output listener that will be called with status messages, LLM responses, and error notifications.
    com.scivicslab.pojoactor.core.ActionResult
    setUrl(String url)
    Sets the MCP server base URL.
    com.scivicslab.pojoactor.core.ActionResult
    status(String args)
    Retrieves the LLM service status via the MCP tools/call method.

    Methods inherited from class com.scivicslab.turingworkflow.workflow.IIActorRef

    callByActionName, hasAnnotatedAction, invokeAnnotatedAction, parseFirstArgument

    Methods inherited from class com.scivicslab.pojoactor.core.ActorRef

    ask, ask, askNow, clearJsonState, clearPendingMessages, close, createChild, expandVariables, getJsonBoolean, getJsonInt, getJsonString, getJsonString, getLastResult, getName, getNamesOfChildren, getParentName, hasJson, hasJsonState, initLogger, isAlive, json, putJson, setLastResult, setParentName, system, tell, tell, tellNow, toStringOfJson, toStringOfYaml

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • LlmActor

      public LlmActor(String name, com.scivicslab.turingworkflow.workflow.IIActorSystem system)
      Creates a new LlmActor with the given name and actor system.
      Parameters:
      name - the actor name used for identification within the workflow
      system - the actor system this actor belongs to

  • Method Details

    • setOutputListener

      public void setOutputListener(Consumer<String> listener)
      Sets an output listener that will be called with status messages, LLM responses, and error notifications.
      Parameters:
      listener - a consumer that receives output messages, or null to disable

    • setUrl

      public com.scivicslab.pojoactor.core.ActionResult setUrl(String url)
      Sets the MCP server base URL. Resets any existing MCP session.

      Expected argument: the base URL string (e.g., "http://localhost:8090/mcp").

      Parameters:
      url - the MCP server base URL; must not be null or blank
      Returns:
      an ActionResult indicating success with the configured URL, or failure if the URL is missing

    • prompt

      public com.scivicslab.pojoactor.core.ActionResult prompt(String promptText)
      Sends a prompt to the LLM via the MCP tools/call method.

      Expected argument: the prompt text as a plain string. The prompt is sent to the sendPrompt tool on the MCP server with an empty model selector (server default).

      Parameters:
      promptText - the prompt text to send; must not be null or blank
      Returns:
      an ActionResult containing the LLM response text on success, or an error message on failure

    • status

      public com.scivicslab.pojoactor.core.ActionResult status(String args)
      Retrieves the LLM service status via the MCP tools/call method.

      Expected argument: ignored (may be null or empty).

      Parameters:
      args - unused argument (required by the action framework signature)
      Returns:
      an ActionResult containing the status information on success, or an error message on failure

    • listTools

      public com.scivicslab.pojoactor.core.ActionResult listTools(String args)
      Lists available tools on the MCP server via the tools/list JSON-RPC method.

      Expected argument: ignored (may be null or empty).

      Parameters:
      args - unused argument (required by the action framework signature)
      Returns:
      an ActionResult containing the JSON list of available tools on success, or an error message on failure

    • callAgent

      public com.scivicslab.pojoactor.core.ActionResult callAgent(String args)
      Calls the call_agent tool on the MCP Gateway, which routes the prompt to a named agent and blocks until the reply arrives (up to 5 minutes).

      Expected argument formats:

      • JSON array: ["agentName", "prompt text"]
      • JSON object: {"agent": "agentName", "prompt": "text", "model": "sonnet"}
      Parameters:
      args - JSON array or object containing agent name and prompt
      Returns:
      an ActionResult containing the agent's reply on success