Package com.rpl.agentorama

Interface AgentTopology

public interface AgentTopology
The agent topology provides the configuration context for defining agents, stores, objects, evaluators, actions, and other infrastructure components within an agent module. The topology provides the configuration context for: Example: 

 public class MyAgentModule extends AgentModule {
   @Override
   protected void defineAgents(AgentTopology topology) {
     topology.declareKeyValueStore("$$myStore", String.class, Integer.class);

     topology.declareAgentObject("openai-api-key", "sk-...");
     topology.declareAgentObjectBuilder("openai-model", setup -> {
       String apiKey = setup.getAgentObject("openai-api-key");
       return OpenAiChatModel.builder()
         .apiKey(apiKey)
         .modelName("gpt-4o-mini")
         .build();
     });

     // Create agents using builder pattern
     topology.newAgent("my-agent")
       .node("start", "process", (AgentNode agentNode, String input) -> {
         KeyValueStore<String, Integer> store = agentNode.getStore("$$myStore");
         store.put("key", 42);
         agentNode.emit("process", "Hello " + input);
       })
       .node("process", (AgentNode agentNode, String input) -> {
         OpenAiChatModel model = agentNode.getAgentObject("openai-model");
         agentNode.result(model.chat(input));
       });
   }
 }

  • Method Details

    • create

      static AgentTopology create(com.rpl.rama.RamaModule.Setup setup, com.rpl.rama.RamaModule.Topologies topologies)
      Creates an agent topology for defining agents and infrastructure. This is used when adding agents to a regular Rama module.
      Parameters:
      setup - the setup object for module configuration
      topologies - the topologies object for defining dataflow topologies
      Returns:
      the agent topology instance

    • newAgent

      AgentGraph newAgent(String name)
      Creates a new agent with the specified name.
      Parameters:
      name - the name of the agent
      Returns:
      the agent graph for defining the agent's execution flow

    • newToolsAgent

      AgentGraph newToolsAgent(String name, List<ToolInfo> tools)
      Creates a new tools agent with the specified name and tools. Tools agents are specialized agents for executing tool calls from AI models. They provide a standardized interface for function calling and tool execution.
      Parameters:
      name - the name of the agent
      tools - the list of tools available to the agent
      Returns:
      the agent graph for defining the agent's execution flow

    • newToolsAgent

      AgentGraph newToolsAgent(String name, List<ToolInfo> tools, ToolsAgentOptions options)
      Creates a new tools agent with the specified name, tools, and options.
      Parameters:
      name - the name of the agent
      tools - the list of tools available to the agent
      options - configuration options for the tools agent
      Returns:
      the agent graph for defining the agent's execution flow

    • declareKeyValueStore

      void declareKeyValueStore(String name, Class keyClass, Class valClass)
      Declares a key-value store for simple typed persistent storage. Store names must start with "$$". Key-value stores provide basic persistent storage with type safety for simple data structures.
      Parameters:
      name - the name of the store (must start with "$$")
      keyClass - the class type for keys
      valClass - the class type for values

    • declareDocumentStore

      void declareDocumentStore(String name, Class keyClass, Object... keyAndValClasses)
      Declares a document store for schema-flexible persistent storage. Document stores provide flexible storage for nested data structures with schema validation capabilities.
      Parameters:
      name - the name of the store (must start with "$$")
      keyClass - the class type for keys
      keyAndValClasses - alternating key and value class types for the document schema

    • declarePStateStore

      com.rpl.rama.PState.Declaration declarePStateStore(String name, Class schema)
      Declares a PState store for direct access to Rama's built-in PState storage,
      Parameters:
      name - the name of the store (must start with "$$")
      schema - the schema class for the PState
      Returns:
      the PState declaration for further configuration

    • declarePStateStore

      com.rpl.rama.PState.Declaration declarePStateStore(String name, com.rpl.rama.PState.Schema schema)
      Declares a PState store for direct access to Rama's built-in PState storage, which are stores defined as any combination of data structures of any size. PStates are durable, replicated, and scalable
      Parameters:
      name - the name of the store (must start with "$$")
      schema - the custom schema for the PState
      Returns:
      the PState declaration for further configuration

    • declareAgentObject

      void declareAgentObject(String name, Object o)
      Declares a static agent object that is shared across all agent executions. Static objects are created once and reused for all agent executions. They are suitable for static information like API keys.
      Parameters:
      name - the name of the agent object
      o - the object instance to share

    • declareAgentObjectBuilder

      void declareAgentObjectBuilder(String name, com.rpl.rama.ops.RamaFunction1<AgentObjectSetup,Object> builder)
      Declares an agent object builder that creates objects on demand. When a node gets an object, it gets exclusive access to it. A pool of up to the configured object limit is created on demand. Exception is when the thread-safe option is set, in which case one object is created and shared for all usage within agents (no pool in this case).
      Parameters:
      name - the name of the agent object
      builder - function that creates the object from setup information

    • declareAgentObjectBuilder

      void declareAgentObjectBuilder(String name, com.rpl.rama.ops.RamaFunction1<AgentObjectSetup,Object> builder, AgentObjectOptions options)
      Declares an agent object builder with configuration options.
      Parameters:
      name - the name of the agent object
      builder - function that creates the object from setup information
      options - configuration options for the object builder

    • declareEvaluatorBuilder

      <Input, RefOutput, Output> void declareEvaluatorBuilder(String name, String description, com.rpl.rama.ops.RamaFunction1<Map<String,String>,com.rpl.rama.ops.RamaFunction4<AgentObjectFetcher,Input,RefOutput,Output,Map>> builder)
      Declares an evaluator builder for measuring agent performance. Evaluator builders return a map of scores, score name (string) to score value (string, boolean, or number). The "fetcher" argument can be used to get agent objects.
      Type Parameters:
      Input - the type of input data
      RefOutput - the type of reference output data
      Output - the type of actual output data
      Parameters:
      name - the name of the evaluator builder
      description - description of what the evaluator measures
      builder - function that creates the evaluator from parameters

    • declareEvaluatorBuilder

      <Input, RefOutput, Output> void declareEvaluatorBuilder(String name, String description, com.rpl.rama.ops.RamaFunction1<Map<String,String>,com.rpl.rama.ops.RamaFunction4<AgentObjectFetcher,Input,RefOutput,Output,Map>> builder, EvaluatorBuilderOptions options)
      Declares an evaluator builder with configuration options.
      Type Parameters:
      Input - the type of input data
      RefOutput - the type of reference output data
      Output - the type of actual output data
      Parameters:
      name - the name of the evaluator builder
      description - description of what the evaluator measures
      builder - function that creates the evaluator from parameters
      options - configuration options for the evaluator builder

    • declareComparativeEvaluatorBuilder

      <Input, RefOutput, Output> void declareComparativeEvaluatorBuilder(String name, String description, com.rpl.rama.ops.RamaFunction1<Map<String,String>,com.rpl.rama.ops.RamaFunction4<AgentObjectFetcher,Input,RefOutput,List<Output>,Map>> builder)
      Declares a comparative evaluator builder for comparing multiple outputs. If a comparative evaluator returns with an "index" key, that is treated specially in the comparative experiment results UI to highlight that output as green as the better result.
      Type Parameters:
      Input - the type of input data
      RefOutput - the type of reference output data
      Output - the type of actual output data
      Parameters:
      name - the name of the evaluator builder
      description - description of what the evaluator measures
      builder - function that creates the evaluator from parameters

    • declareComparativeEvaluatorBuilder

      <Input, RefOutput, Output> void declareComparativeEvaluatorBuilder(String name, String description, com.rpl.rama.ops.RamaFunction1<Map<String,String>,com.rpl.rama.ops.RamaFunction4<AgentObjectFetcher,Input,RefOutput,List<Output>,Map>> builder, EvaluatorBuilderOptions options)
      Declares a comparative evaluator builder with configuration options.
      Type Parameters:
      Input - the type of input data
      RefOutput - the type of reference output data
      Output - the type of actual output data
      Parameters:
      name - the name of the evaluator builder
      description - description of what the evaluator measures
      builder - function that creates the evaluator from parameters
      options - configuration options for the evaluator builder

    • declareSummaryEvaluatorBuilder

      void declareSummaryEvaluatorBuilder(String name, String description, com.rpl.rama.ops.RamaFunction1<Map<String,String>,com.rpl.rama.ops.RamaFunction2<AgentObjectFetcher,List<ExampleRun>,Map>> builder)
      Declares a summary evaluator builder for aggregate metrics in experiments.
      Parameters:
      name - the name of the evaluator builder
      description - description of what the evaluator measures
      builder - function that creates the evaluator from parameters

    • declareSummaryEvaluatorBuilder

      void declareSummaryEvaluatorBuilder(String name, String description, com.rpl.rama.ops.RamaFunction1<Map<String,String>,com.rpl.rama.ops.RamaFunction2<AgentObjectFetcher,List<ExampleRun>,Map>> builder, EvaluatorBuilderOptions options)
      Declares a summary evaluator builder with configuration options.
      Parameters:
      name - the name of the evaluator builder
      description - description of what the evaluator measures
      builder - function that creates the evaluator from parameters
      options - configuration options for the evaluator builder

    • declareActionBuilder

      <Input, Output> void declareActionBuilder(String name, String description, com.rpl.rama.ops.RamaFunction1<Map<String,String>,com.rpl.rama.ops.RamaFunction4<AgentObjectFetcher,List<Input>,Output,RunInfo,Map>> builder)
      Declares an action builder for real-time evaluation on production runs. Actions are user-defined hooks running on live agent executions for real-time evaluation, data capture, etc. They can be parameterized and have concurrency limits controlled by the global config max.limited.actions.concurrency.
      Type Parameters:
      Input - the type of input data
      Output - the type of output data
      Parameters:
      name - the name of the action builder
      description - description of what the action does
      builder - function that creates the action from parameters

    • declareActionBuilder

      <Input, Output> void declareActionBuilder(String name, String description, com.rpl.rama.ops.RamaFunction1<Map<String,String>,com.rpl.rama.ops.RamaFunction4<AgentObjectFetcher,List<Input>,Output,RunInfo,Map>> builder, ActionBuilderOptions options)
      Declares an action builder with configuration options.
      Type Parameters:
      Input - the type of input data
      Output - the type of output data
      Parameters:
      name - the name of the action builder
      description - description of what the action does
      builder - function that creates the action from parameters
      options - configuration options for the action builder

    • declareClusterAgent

      void declareClusterAgent(String localName, String moduleName, String agentName)
      Declares a cluster agent that references an agent in another module. This enables agents to invoke agents in other modules.
      Parameters:
      localName - the local name for the agent
      moduleName - the name of the module containing the agent
      agentName - the name of the agent in the remote module

    • getStreamTopology

      com.rpl.rama.module.StreamTopology getStreamTopology()
      Gets the underlying Rama stream topology.
      Returns:
      the stream topology instance

    • define

      void define()
      Defines the topology for deployment to a Rama cluster. This method must be called after all agents and infrastructure have been declared and is only used when adding an AgentTopology to a regular Rama module.