Package com.rpl.agentorama

Interface AgentClient

All Superinterfaces:
AutoCloseable, Closeable
public interface AgentClient extends Closeable
Client for interacting with a specific agent. Agent clients provide the interface for invoking agents, streaming data, handling human input, and managing agent executions. When called from within an agent node function, this enables subagent execution:
  • Can invoke any other agent in the same module (including the current agent)
  • Enables recursive agent execution patterns
  • Enables mutually recursive agent execution between different agents
  • Subagent calls are tracked and displayed in the UI trace
Example: 

 // From client code
 AgentClient client = manager.getAgentClient("my-agent");
 String result = client.invoke("Hello world");

 // From within an agent node (subagent execution)
 AgentClient subClient = agentNode.getAgentClient("other-agent");
 String subResult = subClient.invoke("Process this data");

  • Method Details

    • invoke

      <T> T invoke(Object... args)
      Synchronously invokes an agent with the provided arguments. This method blocks until the agent execution completes and returns the final result. For long-running agents, consider using initiate() with result() for better control.
      Parameters:
      args - arguments to pass to the agent
      Returns:
      the final result from the agent execution

    • invokeAsync

      <T> CompletableFuture<T> invokeAsync(Object... args)
      Asynchronously invokes an agent with the provided arguments. Returns a CompletableFuture that will complete with the agent's result. This allows for non-blocking agent execution and better resource utilization.
      Parameters:
      args - arguments to pass to the agent
      Returns:
      future that completes with the agent result

    • invokeWithContext

      <T> T invokeWithContext(AgentContext context, Object... args)
      Synchronously invokes an agent with context metadata. Metadata allows attaching custom key-value data to agent executions. Metadata is an additional optional parameter to agent execution, and is also used for analytics. Metadata can be accessed anywhere inside agents by calling getMetadata() within node functions.
      Parameters:
      context - context containing metadata for the execution
      args - arguments to pass to the agent
      Returns:
      the final result from the agent execution

    • invokeWithContextAsync

      <T> CompletableFuture<T> invokeWithContextAsync(AgentContext context, Object... args)
      Asynchronously invokes an agent with context metadata.
      Parameters:
      context - context containing metadata for the execution
      args - arguments to pass to the agent
      Returns:
      future that completes with the agent result

    • initiate

      AgentInvoke initiate(Object... args)
      Initiates an agent execution and returns a handle for tracking. This method starts an agent execution but doesn't wait for completion. Use the returned result handle with result(), nextStep(), or streaming methods to interact with the running agent.
      Parameters:
      args - arguments to pass to the agent
      Returns:
      agent invoke handle for tracking and interacting with the execution

    • initiateAsync

      CompletableFuture<AgentInvoke> initiateAsync(Object... args)
      Asynchronously initiates an agent execution and returns a CompletableFuture with a handle for tracking.
      Parameters:
      args - arguments to pass to the agent
      Returns:
      future that completes with the agent invoke handle

    • initiateWithContext

      AgentInvoke initiateWithContext(AgentContext context, Object... args)
      Initiates an agent execution with context metadata.
      Parameters:
      context - context containing metadata for the execution
      args - arguments to pass to the agent
      Returns:
      agent invoke handle for tracking and interacting with the execution

    • initiateWithContextAsync

      CompletableFuture<AgentInvoke> initiateWithContextAsync(AgentContext context, Object... args)
      Asynchronously initiates an agent execution with context metadata.
      Parameters:
      context - context containing metadata for the execution
      args - arguments to pass to the agent
      Returns:
      future that completes with the agent invoke handle

    • fork

      <T> T fork(AgentInvoke invoke, Map<UUID,List> nodeInvokeIdToNewArgs)
      Synchronously forks an agent execution with new arguments for specific nodes. Forking creates new execution branches from an existing agent invocation. The nodeInvokeIdToNewArgs map specifies which nodes to fork and what new arguments to use for each fork. Node invoke IDs can be found in the trace UI.
      Parameters:
      invoke - the agent invoke handle to fork from
      nodeInvokeIdToNewArgs - map from node invoke ID to new arguments for that node
      Returns:
      the result from the forked execution

    • forkAsync

      <T> CompletableFuture<T> forkAsync(AgentInvoke invoke, Map<UUID,List> nodeInvokeIdToNewArgs)
      Asynchronously forks an agent execution with new arguments for specific nodes.
      Parameters:
      invoke - the agent invoke handle to fork from
      nodeInvokeIdToNewArgs - map from node invoke ID to new arguments for that node
      Returns:
      future that completes with the result from the forked execution

    • initiateFork

      AgentInvoke initiateFork(AgentInvoke invoke, Map<UUID,List> nodeInvokeIdToNewArgs)
      Initiates a fork of an agent execution and returns a handle for tracking.
      Parameters:
      invoke - the agent invoke to fork from
      nodeInvokeIdToNewArgs - map from node invoke ID to new arguments for that node
      Returns:
      agent invoke handle for the forked execution

    • initiateForkAsync

      CompletableFuture<AgentInvoke> initiateForkAsync(AgentInvoke invoke, Map<UUID,List> nodeInvokeIdToNewArgs)
      Asynchronously initiates a fork of an agent execution.
      Parameters:
      invoke - the agent invoke handle to fork from
      nodeInvokeIdToNewArgs - map from node invoke ID to new arguments for that node
      Returns:
      future that completes with the agent invoke handle for the forked execution

    • nextStep

      AgentStep nextStep(AgentInvoke invoke)
      Gets the next execution step of an agent. The next execution step is either a human input request or an agent result. Check which one by checking if the returned object is an instance of HumanInputRequest or AgentComplete. If the agent fails, it will throw an exception.
      Parameters:
      invoke - the agent invoke handle to get the next step for
      Returns:
      the next execution step

    • nextStepAsync

      CompletableFuture<AgentStep> nextStepAsync(AgentInvoke invoke)
      Asynchronously gets the next execution step of an agent.
      Parameters:
      invoke - the agent invoke handle to get the next step for
      Returns:
      future that completes with the next execution step

    • result

      <T> T result(AgentInvoke invoke)
      Gets the final result of an agent execution. This method blocks until the agent execution completes and returns the final result. If the agent fails, it will throw an exception.
      Parameters:
      invoke - the agent invoke handle to get the result for
      Returns:
      the final result from the agent execution

    • resultAsync

      <T> CompletableFuture<T> resultAsync(AgentInvoke invoke)
      Asynchronously gets the final result of an agent execution.
      Parameters:
      invoke - the agent invoke handle to get the result for
      Returns:
      future that completes with the final result from the agent execution

    • isAgentInvokeComplete

      boolean isAgentInvokeComplete(AgentInvoke invoke)
      Checks if an agent execution has completed.
      Parameters:
      invoke - the agent invoke handle to check
      Returns:
      true if the agent execution is complete

    • setMetadata

      void setMetadata(AgentInvoke invoke, String key, int value)
      Sets metadata for an agent execution. Note: For agent execution, only the metadata that was set at the start with the *WithContext functions is used.
      Parameters:
      invoke - the agent invoke handle to set metadata for
      key - the metadata key
      value - the metadata value

    • setMetadata

      void setMetadata(AgentInvoke invoke, String key, long value)
      Sets metadata for an agent execution.
      Parameters:
      invoke - the agent invoke handle to set metadata for
      key - the metadata key
      value - the metadata value

    • setMetadata

      void setMetadata(AgentInvoke invoke, String key, float value)
      Sets metadata for an agent execution.
      Parameters:
      invoke - the agent invoke handle to set metadata for
      key - the metadata key
      value - the metadata value

    • setMetadata

      void setMetadata(AgentInvoke invoke, String key, double value)
      Sets metadata for an agent execution.
      Parameters:
      invoke - the agent invoke handle to set metadata for
      key - the metadata key
      value - the metadata value

    • setMetadata

      void setMetadata(AgentInvoke invoke, String key, String value)
      Sets metadata for an agent execution.
      Parameters:
      invoke - the agent invoke handle to set metadata for
      key - the metadata key
      value - the metadata value

    • setMetadata

      void setMetadata(AgentInvoke invoke, String key, boolean value)
      Sets metadata for an agent execution.
      Parameters:
      invoke - the agent invoke handle to set metadata for
      key - the metadata key
      value - the metadata value

    • removeMetadata

      void removeMetadata(AgentInvoke invoke, String key)
      Removes metadata from an agent execution.
      Parameters:
      invoke - the agent invoke handle to remove metadata from
      key - the metadata key to remove

    • getMetadata

      Map<String,Object> getMetadata(AgentInvoke invoke)
      Gets all metadata for an agent execution.
      Parameters:
      invoke - the agent invoke handle to get metadata for
      Returns:
      map of metadata key-value pairs

    • stream

      AgentStream stream(AgentInvoke invoke, String node)
      Creates a stream for data emitted from a specific node. The returned object can have close() called on it to immediately stop streaming.
      Parameters:
      invoke - the agent invoke handle to stream from
      node - the node name to stream data from
      Returns:
      stream object for accessing chunks and controlling streaming

    • stream

      <T> AgentStream stream(AgentInvoke invoke, String node, AgentClient.StreamCallback<T> callback)
      Creates a stream for data emitted from a specific node with a callback.
      Parameters:
      invoke - the agent invoke handle to stream from
      node - the node name to stream data from
      callback - callback function for handling stream updates
      Returns:
      stream object for accessing chunks and controlling streaming

    • streamSpecific

      AgentStream streamSpecific(AgentInvoke invoke, String node, UUID nodeInvokeId)
      Creates a stream for data emitted from a specific node invocation.
      Parameters:
      invoke - the agent invoke to stream from
      node - the node name to stream data from
      nodeInvokeId - the specific node invocation ID to stream from, which can be found in the trace UI.
      Returns:
      stream object for accessing chunks and controlling streaming

    • streamSpecific

      <T> AgentStream streamSpecific(AgentInvoke invoke, String node, UUID nodeInvokeId, AgentClient.StreamCallback<T> callback)
      Creates a stream for data emitted from a specific node invocation with a callback.
      Parameters:
      invoke - the agent invoke to stream from
      node - the node name to stream data from
      nodeInvokeId - the specific node invocation ID to stream from, which can be found in the trace UI.
      callback - callback function for handling stream updates
      Returns:
      stream object for accessing chunks and controlling streaming

    • streamAll

      AgentStreamByInvoke streamAll(AgentInvoke invoke, String node)
      Creates a stream for data emitted from all invocations of a specific node. The returned object can have close() called on it to immediately stop streaming.
      Parameters:
      invoke - the agent invoke handle to stream from
      node - the node name to stream data from
      Returns:
      stream object for accessing chunks grouped by invoke ID

    • streamAll

      <T> AgentStreamByInvoke streamAll(AgentInvoke invoke, String node, AgentClient.StreamAllCallback<T> callback)
      Creates a stream for data emitted from all invocations of a specific node with a callback.
      Parameters:
      invoke - the agent invoke to stream from
      node - the node name to stream data from
      callback - callback function for handling stream updates
      Returns:
      stream object for accessing chunks grouped by invoke ID

    • pendingHumanInputs

      List<HumanInputRequest> pendingHumanInputs(AgentInvoke invoke)
      Gets all pending human input requests for an agent execution.
      Parameters:
      invoke - the agent invoke to get pending inputs for
      Returns:
      list of pending human input requests

    • pendingHumanInputsAsync

      CompletableFuture<List<HumanInputRequest>> pendingHumanInputsAsync(AgentInvoke invoke)
      Asynchronously gets all pending human input requests for an agent execution.
      Parameters:
      invoke - the agent invoke to get pending inputs for
      Returns:
      future that completes with the list of pending human input requests

    • provideHumanInput

      void provideHumanInput(HumanInputRequest request, String response)
      Provides a response to a human input request.
      Parameters:
      request - the human input request to respond to
      response - the response text

    • provideHumanInputAsync

      CompletableFuture<Void> provideHumanInputAsync(HumanInputRequest request, String response)
      Asynchronously provides a response to a human input request.
      Parameters:
      request - the human input request to respond to
      response - the response text
      Returns:
      future that completes when the response is provided