swf-testbed/example_agents/README.md

0001 # Example Agents
0002
0003 This directory contains simple, standalone agent examples for the SWF testbed,
0004 built upon a reusable base class.
0005
0006 These agents demonstrate the core interaction patterns with the `swf-monitor`
0007 service (via its REST API) and the ActiveMQ message broker. They are designed
0008 to be easy to run and understand, providing a clear blueprint for developing
0009 new, production-grade agents.
0010
0011 The key design is in `base_agent.py`, which provides a `BaseAgent` class
0012 that handles all common infrastructure. The specialized agents
0013 (`example_data_agent.py`, `example_processing_agent.py`) inherit from this
0014 base class and contain only the logic specific to their role.
0015
0016 ## Prerequisites
0017
0018 - Python 3.9+
0019 - An active `swf-monitor` instance with a running REST API.
0020 - A running ActiveMQ broker.
0021
0022 ## Setup
0023
0024 1.  **Create a virtual environment:**
0025     ```bash
0026     python -m venv venv
0027     source venv/bin/activate
0028     ```
0029
0030 2.  **Install dependencies:**
0031     ```bash
0032     pip install -r requirements.txt
0033     ```
0034
0035 ## Configuration
0036
0037 The agents are configured via environment variables, which are read by the
0038 `base_agent.py` script:
0039
0040 - `SWF_MONITOR_URL`: The base URL for the `swf-monitor` REST API (e.g., `http://localhost:8000`).
0041 - `SWF_API_TOKEN`: An authentication token for the REST API.
0042 - `ACTIVEMQ_HOST`: The hostname of the ActiveMQ broker.
0043 - `ACTIVEMQ_PORT`: The port of the ActiveMQ broker.
0044 - `ACTIVEMQ_USER`: The username for the ActiveMQ broker.
0045 - `ACTIVEMQ_PASSWORD`: The password for the ActiveMQ broker.
0046
0047 ### Generating an API Token
0048
0049 To interact with the `swf-monitor` API, you need a token.
0050
0051 1.  **Create a user** (if you haven't already):
0052     ```bash
0053     # Make sure you are in the swf-testbed directory with the venv active
0054     python ../swf-monitor/src/manage.py createsuperuser
0055     ```
0056
0057 2.  **Generate a token for that user:**
0058     ```bash
0059     python ../swf-monitor/src/manage.py drf_create_token <your_username>
0060     ```
0061
0062 3.  **Set the environment variable:**
0063     ```bash
0064     export SWF_API_TOKEN=<your_generated_token>
0065     ```
0066
0067 ## Running an Agent
0068
0069 To run a specific agent, execute its script directly after setting the
0070 required environment variables:
0071
0072 ```bash
0073 # Example for running the Data Agent
0074 export SWF_MONITOR_URL='http://localhost:8000'
0075 export ACTIVEMQ_HOST='localhost'
0076 # ... other variables
0077
0078 python example_data_agent.py
0079 ```