Add structure run tool/task

CHANGELOG.md

@@ -23,7 +23,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `AmazonS3FileManagerDriver` for managing files on Amazon S3.
 - `MediaArtifact` as a base class for `ImageArtifact` and future media Artifacts.
 - Optional `exception` field to `ErrorArtifact`.
-- `GriptapeCloudStructureRunClient` tool for invoking Griptape Cloud Structure Run APIs.
+- `StructureRunClient` for running other Structures via a Tool.
+- `StructureRunTask` for running Structures as a Task from within another Structure.
+- `GriptapeCloudStructureRunDriver` for running Structures in the Griptape Cloud.
+- `LocalStructureRunDriver` for running Structures in the same runtime environment as the code that is running the Structure.
 
 ### Changed
 - **BREAKING**: Secret fields (ex: api_key) removed from serialized Drivers.

docs/examples/multi-agent-workflow.md

@@ -0,0 +1,184 @@
+In this example we implement a multi-agent Workflow. We have a single "Researcher" Agent that conducts research on a topic, and then fans out to multiple "Writer" Agents to write blog posts based on the research.
+
+By splitting up our workloads across multiple Structures, we can parallelize the work and leverage the strengths of each Agent. The Researcher can focus on gathering data and insights, while the Writers can focus on crafting engaging narratives.
+Additionally, this architecture opens us up to using services such as [Griptape Cloud](https://www.griptape.ai/cloud) to have each Agent run on a separate machine, allowing us to scale our Workflow as needed 🤯.
+
+
+```python
+import os
+from pathlib import Path
+
+from griptape.drivers import WebhookEventListenerDriver
+from griptape.events import EventListener, FinishStructureRunEvent
+from griptape.rules import Rule, Ruleset
+from griptape.structures import Agent, Workflow
+from griptape.tasks import PromptTask, StructureRunTask
+from griptape.tools import (
+    TaskMemoryClient,
+    WebScraper,
+    WebSearch,
+)
+
+WRITERS = [
+    {
+        "role": "Travel Adventure Blogger",
+        "goal": "Inspire wanderlust with stories of hidden gems and exotic locales",
+        "backstory": "With a passport full of stamps, you bring distant cultures and breathtaking scenes to life through vivid storytelling and personal anecdotes."
+    },
+    {
+        "role": "Lifestyle Freelance Writer",
+        "goal": "Share practical advice on living a balanced and stylish life",
+        "backstory": "From the latest trends in home decor to tips for wellness, your articles help readers create a life that feels both aspirational and attainable."
+    }
+]
+
+
+def build_researcher():
+    """Builds a Researcher Structure."""
+    researcher = Agent(
+        id="researcher",
+        tools=[
+            WebSearch(
+                google_api_key=os.environ["GOOGLE_API_KEY"],
+                google_api_search_id=os.environ["GOOGLE_API_SEARCH_ID"],
+                off_prompt=False,
+            ),
+            WebScraper(
+                off_prompt=True,
+            ),
+            TaskMemoryClient(off_prompt=False),
+        ],
+        rulesets=[
+            Ruleset(
+                name="Position",
+                rules=[
+                    Rule(
+                        value="Lead Research Analyst",
+                    )
+                ],
+            ),
+            Ruleset(
+                name="Objective",
+                rules=[
+                    Rule(
+                        value="Discover innovative advancements in artificial intelligence and data analytics",
+                    )
+                ],
+            ),
+            Ruleset(
+                name="Background",
+                rules=[
+                    Rule(
+                        value="""You are part of a prominent technology research institute.
+                        Your speciality is spotting new trends.
+                        You excel at analyzing intricate data and delivering practical insights."""
+                    )
+                ],
+            ),
+            Ruleset(
+                name="Desired Outcome",
+                rules=[
+                    Rule(
+                        value="Comprehensive analysis report in list format",
+                    )
+                ],
+            ),
+        ],
+    )
+
+    return researcher
+
+
+def build_writer(role: str, goal: str, backstory: str):
+    """Builds a Writer Structure.
+
+    Args:
+        role: The role of the writer.
+        goal: The goal of the writer.
+        backstory: The backstory of the writer.
+    """
+    writer = Agent(
+        id=role.lower().replace(" ", "_"),
+        event_listeners=[
+            EventListener(
+                event_types=[FinishStructureRunEvent],
+                driver=WebhookEventListenerDriver(
+                    webhook_url=os.environ["WEBHOOK_URL"],
+                ),
+            )
+        ],
+        rulesets=[
+            Ruleset(
+                name="Position",
+                rules=[
+                    Rule(
+                        value=role,
+                    )
+                ],
+            ),
+            Ruleset(
+                name="Objective",
+                rules=[
+                    Rule(
+                        value=goal,
+                    )
+                ],
+            ),
+            Ruleset(
+                name="Backstory",
+                rules=[Rule(value=backstory)],
+            ),
+            Ruleset(
+                name="Desired Outcome",
+                rules=[
+                    Rule(
+                        value="Full blog post of at least 4 paragraphs",
+                    )
+                ],
+            ),
+        ],
+    )
+
+    return writer
+
+
+if __name__ == "__main__":
+    # Build the team
+    team = Workflow()
+    research_task = team.add_task(
+        StructureRunTask(
+            """Conduct a comprehensive analysis of the latest advancements in AI in 2024.
+                Identify key trends, breakthrough technologies, and potential industry impacts.""",
+            id="research",
+            target_structure=build_researcher(),
+        ),
+    )
+    end_task = team.add_task(
+        PromptTask(
+            'State "All Done!"',
+        )
+    )
+    team.insert_tasks(
+        research_task,
+        [
+            StructureRunTask(
+                """Using insights provided, develop an engaging blog
+                post that highlights the most significant AI advancements.
+                Your post should be informative yet accessible, catering to a tech-savvy audience.
+                Make it sound cool, avoid complex words so it doesn't sound like AI.
+
+                Insights:
+                {{ parent_outputs["research"] }}""",
+                target_structure=build_writer(
+                    role=writer["role"],
+                    goal=writer["goal"],
+                    backstory=writer["backstory"],
+                ),
+            )
+            for writer in WRITERS
+        ],
+        end_task,
+    )
+
+    team.run()
+```

docs/griptape-framework/drivers/structure-run-drivers.md

@@ -0,0 +1,97 @@
+## Overview
+Structure Run Drivers can be used to run Griptape Structures in a variety of runtime environments.
+When combined with the [Structure Run Task](../../griptape-framework/structures/tasks.md#structure-run-task) or [Structure Run Client](../../griptape-tools/official-tools/structure-run-client.md) you can create complex, multi-agent pipelines that span multiple runtime environments.
+
+## Local Structure Run Driver
+
+The [LocalStructureRunDriver](../../reference/griptape/drivers/structure_run/local_structure_run_driver.md) is used to run Griptape Structures in the same runtime environment as the code that is running the Structure.
+
+```python
+from griptape.drivers import LocalStructureRunDriver
+from griptape.rules import Rule
+from griptape.structures import Agent, Pipeline
+from griptape.tasks import StructureRunTask
+
+joke_teller = Agent(
+    rules=[
+        Rule(
+            value="You are very funny.",
+        )
+    ],
+)
+
+joke_rewriter = Agent(
+    rules=[
+        Rule(
+            value="You are the editor of a joke book. But you only speak in riddles",
+        )
+    ],
+)
+
+joke_coordinator = Pipeline(
+    tasks=[
+        StructureRunTask(
+            driver=LocalStructureRunDriver(
+                structure_factory_fn=lambda: joke_teller,
+            ),
+        ),
+        StructureRunTask(
+            "Rewrite this joke: {{ parent_output }}",
+            driver=LocalStructureRunDriver(
+                structure_factory_fn=lambda: joke_rewriter,
+            ),
+        ),
+    ]
+)
+
+joke_coordinator.run("Tell me a joke")
+```
+
+## Griptape Cloud Structure Run Driver
+
+The [GriptapeCloudStructureRunDriver](../../reference/griptape/drivers/structure_run/griptape_cloud_structure_run_driver.md) is used to run Griptape Structures in the Griptape Cloud.
+
+
+```python
+import os
+
+from griptape.drivers import GriptapeCloudStructureRunDriver, LocalStructureRunDriver
+from griptape.structures import Pipeline, Agent
+from griptape.rules import Rule
+from griptape.tasks import StructureRunTask
+
+base_url = os.environ["GRIPTAPE_CLOUD_BASE_URL"]
+api_key = os.environ["GRIPTAPE_CLOUD_API_KEY"]
+structure_id = os.environ["GRIPTAPE_CLOUD_STRUCTURE_ID"]
+
+
+pipeline = Pipeline(
+    tasks=[
+        StructureRunTask(
+            "Think of a question related to Retrieval Augmented Generation.",
+            driver=LocalStructureRunDriver(
+                structure=Agent(
+                    rules=[
+                        Rule(
+                            value="You are an expert in Retrieval Augmented Generation.",
+                        ),
+                        Rule(
+                            value="Only output your answer, no other information.",
+                        ),
+                    ]
+                )
+            ),
+        ),
+        StructureRunTask(
+            "{{ parent_output }}",
+            driver=GriptapeCloudStructureRunDriver(
+                base_url=base_url,
+                api_key=api_key,
+                structure_id=structure_id,
+            ),
+        ),
+    ]
+)
+
+pipeline.run()
+```