Package com.rpl.agentorama

Interface AgentNode

All Superinterfaces:
AgentObjectFetcher, com.rpl.agentorama.impl.IFetchAgentClient
public interface AgentNode extends AgentObjectFetcher, com.rpl.agentorama.impl.IFetchAgentClient
Interface for agent node functions to interact with the agent execution environment. Agent nodes are the computational units within an agent graph. This interface provides access to agent objects, stores, streaming, recording trace information, and other execution capabilities. Example: 

 topology.newAgent("myAgent")
         .node("start", "process", (AgentNode agentNode, String input) -> {
           ChatModel model = agentNode.getAgentObject("openai-model");
           KeyValueStore<String, Integer> store = agentNode.getStore("$$myStore");
           store.put("key", 42);
           agentNode.emit("process", "Hello " + input);
         })
         .node("process", null, (AgentNode agentNode, String input) -> {
           agentNode.result("Processing: " + input);
         });

  • Method Details

    • emit

      void emit(String node, Object... args)
      Emits data to another node in the agent graph. The target node must be declared in the outputNodesSpec when creating the agent.
      Parameters:
      node - the name of the target node
      args - arguments to pass to the target node

    • result

      void result(Object arg)
      Sets the final result of the agent execution. This is a first-one wins situation: if multiple nodes return results in parallel, only the first one will be the agent result and others will be dropped.
      Parameters:
      arg - the final result value

    • getMirrorAgentClient

      AgentClient getMirrorAgentClient(String moduleName, String agentName)

    • getStore

      <T extends Store> T getStore(String name)
      Gets a store by name for persistent data access. Store names must start with "$$". Stores are declared in the agent topology using: - AgentTopology.declareKeyValueStore(String, Class, Class) for simple key-value storage - AgentTopology.declareDocumentStore(String, Class, Object...) for schema-flexible nested data - AgentTopology.declarePStateStore(String, Class) for direct Rama PState access
      Parameters:
      name - the name of the store (must start with "$$")
      Returns:
      the store instance

    • getMirrorStore

      <T extends Store> T getMirrorStore(String moduleName, String name)
      Gets a store instance from another module. Stores provide distributed, persistent, replicated storage. Mirror stores are read-only.
      Parameters:
      moduleName - the module where the store exists
      name - the name of the store (declared with declare*Store functions in the target module)
      Returns:
      the store instance with API methods (get, put, etc.)

    • getDepot

      com.rpl.rama.Depot getDepot(String name)
      Gets a depot client within a node. Depots are Rama's append-only logs that can be consumed by any number of topologies.
      Parameters:
      name - the name of the depot (declared in the module)
      Returns:
      Depot instance for appending data

    • getMirrorDepot

      com.rpl.rama.Depot getMirrorDepot(String moduleName, String name)
      Gets a depot instance from another module. Depots are Rama's append-only logs that can be consumed by any number of topologies.
      Parameters:
      moduleName - the module where the depot exists
      name - the name of the depot (declared in the target module)
      Returns:
      Depot instance for appending data

    • getQueryTopologyClient

      <T> com.rpl.rama.QueryTopologyClient<T> getQueryTopologyClient(String name)
      Gets a query topology client for invoking queries within a node.
      Parameters:
      name - the name of the query topology
      Returns:
      QueryTopologyClient instance

    • getMirrorQueryTopologyClient

      <T> com.rpl.rama.QueryTopologyClient<T> getMirrorQueryTopologyClient(String moduleName, String name)
      Gets a query topology client from another module.
      Parameters:
      moduleName - the module where the query topology exists
      name - the name of the query topology
      Returns:
      QueryTopologyClient instance

    • streamChunk

      void streamChunk(Object chunk)
      Streams a chunk of data to clients.
      Parameters:
      chunk - the data chunk to stream

    • recordNestedOp

      void recordNestedOp(NestedOpType nestedOpType, long startTimeMillis, long finishTimeMillis, Map<String,Object> info)
      Records a nested operation for tracing and analytics. Nested operations track internal operations like model calls, database access, and tool calls within an agent execution. The info map provides type-specific metadata for the operation. Special info map usage for certain operation types that gets incorporated into analytics: - model call: "inputTokenCount", "outputTokenCount", "totalTokenCount", "failure" (exception string for failures)

    • getHumanInput

      String getHumanInput(String prompt)
      Requests human input during agent execution. This method blocks until human input is provided. The agent execution will pause until the input is received. The agent will remain in a waiting state unti the human provides a response through the client API or web UI. Since nodes run on virtual threads, this is efficient.
      Parameters:
      prompt - the prompt to show to the human
      Returns:
      the human's response

    • getMetadata

      Map<String,Object> getMetadata()
      Gets metadata associated with this agent execution.
      Returns:
      map of metadata key-value pairs