From b4070eb44c951711b5f2c9d735cfce01d85407c1 Mon Sep 17 00:00:00 2001
From: matt <matt@griptape.ai>
Date: Tue, 15 Oct 2024 13:49:31 -0500
Subject: [PATCH] docs

---
 docs/griptape-framework/misc/events.md        | 20 ++++++++
 .../misc/src/events_no_publish.py             | 49 +++++++++++++++++++
 2 files changed, 69 insertions(+)
 create mode 100644 docs/griptape-framework/misc/src/events_no_publish.py

diff --git a/docs/griptape-framework/misc/events.md b/docs/griptape-framework/misc/events.md
index d33514f8a..15cb39fec 100644
--- a/docs/griptape-framework/misc/events.md
+++ b/docs/griptape-framework/misc/events.md
@@ -152,3 +152,23 @@ User: Write me a poem.
 Assistant:
 ...
 ```
+
+## `EventListenerDriver.handler` Return Value Behavior
+
+The value that gets returned from the [`EventListener.handler`](../../reference/griptape/events/event_listener.md#griptape.events.EventListener.handler) will determine what gets sent to the `event_listener_driver`.
+
+### `EventListener.handler` is None
+
+By default, the `EventListener.handler` function is `None`. Any events that the `EventListener` is listening for will get sent to the `event_listener_driver` as-is.
+
+### Return `BaseEvent` or `dict`
+
+You can return a `BaseEvent` or `dict` object from `EventListener.handler`, and it will get sent to the `event_listener_driver`.
+
+### Return `None`
+
+You can return `None` in the handler function to prevent the event from getting sent to the `event_listener_driver`.
+
+```python
+--8<-- "docs/griptape-framework/misc/src/events_no_publish.py"
+```
diff --git a/docs/griptape-framework/misc/src/events_no_publish.py b/docs/griptape-framework/misc/src/events_no_publish.py
new file mode 100644
index 000000000..a59865923
--- /dev/null
+++ b/docs/griptape-framework/misc/src/events_no_publish.py
@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from griptape.artifacts import ErrorArtifact, InfoArtifact
+from griptape.drivers import GriptapeCloudEventListenerDriver
+from griptape.events import BaseEvent, EventBus, EventListener, FinishStructureRunEvent
+from griptape.structures import Agent
+
+
+def handler_maybe_drop_events(event: FinishStructureRunEvent) -> Optional[BaseEvent | dict]:
+    if event.structure_id == "some_structure_id":
+        # Drop the event if the structure_id is "some_structure_id"
+        return None
+    if isinstance(event.output_task_output, InfoArtifact):
+        # Print the output of the task if it is an InfoArtifact
+        # and then drop the event
+        print(f"Info: {event.output_task_output}")
+        return None
+    if isinstance(event.output_task_output, ErrorArtifact):
+        # Print the output of the task if it is an ErrorArtifact
+        # and then convert it to a dictionary and return it
+        print(f"Error: {event.output_task_output}")
+        return {
+            "error": event.output_task_output.to_text(),
+            "exception_message": str(event.output_task_output.exception),
+        }
+
+    return event
+
+
+EventBus.add_event_listeners(
+    [
+        EventListener(
+            handler_maybe_drop_events,  # pyright: ignore[reportArgumentType]
+            event_types=[FinishStructureRunEvent],
+            # By default, GriptapeCloudEventListenerDriver uses the api key provided
+            # in the GT_CLOUD_API_KEY environment variable.
+            event_listener_driver=GriptapeCloudEventListenerDriver(),
+        ),
+    ]
+)
+
+
+agent1 = Agent(id="some_structure_id")
+agent1.run("Create a list of 8 questions for an interview with a science fiction author.")
+
+agent2 = Agent(id="another_structure_id")
+agent2.run("Create a list of 10 questions for an interview with a theoretical physicist.")