Build applications that make decisions (chatbots, agents, simulations, etc...). Monitor, trace, persist, and execute on your own infrastructure.
Python aiburrchatbot-frameworkdagsgenerative-aigraphshacktoberfestllmopsllmsmlopspersistent-data-structurestate-machinestate-managementvisibility
Adds burr agent application templates (#166)
Stefan Krawczyk98f937550a5f
diff --git a/docs/examples/agents.rst b/docs/examples/agents.rstindex 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.mdnew file mode 100644index 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_agent_collaboration+Example of a multi-agent system where agents can collaborate to solve a task.++++## agent_supervisor+Example of a multi-agent system where agents are supervised by a supervisor agent.++++## 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.++diff --git a/examples/templates/agent_supervisor.png b/examples/templates/agent_supervisor.pngnew file mode 100644index 00000000..f6a90ba9Binary files /dev/null and b/examples/templates/agent_supervisor.png differdiff --git a/examples/templates/agent_supervisor.py b/examples/templates/agent_supervisor.pynew file mode 100644index 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.pngnew file mode 100644index 00000000..35661cb6Binary files /dev/null and b/examples/templates/hierarchical_agent_teams.png differdiff --git a/examples/templates/hierarchical_agent_teams.py b/examples/templates/hierarchical_agent_teams.pynew file mode 100644index 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.pngnew file mode 100644index 00000000..4cc090dfBinary files /dev/null and b/examples/templates/multi_agent_collaboration.png differdiff --git a/examples/templates/multi_agent_collaboration.py b/examples/templates/multi_agent_collaboration.pynew file mode 100644index 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.pngnew file mode 100644index 00000000..39ad50ebBinary files /dev/null and b/examples/templates/multi_modal_agent.png differdiff --git a/examples/templates/multi_modal_agent.py b/examples/templates/multi_modal_agent.pynew file mode 100644index 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.pyindex 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",]