From 0841869217e167ec374c68a0d43cd718e0379f34 Mon Sep 17 00:00:00 2001 From: kevin Date: Tue, 11 Feb 2025 16:13:57 +0000 Subject: [PATCH 1/6] add guide --- docs/guides/watcher.md | 102 +++++++++++++++++++++++++++++++++++++++++ mkdocs.yml | 2 + 2 files changed, 104 insertions(+) create mode 100644 docs/guides/watcher.md diff --git a/docs/guides/watcher.md b/docs/guides/watcher.md new file mode 100644 index 00000000..fe92612a --- /dev/null +++ b/docs/guides/watcher.md @@ -0,0 +1,102 @@ +# Guide: Creating a Whale Watcher Agent + +This guide walks you through creating a whale watcher agent that monitors blockchain transactions for transfers. + +**Note**: Replace `author` in the commands below with your author name (e.g., alice, bob, etc.) + +**Tip**: To see the complete implementation, you can fetch the finished agent: + +```bash +aea fetch bafybeia3yyss6j3ac2hbhmhg7o7mbytspe4cgqfrpg6y5eskowln2rlqxe +``` +## 1. Create the FSM Definition + +Create `whale_watcher_fsm.yaml`: + +```yaml +alphabet_in: + - BLOCK_RECEIVED # A new Ethereum block is detected + - TX_OVER_THRESHOLD # A transaction exceeds the whale threshold + - TX_UNDER_THRESHOLD # A transaction is under the whale threshold + - DONE # All transactions for this block are processed + - TIMEOUT # A timeout or other error occurs + +default_start_state: SetupRound +label: WhaleWatcherAbciApp + +states: + - SetupRound + - IdleRound + - BlockReceivedRound + - AlertRound + - DoneRound + - ErrorRound + +start_states: + - SetupRound + +final_states: + - ErrorRound + - DoneRound + +transition_func: + (SetupRound, DONE): IdleRound + (IdleRound, BLOCK_RECEIVED): BlockReceivedRound + (BlockReceivedRound, TX_OVER_THRESHOLD): AlertRound + (BlockReceivedRound, TX_UNDER_THRESHOLD): BlockReceivedRound + (BlockReceivedRound, DONE): DoneRound + (AlertRound, DONE): DoneRound + (DoneRound, DONE): SetupRound + (IdleRound, DONE): SetupRound + (BlockReceivedRound, TIMEOUT): ErrorRound + (AlertRound, TIMEOUT): ErrorRound +``` + +## 2. Create Agent from FSM + +Generate the initial agent structure from the FSM definition: + +```bash +adev create_from_fsm author/whale_watcher whale_watcher_fsm.yaml +``` + +## 3. Add Required Components + +Install the necessary contract and connection: + +```bash +cd whale_watcher +aea add connection bafybeigntoericenpzvwejqfuc3kqzo2pscs76qoygg5dbj6f4zxusru5e +aea add contract bafybeigovz3fg5g46f5geyy33fpvuof3ewktslxswipk37fqpmfj42uysi +``` + +## 4. Eject and Customize the Skill + +```bash +adev eject skill author/whale_watcher_abci_app author/whale_watcher_abci_app +``` + +## 5. Implement the Components + +Create the following files in your skill directory: + +- `behaviours.py`: Implements the FSM behavior states +- `dialogues.py`: Handles dialogue management +- `handlers.py`: Implements message handlers +- `skill.yaml`: Configures the skill components + +## 6. Publish the Agent + +```bash +cd whale_watcher +adev publish author/whale_watcher --force +``` + +## 7. Run the Agent + +```bash +cd .. +adev run dev author/whale_watcher --force +``` + +For detailed implementation of each component, refer to the code examples in the previous sections. \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 4efeb830..baf38030 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -10,6 +10,8 @@ nav: - FSM: fsm.md - OpenAPI: openapi.md - Data Access Object: dao.md +- Guides: + - Watcher: guides/watcher.md - Commands: - augment: commands/augment.md - convert: commands/convert.md From 04e84345f2f1e53809bf9999b61391022b33b73a Mon Sep 17 00:00:00 2001 From: kevin Date: Tue, 11 Feb 2025 16:20:53 +0000 Subject: [PATCH 2/6] note update --- docs/guides/watcher.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/guides/watcher.md b/docs/guides/watcher.md index fe92612a..e1ada7eb 100644 --- a/docs/guides/watcher.md +++ b/docs/guides/watcher.md @@ -97,6 +97,4 @@ adev publish author/whale_watcher --force ```bash cd .. adev run dev author/whale_watcher --force -``` - -For detailed implementation of each component, refer to the code examples in the previous sections. \ No newline at end of file +``` \ No newline at end of file From b1b1bfd1859778b2ddd29bdf7e3a34fcba569908 Mon Sep 17 00:00:00 2001 From: kevin Date: Tue, 11 Feb 2025 17:27:08 +0000 Subject: [PATCH 3/6] update to include note on how to convert and run --- docs/guides/watcher.md | 24 +++++++++++++++++++----- 1 file changed, 19 insertions(+), 5 deletions(-) diff --git a/docs/guides/watcher.md b/docs/guides/watcher.md index e1ada7eb..eb859aa0 100644 --- a/docs/guides/watcher.md +++ b/docs/guides/watcher.md @@ -4,11 +4,6 @@ This guide walks you through creating a whale watcher agent that monitors blockc **Note**: Replace `author` in the commands below with your author name (e.g., alice, bob, etc.) -**Tip**: To see the complete implementation, you can fetch the finished agent: - -```bash -aea fetch bafybeia3yyss6j3ac2hbhmhg7o7mbytspe4cgqfrpg6y5eskowln2rlqxe -``` ## 1. Create the FSM Definition Create `whale_watcher_fsm.yaml`: @@ -97,4 +92,23 @@ adev publish author/whale_watcher --force ```bash cd .. adev run dev author/whale_watcher --force +``` + +## 8. (optional) convert the agent to a service + +```bash +adev convert author/whale_watcher author/finished_whale_watcher +``` +and then run it + +```bash +autonomy generate-key ethereum -n 1 + +adev run prod author_finished_whale_watcher +``` + +To see the complete implementation, you can fetch the finished agent: + +```bash +aea fetch bafybeia3yyss6j3ac2hbhmhg7o7mbytspe4cgqfrpg6y5eskowln2rlqxe ``` \ No newline at end of file From 98d5a89d8d95e883c69639d03918776833f06c2a Mon Sep 17 00:00:00 2001 From: kevin Date: Tue, 11 Feb 2025 22:25:21 +0000 Subject: [PATCH 4/6] typo --- docs/guides/watcher.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/watcher.md b/docs/guides/watcher.md index eb859aa0..66107cce 100644 --- a/docs/guides/watcher.md +++ b/docs/guides/watcher.md @@ -104,7 +104,7 @@ and then run it ```bash autonomy generate-key ethereum -n 1 -adev run prod author_finished_whale_watcher +adev run prod author/finished_whale_watcher ``` To see the complete implementation, you can fetch the finished agent: From 8fbe094123e7b03c0979744dec7deccbe6d23481 Mon Sep 17 00:00:00 2001 From: kevin Date: Wed, 12 Feb 2025 11:55:29 +0000 Subject: [PATCH 5/6] make from mermaid --- docs/guides/watcher.md | 78 ++++++++++++++++++++---------------------- 1 file changed, 38 insertions(+), 40 deletions(-) diff --git a/docs/guides/watcher.md b/docs/guides/watcher.md index 66107cce..8bd6ae9a 100644 --- a/docs/guides/watcher.md +++ b/docs/guides/watcher.md @@ -6,47 +6,45 @@ This guide walks you through creating a whale watcher agent that monitors blockc ## 1. Create the FSM Definition -Create `whale_watcher_fsm.yaml`: - -```yaml -alphabet_in: - - BLOCK_RECEIVED # A new Ethereum block is detected - - TX_OVER_THRESHOLD # A transaction exceeds the whale threshold - - TX_UNDER_THRESHOLD # A transaction is under the whale threshold - - DONE # All transactions for this block are processed - - TIMEOUT # A timeout or other error occurs - -default_start_state: SetupRound -label: WhaleWatcherAbciApp - -states: - - SetupRound - - IdleRound - - BlockReceivedRound - - AlertRound - - DoneRound - - ErrorRound - -start_states: - - SetupRound - -final_states: - - ErrorRound - - DoneRound - -transition_func: - (SetupRound, DONE): IdleRound - (IdleRound, BLOCK_RECEIVED): BlockReceivedRound - (BlockReceivedRound, TX_OVER_THRESHOLD): AlertRound - (BlockReceivedRound, TX_UNDER_THRESHOLD): BlockReceivedRound - (BlockReceivedRound, DONE): DoneRound - (AlertRound, DONE): DoneRound - (DoneRound, DONE): SetupRound - (IdleRound, DONE): SetupRound - (BlockReceivedRound, TIMEOUT): ErrorRound - (AlertRound, TIMEOUT): ErrorRound +First, create a Mermaid diagram to visualize the FSM. Create `whale_watcher_diagram.mmd`: + +```mermaid +stateDiagram-v2 + [*] --> SetupRound: Start + SetupRound --> IdleRound: DONE + IdleRound --> BlockReceivedRound: BLOCK_RECEIVED + BlockReceivedRound --> AlertRound: TX_OVER_THRESHOLD + BlockReceivedRound --> BlockReceivedRound: TX_UNDER_THRESHOLD + BlockReceivedRound --> DoneRound: DONE + AlertRound --> DoneRound: DONE + DoneRound --> SetupRound: DONE + IdleRound --> SetupRound: DONE + BlockReceivedRound --> ErrorRound: TIMEOUT + AlertRound --> ErrorRound: TIMEOUT + ErrorRound --> [*]: DONE + DoneRound --> [*]: DONE ``` +This diagram represents the following states and transitions: +- `SetupRound`: Initial setup and configuration +- `IdleRound`: Waiting for new blocks +- `BlockReceivedRound`: Processing a new block's transactions +- `AlertRound`: Handling whale transactions +- `DoneRound`: Completed processing +- `ErrorRound`: Error handling state + +Now convert the Mermaid diagram to FSM specification: + +```bash +adev fsm from-file whale_watcher_diagram.mmd WhaleWatcherAbciApp --in-type mermaid --output fsm_spec > whale_watcher_fsm.yaml +``` + +This will create `whale_watcher_fsm.yaml` with the FSM specification that includes: +- Input alphabet (events like BLOCK_RECEIVED, TX_OVER_THRESHOLD) +- States and transitions +- Start and final states +- Complete transition function + ## 2. Create Agent from FSM Generate the initial agent structure from the FSM definition: @@ -110,5 +108,5 @@ adev run prod author/finished_whale_watcher To see the complete implementation, you can fetch the finished agent: ```bash -aea fetch bafybeia3yyss6j3ac2hbhmhg7o7mbytspe4cgqfrpg6y5eskowln2rlqxe +aea fetch bafybeicr5wi5r4f272rxybgb4jcpksnylktm5qnzi3ldltbdxnjk4yq24e ``` \ No newline at end of file From 257925a039d17057ef336dfbba6a5ca4fa031271 Mon Sep 17 00:00:00 2001 From: 8ball030 <35799987+8ball030@users.noreply.github.com> Date: Wed, 12 Feb 2025 14:01:00 +0000 Subject: [PATCH 6/6] Update watcher.md --- docs/guides/watcher.md | 48 +++++++++++++++++++++++++++++++++++++----- 1 file changed, 43 insertions(+), 5 deletions(-) diff --git a/docs/guides/watcher.md b/docs/guides/watcher.md index 8bd6ae9a..675f0cb7 100644 --- a/docs/guides/watcher.md +++ b/docs/guides/watcher.md @@ -2,11 +2,35 @@ This guide walks you through creating a whale watcher agent that monitors blockchain transactions for transfers. +Auto Dev will scaffold the enitre project allowing you to focus on the business logic of the application, rather than the structure. + **Note**: Replace `author` in the commands below with your author name (e.g., alice, bob, etc.) -## 1. Create the FSM Definition +### Steps +- Plan the agent +- Scaffold the agent +- Implement the business logic + +## 1. Create the FSM Specification from a Mermaid Diagram -First, create a Mermaid diagram to visualize the FSM. Create `whale_watcher_diagram.mmd`: +First, create a [Mermaid diagram](https://mermaid.live/edit#pako:eNqNkm1rgzAQx7-K3MuhZZr5-GKw1kDLugralrE5StD0gakpaSzrit99me2U0TqWV7n__e5yd7kjJCyl4MFOEEH9DVlxkmt7Iy4UeV5v3hRNu1ciKsptyMoi9ZRIEC5O7lauqVGa0TPkBxN8YhqxRvoZS95DmtDNnqZntj8OBo-LEA_waI79U9QlV4c_ZJSLc9j0eRHMcbiYDkMcDYPx35HXHpYZZhP_3yl8Vly211bUzTTixSy7xnSd6agLc874T0ujJxzMpldr6-RaR83JT--uvnGCCjnlOdmkcnmO32gMYk1zGoMnryldkjITMcRFJVFSChYdigQ8wUuqAmflag3ekmQ7aZXbtF2-Rt2S4oWxXzZ4R_gAT0NIN3ro1kSW7bqW4dhIhYPULVfvmbZu39kWMl1Hr1T4rFMYPUvXkYtcwzEN20GGWX0BPbntug) to visualize the FSM. Create `whale_watcher_diagram.mmd`: + +```text +stateDiagram-v2 + [*] --> SetupRound: Start + SetupRound --> IdleRound: DONE + IdleRound --> BlockReceivedRound: BLOCK_RECEIVED + BlockReceivedRound --> AlertRound: TX_OVER_THRESHOLD + BlockReceivedRound --> BlockReceivedRound: TX_UNDER_THRESHOLD + BlockReceivedRound --> DoneRound: DONE + AlertRound --> DoneRound: DONE + DoneRound --> SetupRound: DONE + IdleRound --> SetupRound: DONE + BlockReceivedRound --> ErrorRound: TIMEOUT + AlertRound --> ErrorRound: TIMEOUT + ErrorRound --> [*]: DONE + DoneRound --> [*]: DONE +``` ```mermaid stateDiagram-v2 @@ -33,7 +57,7 @@ This diagram represents the following states and transitions: - `DoneRound`: Completed processing - `ErrorRound`: Error handling state -Now convert the Mermaid diagram to FSM specification: +Now convert the Mermaid diagram to FSM specification which is used to scaffold the agent. ```bash adev fsm from-file whale_watcher_diagram.mmd WhaleWatcherAbciApp --in-type mermaid --output fsm_spec > whale_watcher_fsm.yaml @@ -45,6 +69,8 @@ This will create `whale_watcher_fsm.yaml` with the FSM specification that includ - Start and final states - Complete transition function +The [FSM SPecification](https://docs.autonolas.network/open-autonomy/key_concepts/fsm/) defines the states that the agent will move between. + ## 2. Create Agent from FSM Generate the initial agent structure from the FSM definition: @@ -53,7 +79,19 @@ Generate the initial agent structure from the FSM definition: adev create_from_fsm author/whale_watcher whale_watcher_fsm.yaml ``` -## 3. Add Required Components +This will create an agent with a very basic fsm in place. + +The agent will be ejected to the local packages registry. + +### 2.a) (OPTIONAL) + +Run generated tests to verify the agent; + +```bash +adev test -p packages/author/agents/whale_watcher +``` + +## 3. Extend the Scaffold to interact with contracts and components. Install the necessary contract and connection: @@ -109,4 +147,4 @@ To see the complete implementation, you can fetch the finished agent: ```bash aea fetch bafybeicr5wi5r4f272rxybgb4jcpksnylktm5qnzi3ldltbdxnjk4yq24e -``` \ No newline at end of file +```