Skip to content

armgit / burr

Public Imported from GitHub
0

Build applications that make decisions (chatbots, agents, simulations, etc...). Monitor, trace, persist, and execute on your own infrastructure.

Adds burr agent application templates (#166)

Stefan Krawczyk98f937550a5f
diff --git a/docs/examples/agents.rst b/docs/examples/agents.rst
index 256e8f52..2476ae34 100644
--- a/docs/examples/agents.rst
+++ b/docs/examples/agents.rst
@@ -41,3 +41,20 @@ things like examples of `tracing` and `hooks`.
<a target="_blank" href="https://colab.research.google.com/github/dagworks-inc/burr/blob/main/examples/multi-agent-collaboration/hamilton/notebook.ipynb">
<img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/>
</a>
+
+
+Templates
+--------------------
+
+We have the bones of a few applications that can be used to create agents. These are not fully fleshed out, but they
+can be used as a starting point for creating your own agents.
+
+We have the following templates:
+
+1. multi_modal_agent
+1. multi_agent_collaboration
+1. agent_supervisor
+1. hierarchical_agent_teams
+
+See the `templates` `directory under examples <https://github.com/DAGWorks-Inc/burr/tree/main/examples/templates>`_
+in our repository for the code.
diff --git a/examples/templates/README.md b/examples/templates/README.md
new file mode 100644
index 00000000..a656dc88
--- /dev/null
+++ b/examples/templates/README.md
@@ -0,0 +1,27 @@
+# Templates
+
+Some bones of a Burr application to get you started.
+
+## multi_modal_agent
+Simple example of a multi-modal agent that can switch between different modalities.
+
+![multi_modal_agent](muti_modal_agent.png))
+
+## multi_agent_collaboration
+Example of a multi-agent system where agents can collaborate to solve a task.
+
+![multi_agent_collaboration](multi_agent_collaboration.png)
+
+## agent_supervisor
+Example of a multi-agent system where agents are supervised by a supervisor agent.
+
+![agent_supervisor](agent_supervisor.png)
+
+## hierarchical_agent_teams
+Example of a multi-agent system where agents are organized in hierarchical teams.
+Recursively each team mirrors the `agent_supervisor` example above.
+
+Note: we're working on a better API to express this so you can also see the
+entire hierarchy in the diagram.
+
+![hierarchical_agent_teams](hierarchical_agent_teams.png)
diff --git a/examples/templates/agent_supervisor.png b/examples/templates/agent_supervisor.png
new file mode 100644
index 00000000..f6a90ba9
Binary files /dev/null and b/examples/templates/agent_supervisor.png differ
diff --git a/examples/templates/agent_supervisor.py b/examples/templates/agent_supervisor.py
new file mode 100644
index 00000000..f42c1aaf
--- /dev/null
+++ b/examples/templates/agent_supervisor.py
@@ -0,0 +1,155 @@
+"""
+Template for agent supervisor with multiple agents.
+
+This example is similar to the multi_agent_collaboration.py example, but that
+instead a supervisor agent is used to manage it all and whether to stop or continue.
+"""
+from burr import core
+from burr.core import ApplicationBuilder, State, action, default
+from burr.tracking import client as burr_tclient
+
+# --- Define some tools
+
+tools = [] # these could be functions, etc.
+
+# --- Start defining Action
+
+
+@action(reads=["query", "messages"], writes=["next_step"])
+def supervisor_agent(state: State) -> tuple[dict, State]:
+ """This agent decides what to do next given the current contxt.
+
+ i.e. call which agent, or terminate.
+
+ :param state: state of the application
+ :return:
+ """
+ _query = state["query"] # noqa:F841
+ _message = state["messages"] # noqa:F841
+ _agents = ["some_agent_1", "some_agent_2"] # noqa:F841
+ # Do LLM call, passing in current information and options
+ # determine what to do next
+ _result = {"next_step": "agent_or_terminate"}
+ return _result, state.update(**_result)
+
+
+@action(reads=["query", "messages"], writes=["parsed_tool_calls"])
+def some_agent_1(state: State) -> tuple[dict, State]:
+ """An agent specializing in some task.
+
+ :param state: state of the application
+ :return:
+ """
+ _query = state["query"] # noqa:F841
+ _message = state["messages"] # noqa:F841
+ # Do LLM call, passing in tool information
+ # determine which tool to call
+ _result = {"tool_call": "some_tool", "tool_args": {"arg1": "value1"}}
+ return _result, state.update(parsed_tool_calls=[_result], sender="some_agent_1")
+
+
+@action(reads=["query", "messages"], writes=["parsed_tool_calls"])
+def some_agent_2(state: State) -> tuple[dict, State]:
+ """An agent specializing in some other task.
+
+ :param state: state of the application
+ :return:
+ """
+ _query = state["query"] # noqa:F841
+ _message = state["messages"] # noqa:F841
+ # Do LLM call, passing in tool information
+ # determine which tool to call
+ _result = {"tool_call": "some_tool2", "tool_args": {"arg1": "value1"}}
+ return _result, state.update(parsed_tool_calls=[_result], sender="some_agent_2")
+
+
+@action(reads=["messages", "parsed_tool_calls"], writes=["messages", "parsed_tool_calls"])
+def tool_node(state: State) -> tuple[dict, State]:
+ """Given a tool call, execute it and return the result."""
+ _messages = state["messages"] # noqa:F841
+ _parsed_tool_calls = state["parsed_tool_calls"] # noqa:F841
+ # execute the tool call
+ # get result and create new message
+ _tool_results = [{"some": "message", "from": "tool_node"}]
+ new_state = state.append(messages=_tool_results)
+ new_state = new_state.update(parsed_tool_calls=[])
+ # We return a list, because this will get added to the existing list
+ return {"tool_results": _tool_results}, new_state
+
+
+@action(reads=["messages"], writes=[])
+def terminal_step(state: State) -> tuple[dict, State]:
+ """Terminal step we have here that does nothing, but it could"""
+ return {}, state
+
+
+def default_state_and_entry_point(query: str = None) -> tuple[dict, str]:
+ """Returns the default state and entry point for the application."""
+ return {
+ "messages": [],
+ "query": query,
+ "sender": "",
+ "parsed_tool_calls": [],
+ }, "supervisor_agent"
+
+
+def main(query: str = None, app_instance_id: str = None, sequence_number: int = None):
+ """Main function to run the application.
+
+ :param query: the query for the agents to run over.
+ :param app_instance_id: a prior app instance id to restart from.
+ :param sequence_number: a prior sequence number to restart from.
+ :return:
+ """
+ project_name = "template:multi-agent-collaboration"
+ if app_instance_id:
+ tracker = burr_tclient.LocalTrackingClient(project_name)
+ persisted_state = tracker.load("", app_id=app_instance_id, sequence_no=sequence_number)
+ if not persisted_state:
+ print(f"Warning: No persisted state found for app_id {app_instance_id}.")
+ state, entry_point = default_state_and_entry_point(query)
+ else:
+ state = persisted_state["state"]
+ entry_point = persisted_state["position"]
+ else:
+ state, entry_point = default_state_and_entry_point(query)
+ # look up app_id for particular user
+ # if None -- then proceed with defaults
+ # else load from state, and set entry point
+ app = (
+ ApplicationBuilder()
+ .with_state(**state)
+ .with_actions(
+ supervisor_agent=supervisor_agent,
+ some_agent_1=some_agent_1,
+ some_agent_2=some_agent_2,
+ tool_node=tool_node,
+ terminal=terminal_step,
+ )
+ .with_transitions(
+ ("supervisor_agent", "some_agent_1", core.when(next_step="some_agent_1")),
+ ("supervisor_agent", "some_agent_2", core.when(next_step="some_agent_2")),
+ ("supervisor_agent", "terminal", core.when(next_step="terminate")),
+ ("some_agent_1", "tool_node", core.expr("len(parsed_tool_calls) > 0")),
+ ("some_agent_1", "supervisor_agent", default),
+ ("some_agent_2", "tool_node", core.expr("len(parsed_tool_calls) > 0")),
+ ("some_agent_2", "supervisor_agent", default),
+ ("tool_node", "some_agent_1", core.when(sender="some_agent_1")),
+ ("tool_node", "some_agent_2", core.when(sender="some_agent_2")),
+ )
+ .with_identifiers(partition_key="demo")
+ .with_entrypoint(entry_point)
+ .with_tracker(project=project_name)
+ .build()
+ )
+ return app
+
+
+if __name__ == "__main__":
+ # Add an app_id to restart from last sequence in that state
+ _app_id = "8458dc58-7b6c-430b-9ab3-23450774f883"
+ app = main("some user query", _app_id)
+ app.visualize(
+ output_file_path="agent_supervisor", include_conditions=True, view=True, format="png"
+ )
+ # app.run(halt_after=["terminal"])
diff --git a/examples/templates/hierarchical_agent_teams.png b/examples/templates/hierarchical_agent_teams.png
new file mode 100644
index 00000000..35661cb6
Binary files /dev/null and b/examples/templates/hierarchical_agent_teams.png differ
diff --git a/examples/templates/hierarchical_agent_teams.py b/examples/templates/hierarchical_agent_teams.py
new file mode 100644
index 00000000..ea4f6d1a
--- /dev/null
+++ b/examples/templates/hierarchical_agent_teams.py
@@ -0,0 +1,150 @@
+"""
+This shows how to do a nested example of a hierarchical agent that uses
+teams. What that means is that we will use Burr within Burr!
+
+We're still deciding on a nicer way to do this, but for now, this is one
+way to do it.
+
+Note: you could unroll this into a single application.
+"""
+import uuid
+
+import agent_supervisor
+
+from burr import core
+from burr.core import ApplicationBuilder, State, action, default
+from burr.tracking import client as burr_tclient
+
+# --- Define some tools
+
+tools = [] # these could be functions, etc.
+
+# --- Start defining Action
+
+
+@action(reads=["query", "messages"], writes=["next_step"])
+def supervisor_agent(state: State) -> tuple[dict, State]:
+ """This agent decides what to do next given the current context.
+
+ i.e. call which team, or terminate.
+
+ :param state: state of the application
+ :return:
+ """
+ _query = state["query"] # noqa:F841
+ _message = state["messages"] # noqa:F841
+ _agents = ["team_1", "team_2"] # noqa:F841
+ # Do LLM call, passing in current information and options
+ # determine what to do next
+ _result = {"next_step": "team_or_terminate"}
+ return _result, state.update(**_result)
+
+
+@action(reads=["query", "messages"], writes=["result"])
+def team_1(state: State) -> tuple[dict, State]:
+ """A team specializing in some task.
+
+ :param state: state of the application
+ :return:
+ """
+ _query = state["query"] # noqa:F841
+ _message = state["messages"] # noqa:F841
+ _id = str(uuid.uuid4())
+ _app = agent_supervisor.main("some user query", _id)
+ _last_action, _result, _state = _app.run(halt_after=["terminal"]) # noqa:F841
+ # pull results and updates accordingly
+ _result = {"result": _result}
+ return _result, state.update(**_result)
+
+
+@action(reads=["query", "messages"], writes=["result"])
+def team_2(state: State) -> tuple[dict, State]:
+ """A team specializing in some other task.
+
+ :param state: state of the application
+ :return:
+ """
+ _query = state["query"] # noqa:F841
+ _message = state["messages"] # noqa:F841
+ _id = str(uuid.uuid4())
+ _app = agent_supervisor.main("some user query", _id)
+ _last_action, _result, _state = _app.run(halt_after=["terminal"]) # noqa:F841
+ # pull results and updates accordingly
+ _result = {"result": _result}
+ return _result, state.update(**_result)
+
+
+@action(reads=["messages"], writes=[])
+def terminal_step(state: State) -> tuple[dict, State]:
+ """Terminal step we have here that does nothing, but it could"""
+ return {}, state
+
+
+def default_state_and_entry_point(query: str = None) -> tuple[dict, str]:
+ """Returns the default state and entry point for the application."""
+ return {
+ "messages": [],
+ "query": query,
+ "sender": "",
+ "parsed_tool_calls": [],
+ }, "supervisor_agent"
+
+
+def main(query: str = None, app_instance_id: str = None, sequence_number: int = None):
+ """Main function to run the application.
+
+ :param query: the query for the agents to run over.
+ :param app_instance_id: a prior app instance id to restart from.
+ :param sequence_number: a prior sequence number to restart from.
+ :return:
+ """
+ project_name = "template:hierarchical-agent-teams"
+ if app_instance_id:
+ tracker = burr_tclient.LocalTrackingClient(project_name)
+ persisted_state = tracker.load("", app_id=app_instance_id, sequence_no=sequence_number)
+ if not persisted_state:
+ print(f"Warning: No persisted state found for app_id {app_instance_id}.")
+ state, entry_point = default_state_and_entry_point(query)
+ else:
+ state = persisted_state["state"]
+ entry_point = persisted_state["position"]
+ else:
+ state, entry_point = default_state_and_entry_point(query)
+ # look up app_id for particular user
+ # if None -- then proceed with defaults
+ # else load from state, and set entry point
+ app = (
+ ApplicationBuilder()
+ .with_state(**state)
+ .with_actions(
+ supervisor_agent=supervisor_agent,
+ team_1=team_1,
+ team_2=team_2,
+ terminal=terminal_step,
+ )
+ .with_transitions(
+ ("supervisor_agent", "team_1", core.when(next_step="team_1")),
+ ("supervisor_agent", "team_2", core.when(next_step="team_2")),
+ ("supervisor_agent", "terminal", core.when(next_step="terminate")),
+ ("team_1", "supervisor_agent", default),
+ ("team_2", "supervisor_agent", default),
+ )
+ .with_identifiers(partition_key="demo")
+ .with_entrypoint(entry_point)
+ .with_tracker(project=project_name)
+ .build()
+ )
+ return app
+
+
+if __name__ == "__main__":
+ # Add an app_id to restart from last sequence in that state
+ _app_id = "8458dc58-7b6c-430b-9ab3-23450774f883"
+ app = main("some user query", _app_id)
+ app.visualize(
+ output_file_path="hierarchical_agent_teams",
+ include_conditions=True,
+ view=True,
+ format="png",
+ )
+ # app.run(halt_after=["terminal"])
diff --git a/examples/templates/multi_agent_collaboration.png b/examples/templates/multi_agent_collaboration.png
new file mode 100644
index 00000000..4cc090df
Binary files /dev/null and b/examples/templates/multi_agent_collaboration.png differ
diff --git a/examples/templates/multi_agent_collaboration.py b/examples/templates/multi_agent_collaboration.py
new file mode 100644
index 00000000..d7ba6101
--- /dev/null
+++ b/examples/templates/multi_agent_collaboration.py
@@ -0,0 +1,146 @@
+"""
+Template for multi-agent collaboration.
+
+This contains a simple example of how to set up a multi-agent collaboration.
+The functions are to be filled in with the actual code to run the agents.
+"""
+from burr import core
+from burr.core import ApplicationBuilder, State, action, default
+from burr.tracking import client as burr_tclient
+
+# --- Define some tools
+
+tools = [] # these could be functions, etc.
+
+# --- Start defining Action
+
+
+@action(reads=["query", "messages"], writes=["parsed_tool_calls"])
+def some_agent_1(state: State) -> tuple[dict, State]:
+ """An agent specializing in some task.
+
+ :param state: state of the application
+ :return:
+ """
+ _query = state["query"] # noqa:F841
+ _message = state["messages"] # noqa:F841
+ # Do LLM call, passing in tool information
+ # determine which tool to call
+ _result = {"tool_call": "some_tool", "tool_args": {"arg1": "value1"}}
+ return _result, state.update(parsed_tool_calls=[_result], sender="some_agent_1")
+
+
+@action(reads=["query", "messages"], writes=["parsed_tool_calls"])
+def some_agent_2(state: State) -> tuple[dict, State]:
+ """An agent specializing in some other task.
+
+ :param state: state of the application
+ :return:
+ """
+ _query = state["query"] # noqa:F841
+ _message = state["messages"] # noqa:F841
+ # Do LLM call, passing in tool information
+ # determine which tool to call
+ _result = {"tool_call": "some_tool2", "tool_args": {"arg1": "value1"}}
+ return _result, state.update(parsed_tool_calls=[_result], sender="some_agent_2")
+
+
+@action(reads=["messages", "parsed_tool_calls"], writes=["messages", "parsed_tool_calls"])
+def tool_node(state: State) -> tuple[dict, State]:
+ """Given a tool call, execute it and return the result."""
+ _messages = state["messages"] # noqa:F841
+ _parsed_tool_calls = state["parsed_tool_calls"] # noqa:F841
+ # execute the tool call
+ # get result and create new message
+ _tool_results = [{"some": "message", "from": "tool_node"}]
+ new_state = state.append(messages=_tool_results)
+ new_state = new_state.update(parsed_tool_calls=[])
+ # We return a list, because this will get added to the existing list
+ return {"tool_results": _tool_results}, new_state
+
+
+@action(reads=["messages"], writes=[])
+def terminal_step(state: State) -> tuple[dict, State]:
+ """Terminal step we have here that does nothing, but it could"""
+ return {}, state
+
+
+def default_state_and_entry_point(query: str = None) -> tuple[dict, str]:
+ """Returns the default state and entry point for the application."""
+ return {
+ "messages": [],
+ "query": query,
+ "sender": "",
+ "parsed_tool_calls": [],
+ }, "some_agent_1"
+
+
+def main(query: str = None, app_instance_id: str = None, sequence_number: int = None):
+ """Main function to run the application.
+
+ :param query: the query for the agents to run over.
+ :param app_instance_id: a prior app instance id to restart from.
+ :param sequence_number: a prior sequence number to restart from.
+ :return:
+ """
+ project_name = "template:multi-agent-collaboration"
+ if app_instance_id:
+ tracker = burr_tclient.LocalTrackingClient(project_name)
+ persisted_state = tracker.load("", app_id=app_instance_id, sequence_no=sequence_number)
+ if not persisted_state:
+ print(f"Warning: No persisted state found for app_id {app_instance_id}.")
+ state, entry_point = default_state_and_entry_point(query)
+ else:
+ state = persisted_state["state"]
+ entry_point = persisted_state["position"]
+ else:
+ state, entry_point = default_state_and_entry_point(query)
+ # look up app_id for particular user
+ # if None -- then proceed with defaults
+ # else load from state, and set entry point
+ app = (
+ ApplicationBuilder()
+ .with_state(**state)
+ .with_actions(
+ some_agent_1=some_agent_1,
+ some_agent_2=some_agent_2,
+ tool_node=tool_node,
+ terminal=terminal_step,
+ )
+ .with_transitions(
+ ("some_agent_1", "tool_node", core.expr("len(parsed_tool_calls) > 0")),
+ (
+ "some_agent_1",
+ "terminal",
+ core.expr("'SOMETHING_IN_MESSAGES' in messages[-1]['content']"),
+ ),
+ ("some_agent_1", "some_agent_2", default),
+ ("some_agent_2", "tool_node", core.expr("len(parsed_tool_calls) > 0")),
+ (
+ "some_agent_2",
+ "terminal",
+ core.expr("'SOMETHING_IN_MESSAGES' in messages[-1]['content']"),
+ ),
+ ("some_agent_2", "some_agent_1", default),
+ ("tool_node", "some_agent_1", core.expr("sender == 'some_agent_1'")),
+ ("tool_node", "some_agent_2", core.expr("sender == 'some_agent_2'")),
+ )
+ .with_identifiers(partition_key="demo")
+ .with_entrypoint(entry_point)
+ .with_tracker(project=project_name)
+ .build()
+ )
+ return app
+
+
+if __name__ == "__main__":
+ # Add an app_id to restart from last sequence in that state
+ _app_id = "8458dc58-7b6c-430b-9ab3-23450774f883"
+ app = main("some user query", _app_id)
+ app.visualize(
+ output_file_path="multi_agent_collaboration",
+ include_conditions=True,
+ view=True,
+ format="png",
+ )
+ # app.run(halt_after=["terminal"])
diff --git a/examples/templates/multi_modal_agent.png b/examples/templates/multi_modal_agent.png
new file mode 100644
index 00000000..39ad50eb
Binary files /dev/null and b/examples/templates/multi_modal_agent.png differ
diff --git a/examples/templates/multi_modal_agent.py b/examples/templates/multi_modal_agent.py
new file mode 100644
index 00000000..e97b700e
--- /dev/null
+++ b/examples/templates/multi_modal_agent.py
@@ -0,0 +1,107 @@
+"""
+Template for a multi-modal agent.
+
+The idea is that this whole application functions as an agent that can do
+multi-modal things.
+
+Fill in the functions, and adjust/create new actions as needed.
+"""
+from typing import Tuple
+
+from burr import tracking
+from burr.core import Application, ApplicationBuilder, State, default, when
+from burr.core.action import action
+
+
+@action(reads=[], writes=["chat_history", "query"])
+def apply_input_query(state: State, user_query: str) -> Tuple[dict, State]:
+ # this is a simple example of how you might process a user query -- stick it directly into the chat history
+ result = {"chat_item": {"role": "user", "content": user_query, "type": "text"}}
+ new_state = state.append(chat_history=result["chat_item"]).update(query=user_query)
+ return result, new_state
+
+
+@action(reads=["prompt"], writes=["mode"])
+def choose_mode(state: State) -> Tuple[dict, State]:
+ """Code to choose a mode"""
+ result = {"mode": "example"}
+ return result, state.update(**result)
+
+
+@action(reads=[], writes=["response"])
+def unknown_action(state: State) -> Tuple[dict, State]:
+ result = {
+ "response": {
+ "content": "None of the response modes I support apply to your question. Please clarify?",
+ "type": "text",
+ "role": "assistant",
+ }
+ }
+ return result, state.update(**result)
+
+
+@action(reads=["query", "chat_history", "mode"], writes=["response"])
+def some_action(state: State) -> Tuple[dict, State]:
+ """An example action -- create more of these to handle different modes"""
+ _query = state["query"] # noqa:F841
+ _mode = state["mode"] # noqa:F841
+ _chat_history = state["chat_history"] # noqa:F841
+ result = {"response": {"some": "response"}}
+ return result, state.update(**result)
+
+
+@action(reads=["query", "mode", "response"], writes=["chat_history"])
+def response(state: State) -> Tuple[dict, State]:
+ """Function to create a response based on the prior action."""
+ _result = {
+ "content": state["response"],
+ "type": state["mode"],
+ "role": "assistant",
+ }
+ return _result, state.append(chat_history=_result)
+
+
+def base_application(app_id: str, storage_dir: str, project_id: str) -> Application:
+ """Creates the Burr application"""
+ tracker = tracking.LocalTrackingClient(project=project_id, storage_dir=storage_dir)
+ return (
+ ApplicationBuilder()
+ .with_actions(
+ apply_input_query=apply_input_query,
+ decide_mode=choose_mode,
+ unknown_action=unknown_action,
+ some_action=some_action,
+ response=response,
+ )
+ .with_transitions(
+ ("apply_input_query", "decide_mode", default),
+ ("decide_mode", "unknown_action", when(mode="unknown")),
+ ("decide_mode", "some_action", when(mode="some_action")),
+ (["unknown_action", "some_action"], "response", default),
+ ("response", "apply_input_query", default),
+ )
+ # initializes from the tracking log if it does not already exist
+ .initialize_from(
+ tracker,
+ resume_at_next_action=False, # always resume from entrypoint in the case of failure
+ default_state={"chat_history": []},
+ default_entrypoint="apply_input_query",
+ )
+ .with_tracker(tracker)
+ .with_identifiers(app_id=app_id)
+ .build()
+ )
+
+
+if __name__ == "__main__":
+ import uuid
+
+ app_id: str = str(uuid.uuid4())
+ storage_dir: str = "~/.burr"
+ project_id: str = "template:multi-modal-agent"
+ app = base_application(app_id, storage_dir, project_id)
+ app.visualize(
+ output_file_path="multi_modal_agent", include_conditions=False, view=True, format="png"
+ )
+ # this is how you could run one cycle of the agent:
+ # app.run(halt_after=["response"], inputs={"user_query": "Hello, world!"})
diff --git a/examples/validate_examples.py b/examples/validate_examples.py
index b4b2b971..b5db7597 100644
--- a/examples/validate_examples.py
+++ b/examples/validate_examples.py
@@ -20,6 +20,7 @@ FILTERLIST = [
"multi-agent-collaboration",
"web-server",
"integrations",
+ "templates",
]