Skip to content

A programming framework for agentic AI

Add initial base and ledger orchestrator, improve executor (#206)

gagb386680fd3e9d
diff --git a/python/teams/team-one/examples/example.py b/python/teams/team-one/examples/example.py
index 915e2dc4d..bdd0ca7ff 100644
--- a/python/teams/team-one/examples/example.py
+++ b/python/teams/team-one/examples/example.py
@@ -1,3 +1,47 @@
-import team_one
+import asyncio
+import logging
-print(team_one.ABOUT)
+from agnext.application import SingleThreadedAgentRuntime
+from agnext.application.logging import EVENT_LOGGER_NAME
+from team_one.agents.coder import Coder, Executor
+from team_one.agents.orchestrator import LedgerOrchestrator
+from team_one.agents.user_proxy import UserProxy
+from team_one.messages import RequestReplyMessage
+from team_one.utils import LogHandler, create_completion_client_from_env
+
+
+async def main() -> None:
+ # Create the runtime.
+ runtime = SingleThreadedAgentRuntime()
+
+ # Register agents.
+ coder = runtime.register_and_get_proxy(
+ "Coder",
+ lambda: Coder(model_client=create_completion_client_from_env()),
+ )
+
+ executor = runtime.register_and_get_proxy("Executor", lambda: Executor("A agent for executing code"))
+
+ user_proxy = runtime.register_and_get_proxy(
+ "UserProxy",
+ lambda: UserProxy(description="The current user interacting with you."),
+ )
+
+ runtime.register(
+ "orchestrator",
+ lambda: LedgerOrchestrator(
+ model_client=create_completion_client_from_env(), agents=[coder, executor, user_proxy]
+ ),
+ )
+
+ run_context = runtime.start()
+ await runtime.send_message(RequestReplyMessage(), user_proxy.id)
+ await run_context.stop_when_idle()
+
+
+if __name__ == "__main__":
+ logger = logging.getLogger(EVENT_LOGGER_NAME)
+ logger.setLevel(logging.INFO)
+ log_handler = LogHandler()
+ logger.handlers = [log_handler]
+ asyncio.run(main())
diff --git a/python/teams/team-one/src/team_one/agents/base_orchestrator.py b/python/teams/team-one/src/team_one/agents/base_orchestrator.py
new file mode 100644
index 000000000..f7e0c6d88
--- /dev/null
+++ b/python/teams/team-one/src/team_one/agents/base_orchestrator.py
@@ -0,0 +1,83 @@
+import logging
+from typing import List, Optional
+
+from agnext.application.logging import EVENT_LOGGER_NAME
+from agnext.components import TypeRoutedAgent, message_handler
+from agnext.components.models import AssistantMessage, LLMMessage, UserMessage
+from agnext.core import AgentProxy, CancellationToken
+
+from ..messages import BroadcastMessage, OrchestrationEvent, RequestReplyMessage
+from ..utils import message_content_to_str
+
+logger = logging.getLogger(EVENT_LOGGER_NAME + ".orchestrator")
+
+
+class BaseOrchestrator(TypeRoutedAgent):
+ def __init__(
+ self,
+ agents: List[AgentProxy],
+ description: str = "Base orchestrator",
+ max_rounds: int = 20,
+ ) -> None:
+ super().__init__(description)
+ self._agents = agents
+ self._max_rounds = max_rounds
+ self._num_rounds = 0
+
+ @message_handler
+ async def handle_incoming_message(self, message: BroadcastMessage, cancellation_token: CancellationToken) -> None:
+ """Handle an incoming message."""
+ source = "Unknown"
+ if isinstance(message.content, UserMessage) or isinstance(message.content, AssistantMessage):
+ source = message.content.source
+
+ content = message_content_to_str(message.content.content)
+
+ logger.info(OrchestrationEvent(source, content))
+
+ # Termination conditions
+ if self._num_rounds >= self._max_rounds:
+ logger.info(
+ OrchestrationEvent(
+ f"{self.metadata['name']} (termination condition)",
+ f"Max rounds ({self._max_rounds}) reached.",
+ )
+ )
+ return
+
+ if message.request_halt:
+ logger.info(
+ OrchestrationEvent(
+ f"{self.metadata['name']} (termination condition)",
+ f"{source} requested halt.",
+ )
+ )
+ return
+
+ next_agent = await self._select_next_agent(message.content)
+ if next_agent is None:
+ logger.info(
+ OrchestrationEvent(
+ f"{self.metadata['name']} (termination condition)",
+ "No agent selected.",
+ )
+ )
+ return
+ request_reply_message = RequestReplyMessage()
+ # emit an event
+
+ logger.info(
+ OrchestrationEvent(
+ source=f"{self.metadata['name']} (thought)",
+ message=f"Next speaker {next_agent.metadata['name']}" "",
+ )
+ )
+
+ self._num_rounds += 1 # Call before sending the message
+ await self.send_message(request_reply_message, next_agent.id)
+
+ async def _select_next_agent(self, message: LLMMessage) -> Optional[AgentProxy]:
+ raise NotImplementedError()
+
+ def get_max_rounds(self) -> int:
+ return self._max_rounds
diff --git a/python/teams/team-one/src/team_one/agents/coder.py b/python/teams/team-one/src/team_one/agents/coder.py
index 2dfc5a2a6..824e627b2 100644
--- a/python/teams/team-one/src/team_one/agents/coder.py
+++ b/python/teams/team-one/src/team_one/agents/coder.py
@@ -6,6 +6,7 @@ from agnext.components.code_executor import CodeBlock, CodeExecutor, LocalComman
from agnext.components.models import (
ChatCompletionClient,
SystemMessage,
+ UserMessage,
)
from agnext.core import CancellationToken
@@ -58,32 +59,46 @@ If the code was executed, and the output appears to indicate that the original p
class Executor(BaseAgent):
- def __init__(self, description: str, executor: Optional[CodeExecutor] = None) -> None:
+ def __init__(
+ self, description: str, executor: Optional[CodeExecutor] = None, check_last_n_message: int = 5
+ ) -> None:
super().__init__(description)
self._executor = executor or LocalCommandLineCodeExecutor()
+ self._check_last_n_message = check_last_n_message
async def _generate_reply(self, cancellation_token: CancellationToken) -> Tuple[bool, UserContent]:
"""Respond to a reply request."""
- # Extract code block from the message.
- assert isinstance(self._chat_history[-1].content, str)
- code = self._extract_execution_request(self._chat_history[-1].content)
- if code is not None:
- execution_requests = [CodeBlock(code=code, language="python")]
- future = asyncio.get_event_loop().run_in_executor(
- None, self._executor.execute_code_blocks, execution_requests
- )
- cancellation_token.link_future(future)
- result = await future
- return (
- False,
- f"The script ran, then exited with Unix exit code: {result.exit_code}\nIts output was:\n{result.output}",
- )
- else:
- return (
- False,
- "No code block detected. Please provide a markdown-encoded code block to execute for the original task.",
- )
+ n_messages_checked = 0
+ for idx in range(len(self._chat_history)):
+ message = self._chat_history[-(idx + 1)]
+
+ if not isinstance(message, UserMessage):
+ continue
+
+ # Extract code block from the message.
+ assert isinstance(message.content, str)
+ code = self._extract_execution_request(message.content)
+ if code is not None:
+ execution_requests = [CodeBlock(code=code, language="python")]
+ future = asyncio.get_event_loop().run_in_executor(
+ None, self._executor.execute_code_blocks, execution_requests
+ )
+ cancellation_token.link_future(future)
+ result = await future
+ return (
+ False,
+ f"The script ran, then exited with Unix exit code: {result.exit_code}\nIts output was:\n{result.output}",
+ )
+ else:
+ n_messages_checked += 1
+ if n_messages_checked > self._check_last_n_message:
+ break
+
+ return (
+ False,
+ "No code block detected in the messages. Please provide a markdown-encoded code block to execute for the original task.",
+ )
def _extract_execution_request(self, markdown_text: str) -> Union[str, None]:
pattern = r"```(\w+)\n(.*?)\n```"
diff --git a/python/teams/team-one/src/team_one/agents/orchestrator.py b/python/teams/team-one/src/team_one/agents/orchestrator.py
index a298785bd..bf32aa1cd 100644
--- a/python/teams/team-one/src/team_one/agents/orchestrator.py
+++ b/python/teams/team-one/src/team_one/agents/orchestrator.py
@@ -1,73 +1,241 @@
-import logging
-from typing import List
+import json
+from typing import Any, Dict, List, Optional
-from agnext.application.logging import EVENT_LOGGER_NAME
-from agnext.components import TypeRoutedAgent, message_handler
-from agnext.components.models import AssistantMessage, UserMessage
-from agnext.core import AgentProxy, CancellationToken
+from agnext.components.models import AssistantMessage, ChatCompletionClient, LLMMessage, SystemMessage, UserMessage
+from agnext.core import AgentProxy
-from ..messages import BroadcastMessage, OrchestrationEvent, RequestReplyMessage
-from ..utils import message_content_to_str
+from ..messages import BroadcastMessage, OrchestrationEvent
+from .base_orchestrator import BaseOrchestrator, logger
+from .orchestrator_prompts import (
+ ORCHESTRATOR_CLOSED_BOOK_PROMPT,
+ ORCHESTRATOR_LEDGER_PROMPT,
+ ORCHESTRATOR_PLAN_PROMPT,
+ ORCHESTRATOR_SYNTHESIZE_PROMPT,
+ ORCHESTRATOR_SYSTEM_MESSAGE,
+)
-logger = logging.getLogger(EVENT_LOGGER_NAME + ".orchestrator")
-
-class RoundRobinOrchestrator(TypeRoutedAgent):
+class RoundRobinOrchestrator(BaseOrchestrator):
def __init__(
self,
agents: List[AgentProxy],
description: str = "Round robin orchestrator",
max_rounds: int = 20,
) -> None:
- super().__init__(description)
- self._agents = agents
- self._max_rounds = max_rounds
- self._num_rounds = 0
+ super().__init__(agents=agents, description=description, max_rounds=max_rounds)
- @message_handler
- async def handle_incoming_message(self, message: BroadcastMessage, cancellation_token: CancellationToken) -> None:
- """Handle an incoming message."""
- source = "Unknown"
- if isinstance(message.content, UserMessage) or isinstance(message.content, AssistantMessage):
- source = message.content.source
+ async def _select_next_agent(self, message: LLMMessage) -> AgentProxy:
+ self._current_index = (self._num_rounds) % len(self._agents)
+ return self._agents[self._current_index]
- content = message_content_to_str(message.content.content)
- logger.info(OrchestrationEvent(source, content))
+class LedgerOrchestrator(BaseOrchestrator):
+ DEFAULT_SYSTEM_MESSAGES = [
+ SystemMessage(ORCHESTRATOR_SYSTEM_MESSAGE),
+ ]
- # Termination conditions
- if self._num_rounds >= self._max_rounds:
- logger.info(
- OrchestrationEvent(
- f"{self.metadata['name']} (termination condition)",
- f"Max rounds ({self._max_rounds}) reached.",
- )
+ def __init__(
+ self,
+ agents: List[AgentProxy],
+ model_client: ChatCompletionClient,
+ description: str = "Ledger-based orchestrator",
+ system_messages: List[SystemMessage] = DEFAULT_SYSTEM_MESSAGES,
+ closed_book_prompt: str = ORCHESTRATOR_CLOSED_BOOK_PROMPT,
+ plan_prompt: str = ORCHESTRATOR_PLAN_PROMPT,
+ synthesize_prompt: str = ORCHESTRATOR_SYNTHESIZE_PROMPT,
+ ledger_prompt: str = ORCHESTRATOR_LEDGER_PROMPT,
+ max_rounds: int = 20,
+ max_stalls_before_replan: int = 3,
+ max_replans: int = 4,
+ ) -> None:
+ super().__init__(agents=agents, description=description, max_rounds=max_rounds)
+
+ self._model_client = model_client
+
+ # prompt-based parameters
+ self._system_messages = system_messages
+ self._closed_book_prompt = closed_book_prompt
+ self._plan_prompt = plan_prompt
+ self._synthesize_prompt = synthesize_prompt
+ self._ledger_prompt = ledger_prompt
+
+ self._chat_history: List[LLMMessage] = []
+ self._should_replan = True
+ self._max_stalls_before_replan = max_stalls_before_replan
+ self._stall_counter = 0
+ self._max_replans = max_replans
+ self._replan_counter = 0
+ self.task_str = ""
+
+ def _get_closed_book_prompt(self, task: str) -> str:
+ return self._closed_book_prompt.format(task=task)
+
+ def _get_plan_prompt(self, task: str, team: str) -> str:
+ return self._plan_prompt.format(task=task, team=team)
+
+ def _get_synthesize_prompt(self, task: str, team: str, facts: str, plan: str) -> str:
+ return self._synthesize_prompt.format(task=task, team=team, facts=facts, plan=plan)
+
+ def _get_ledger_prompt(self, task: str, team: str, names: List[str]) -> str:
+ return self._ledger_prompt.format(task=task, team=team, names=names)
+
+ def _get_team_description(self) -> str:
+ team_description = ""
+ for agent in self._agents:
+ name = agent.metadata["name"]
+ description = agent.metadata["description"]
+ team_description += f"{name}: {description}\n"
+ return team_description
+
+ def _get_team_names(self) -> List[str]:
+ return [agent.metadata["name"] for agent in self._agents]
+
+ def _set_task_str(self, message: LLMMessage) -> None:
+ if len(self._chat_history) == 1:
+ if isinstance(message.content, str):
+ self.task_str = message.content
+ else:
+ for content in message.content:
+ if isinstance(content, str):
+ self.task_str += content + "\n"
+ break
+ assert len(self.task_str) > 0
+
+ def _needs_replan(self) -> bool:
+ if len(self._chat_history) == 1:
+ self._set_task_str(self._chat_history[0])
+ return True
+
+ if self._stall_counter > self._max_stalls_before_replan:
+ return True
+
+ return False
+
+ async def _plan(self) -> str:
+ team_description = self._get_team_description()
+
+ # 1. GATHER FACTS
+ # create a closed book task and generate a response and update the chat history
+ cb_task = self._get_closed_book_prompt(self.task_str)
+ cb_user_message = UserMessage(
+ content=cb_task, source=self.metadata["name"]
+ ) # TODO: allow images in this message.
+ cb_response = await self._model_client.create(self._system_messages + self._chat_history + [cb_user_message])
+ facts = cb_response.content
+ assert isinstance(facts, str)
+ cb_assistant_message = AssistantMessage(content=facts, source=self.metadata["name"])
+
+ # 2. CREATE A PLAN
+ ## plan based on available information
+ plan_task = self._get_plan_prompt(self.task_str, team_description)
+ plan_user_message = UserMessage(
+ content=plan_task, source=self.metadata["name"]
+ ) # TODO: allow images in this message.
+ plan_response = await self._model_client.create(
+ self._system_messages + self._chat_history + [cb_assistant_message, plan_user_message]
+ )
+ plan = plan_response.content
+ assert isinstance(plan, str)
+
+ # SYNTHESIZE FACTS AND PLAN
+ plan_str = self._get_synthesize_prompt(self.task_str, team_description, facts, plan)
+ return plan_str
+
+ async def update_ledger(self) -> Dict[str, Any]:
+ max_json_retries = 10
+
+ team_description = self._get_team_description()
+ names = self._get_team_names()
+ ledger_prompt = self._get_ledger_prompt(self.task_str, team_description, names)
+ ledger_user_message = UserMessage(content=ledger_prompt, source=self.metadata["name"])
+
+ assert max_json_retries > 0
+ for _ in range(max_json_retries):
+ ledger_response = await self._model_client.create(
+ self._system_messages + self._chat_history + [ledger_user_message],
+ json_output=True,
)
- return
+ ledger_str = ledger_response.content
+
+ try:
+ assert isinstance(ledger_str, str)
+ ledger_dict: Dict[str, Any] = json.loads(ledger_str)
+ return ledger_dict
+ except json.JSONDecodeError as e:
+ logger.info(
+ OrchestrationEvent(
+ f"{self.metadata['name']} (error)",
+ f"Failed to parse ledger information: {ledger_str}",
+ )
+ )
+ raise e
+
+ raise ValueError("Failed to parse ledger information after multiple retries.")
+
+ async def _select_next_agent(self, message: LLMMessage) -> Optional[AgentProxy]:
+ self._chat_history.append(message)
- if message.request_halt:
+ self._should_replan = self._needs_replan()
+
+ if self._should_replan:
+ plan_str = await self._plan()
+ plan_user_message = UserMessage(content=plan_str, source=self.metadata["name"])
logger.info(
OrchestrationEvent(
- f"{self.metadata['name']} (termination condition)",
- f"{source} requested halt.",
+ f"{self.metadata['name']} (thought)",
+ f"New plan:\n{plan_str}",
)
)
- return
-
- next_agent = self._select_next_agent()
- request_reply_message = RequestReplyMessage()
- # emit an event
+ self._chat_history.append(plan_user_message)
+ ledger_dict = await self.update_ledger()
logger.info(
OrchestrationEvent(
- source=f"{self.metadata['name']} (thought)",
- message=f"Next speaker {next_agent.metadata['name']}" "",
+ f"{self.metadata['name']} (thought)",
+ f"Updated Ledger:\n{json.dumps(ledger_dict, indent=2)}",
)
)
- self._num_rounds += 1 # Call before sending the message
- await self.send_message(request_reply_message, next_agent.id)
+ if ledger_dict["is_request_satisfied"]["answer"] is True:
+ logger.info(
+ OrchestrationEvent(
+ f"{self.metadata['name']} (thought)",
+ "Request satisfied.",
+ )
+ )
+ return None
- def _select_next_agent(self) -> AgentProxy:
- self._current_index = (self._num_rounds) % len(self._agents)
- return self._agents[self._current_index]
+ if ledger_dict["is_in_loop"]["answer"]:
+ self._stall_counter += 1
+
+ if self._stall_counter > self._max_stalls_before_replan:
+ self._replan_counter += 1
+ self._stall_counter = 0
+ if self._replan_counter < self._max_replans:
+ logger.info(
+ OrchestrationEvent(
+ f"{self.metadata['name']} (thought)",
+ "Stalled.... Replanning...",
+ )
+ )
+ return await self._select_next_agent(message)
+ else:
+ logger.info(
+ OrchestrationEvent(
+ f"{self.metadata['name']} (thought)",
+ "Replan counter exceeded... Terminating.",
+ )
+ )
+ return None
+
+ next_agent_name = ledger_dict["next_speaker"]["answer"]
+ for agent in self._agents:
+ if agent.metadata["name"] == next_agent_name:
+ # broadcast a new message
+ instruction = ledger_dict["instruction_or_question"]["answer"]
+ user_message = UserMessage(content=instruction, source=self.metadata["name"])
+ logger.info(OrchestrationEvent(f"{self.metadata['name']} (-> {next_agent_name})", instruction))
+ await self.publish_message(BroadcastMessage(content=user_message, request_halt=False))
+ return agent
+
+ return None
diff --git a/python/teams/team-one/src/team_one/agents/orchestrator_prompts.py b/python/teams/team-one/src/team_one/agents/orchestrator_prompts.py
new file mode 100644
index 000000000..1ca5282a3
--- /dev/null
+++ b/python/teams/team-one/src/team_one/agents/orchestrator_prompts.py
@@ -0,0 +1,91 @@
+ORCHESTRATOR_SYSTEM_MESSAGE = ""
+
+
+ORCHESTRATOR_CLOSED_BOOK_PROMPT = """Below I will present you a request. Before we begin addressing the request, please answer the following pre-survey to the best of your ability. Keep in mind that you are Ken Jennings-level with trivia, and Mensa-level with puzzles, so there should be a deep well to draw from.
+
+Here is the request:
+
+{task}
+
+Here is the pre-survey:
+
+ 1. Please list any specific facts or figures that are GIVEN in the request itself. It is possible that there are none.
+ 2. Please list any facts that may need to be looked up, and WHERE SPECIFICALLY they might be found. In some cases, authoritative sources are mentioned in the request itself.
+ 3. Please list any facts that may need to be derived (e.g., via logical deduction, simulation, or computation)
+ 4. Please list any facts that are recalled from memory, hunches, well-reasoned guesses, etc.
+
+When answering this survey, keep in mind that "facts" will typically be specific names, dates, statistics, etc. Your answer should use headings:
+
+ 1. GIVEN OR VERIFIED FACTS
+ 2. FACTS TO LOOK UP
+ 3. FACTS TO DERIVE
+ 4. EDUCATED GUESSES
+"""
+
+
+ORCHESTRATOR_PLAN_PROMPT = """Fantastic. To address this request we have assembled the following team:
+
+{team}
+
+Based on the team composition, and known and unknown facts, please devise a short bullet-point plan for addressing the original request. Remember, there is no requirement to involve all team members -- a team member's particular expertise may not be needed for this task."""
+
+
+ORCHESTRATOR_SYNTHESIZE_PROMPT = """
+We are working to address the following user request:
+
+{task}
+
+
+To answer this request we have assembled the following team:
+
+{team}
+
+Some additional points to consider:
+
+{facts}
+
+{plan}
+"""
+
+ORCHESTRATOR_LEDGER_PROMPT = """
+Recall we are working on the following request:
+
+{task}
+
+And we have assembled the following team:
+
+{team}
+
+To make progress on the request, please answer the following questions, including necessary reasoning:
+
+ - Is the request fully satisfied? (True if complete, or False if the original request has yet to be SUCCESSFULLY and FULLY addressed)
+ - Are we in a loop where we are repeating the same requests and / or getting the same responses as before? Loops can span multiple turns, and can include repeated actions like scrolling up or down more than a handful of times.
+ - Are we making forward progress? (True if just starting, or recent messages are adding value. False if recent messages show evidence of being stuck in a loop or if there is evidence of significant barriers to success such as the inability to read from a required file)
+ - Who should speak next? (select from: {names})
+ - What instruction or question would you give this team member? (Phrase as if speaking directly to them, and include any specific information they may need)
+
+Please output an answer in pure JSON format according to the following schema. The JSON object must be parsable as-is. DO NOT OUTPUT ANYTHING OTHER THAN JSON, AND DO NOT DEVIATE FROM THIS SCHEMA:
+
+ {{
+ "next_speaker": {{
+ "reason": string,
+ "answer": string (select from: {names})
+ }},
+ "instruction_or_question": {{
+ "reason": string,
+ "answer": string
+ }},
+ "is_request_satisfied": {{
+ "reason": string,
+ "answer": boolean
+ }},
+ "is_in_loop": {{
+ "reason": string,
+ "answer": boolean
+ }},
+ "is_progress_being_made": {{
+ "reason": string,
+ "answer": boolean
+ }}
+ }}
+"""