Skip to main content

Agent Modules

In this section, we'll cover:

🤖 What is an Agent Module?​

The core of the Agent Module is the loop or logic that an agent runs. Some examples of agents that use different loops include:

  • Chat Agents
    Simple conversational agents that can engage in dialogue. These agents receive a request and send a response.
  • ReAct Agents Agents that follow the Reason-Act pattern for structured problem solving. First a reasoning step is performed to determine the best action to take. Then an action is executed.
  • Cognitive Agents Agents that follow the Perceive-Act-Reflect loop, where they perceive their environment, take actions, and reflect on the outcomes to improve future decisions. This kind of loop is used by cognitive architectures like SOAR and ACT-R.

The code for this loop is usually contained in the run.py file of the agent module (for a detailed breakdown of the structure of an agent module, see the overview page).

📝 Agent Configurations​

As well as the core loop, Agent Modules are configured by specifying:

  • An LLM Configuration - The language model that the agent uses to generate responses
  • System Prompts - Define the data that will be passed to the LLM along with inputs
  • Persona Module - Additional personality traits and characteristics loaded into the system prompt

The configuration of an agent module can be specified using the AgentConfig class:

#naptha_sdk/schemas.py
class AgentConfig(BaseModel):
    config_name: Optional[str] = "agent_config"
    llm_config: Optional[LLMConfig] = None
    persona_module: Optional[Union[Dict, BaseModel]] = None
    system_prompt: Optional[Union[Dict, BaseModel]] = None

🐋 Agent Deployments​

Agent deployments allow you to specify other modules that the agent module interacts with:

  • Tools/Skills - Capabilities that agents can use to interact with external systems
  • Environments - Environments that the agent interacts with
  • Knowledge Bases - Knowledge bases that the agent can interact with
  • Memory - Contextual storage enabling agents to maintain state and learn from interactions

They also allow you to specify the node that the agent will run on, and the module that the agent will use. The configuration of an agent deployment can be specified using the AgentDeployment class:

#naptha_sdk/schemas.py
class AgentDeployment(BaseModel):
    node: Union[NodeConfigUser, NodeConfig, Dict]
    name: Optional[str] = None
    module: Optional[Dict] = None
    config: Optional[AgentConfig] = None
    data_generation_config: Optional[DataGenerationConfig] = None
    tool_deployments: Optional[List[ToolDeployment]] = None
    environment_deployments: Optional[List[EnvironmentDeployment]] = None
    kb_deployments: Optional[List[KBDeployment]] = None
    memory_deployments: Optional[List[MemoryDeployment]] = None

🚀 Running an Agent Module​

Prerequisites​

Install the Naptha SDK using the instructions here.

Example​

The Hello World Agent is the simplest example of an agent that prints hello. You can deploy the agent (without running) using:

# usage: naptha create <agent_name>
naptha create agent:hello_world_agent

Run the agent:

# usage: naptha run <agent_name> <agent args>
naptha run agent:hello_world_agent -p "firstname=sam surname=altman"

Try running the Simple Chat Agent that uses the local LLM running on your node:

naptha run agent:simple_chat_agent -p "tool_name='chat' tool_input_data='what is an ai agent?'"
note

You can modify the llm_config of the agent run from the default value by passing in a config object in the command line: --config '{"llm_config": {"config_name": "model_1"}}'

The configuration of an agent module is specified in the deployment.json file in the configs folder of the module.

# AgentConfig in deployment.json file 
[
    {
        ...
        "config": {
            "config_name": "agent_config",
            "llm_config": {"config_name": "model_1"},
            "persona_module" : {"name": "richard_twitter"},
            "system_prompt": {
                "role": "You are a helpful AI assistant.",
                "persona": ""
            }
        }
    }
]
info

For details on how to run LLM inference within modules, see the LLM Inference page.

For an example of calling an agent from Python (within an orchestrator module that uses an agent module), see the Orchestrator Modules page.

Examples​

Check out these sample agent modules:

Need Help?​

  • Join our Community and post in the #support channel
  • Submit issues on GitHub

Next Steps​