Unified system instructions. Added streaming to Agent SDK examples.

pyproject.toml

@@ -1,7 +1,7 @@
 [project]
-name = "aieng-template-uv"
+name = "agent-bootcamp-202507"
 version = "0.1.0"
-description = "Add your description here"
+description = "Vector Institute Agent Bootcamp 202507"
 readme = "README.md"
 authors = [ {name = "Vector AI Engineering", email = "ai_engineering@vectorinstitute.ai"}]
 license = "Apache-2.0"
@@ -93,6 +93,7 @@ ignore = [
     "PLR0913", # Too many arguments
     "COM812", # Missing trailing comma
     "N999", # Number in module names.
+    "ERA001", # Commented out lines.
 ]
 
 # Ignore import violations in all `__init__.py` files.

src/1_basics/1_react_rag/README.md

@@ -5,6 +5,7 @@ This folder contains an example of a basic Reason-and-Act (ReAct) agent for know
 ## Run
 
 ```bash
+uv run -m src.1_basics.1_react_rag.manual_tools
 uv run -m src.1_basics.1_react_rag.main
 uv run -m src.1_basics.1_react_rag.gradio
 ```

src/1_basics/1_react_rag/gradio.py

@@ -15,6 +15,7 @@
 from openai import AsyncOpenAI
 from openai.types.chat import ChatCompletionSystemMessageParam, ChatCompletionToolParam
 
+from src.prompts import REACT_INSTRUCTIONS
 from src.utils import (
     AsyncWeaviateKnowledgeBase,
     Configs,
@@ -52,14 +53,7 @@
 
 system_message: "ChatCompletionSystemMessageParam" = {
     "role": "system",
-    "content": (
-        "Answer the question using the search tool. "
-        "You must explain your reasons for invoking the tool. "
-        "Be sure to mention the sources. "
-        "If the search did not return intended results, try again. "
-        "Do not make up information. You must use the search tool "
-        "for all facts that might change over time."
-    ),
+    "content": REACT_INSTRUCTIONS,
 }
 
 
@@ -95,13 +89,14 @@ async def react_rag(query: str, history: list[ChatMessage]):
         # Execute tool calls and send results back to LLM if requested.
         # Otherwise, stop, as the conversation would have been finished.
         tool_calls = message.tool_calls
-        if tool_calls is None:
-            history.append(
-                ChatMessage(
-                    content=message.content or "",
-                    role="assistant",
-                )
+        history.append(
+            ChatMessage(
+                content=message.content or "",
+                role="assistant",
             )
+        )
+
+        if tool_calls is None:
             yield history
             break
 

src/1_basics/1_react_rag/main.py

@@ -8,6 +8,7 @@
 from dotenv import load_dotenv
 from openai import AsyncOpenAI
 
+from src.prompts import REACT_INSTRUCTIONS
 from src.utils import (
     AsyncWeaviateKnowledgeBase,
     Configs,
@@ -67,14 +68,7 @@ async def _main():
     messages: list = [
         {
             "role": "system",
-            "content": (
-                "Answer the question using the search tool. "
-                "You must explain your reasons for invoking the tool. "
-                "Be sure to mention the sources. "
-                "If the search did not return intended results, try again. "
-                "Do not make up information. You must use the search tool "
-                "for all facts that might change over time."
-            ),
+            "content": REACT_INSTRUCTIONS,
         },
         {
             "role": "user",

src/2_frameworks/1_react_rag/basic.py

@@ -3,10 +3,17 @@
 import asyncio
 import logging
 
-from agents import Agent, OpenAIChatCompletionsModel, RunConfig, Runner, function_tool
+from agents import (
+    Agent,
+    OpenAIChatCompletionsModel,
+    RunConfig,
+    Runner,
+    function_tool,
+)
 from dotenv import load_dotenv
 from openai import AsyncOpenAI
 
+from src.prompts import REACT_INSTRUCTIONS
 from src.utils import (
     AsyncWeaviateKnowledgeBase,
     Configs,
@@ -20,15 +27,6 @@
 AGENT_LLM_NAME = "gemini-2.5-flash"
 no_tracing_config = RunConfig(tracing_disabled=True)
 
-INSTRUCTIONS = """\
-Answer the question using the search tool. \
-Always plan your actions before invoking the tool. \
-Be sure to mention the sources. \
-If the search did not return intended results, try again. \
-Do not make up information. You must use the search tool \
-for all facts that might change over time.
-"""
-
 
 async def _main(query: str):
     configs = Configs.from_env_var()
@@ -50,7 +48,7 @@ async def _main(query: str):
 
     wikipedia_agent = Agent(
         name="Wikipedia Agent",
-        instructions=INSTRUCTIONS,
+        instructions=REACT_INSTRUCTIONS,
         tools=[function_tool(async_knowledgebase.search_knowledgebase)],
         model=OpenAIChatCompletionsModel(
             model=AGENT_LLM_NAME, openai_client=async_openai_client
@@ -63,10 +61,23 @@ async def _main(query: str):
         run_config=no_tracing_config,
     )
 
-    pretty_print(response.raw_responses)
-    pretty_print(response.new_items)
+    for item in response.new_items:
+        pretty_print(item.raw_item)
+        print()
+
     pretty_print(response.final_output)
 
+    # Uncomment the following for a basic "streaming" example
+
+    # from src.utils import oai_agent_stream_to_gradio_messages
+    # result_stream = Runner.run_streamed(
+    #     wikipedia_agent, input=query, run_config=no_tracing_config
+    # )
+    # async for event in result_stream.stream_events():
+    #     event_parsed = oai_agent_stream_to_gradio_messages(event)
+    #     if len(event_parsed) > 0:
+    #         pretty_print(event_parsed)
+
     await async_weaviate_client.close()
     await async_openai_client.close()
 

src/2_frameworks/1_react_rag/gradio.py

@@ -12,11 +12,13 @@
 from gradio.components.chatbot import ChatMessage
 from openai import AsyncOpenAI
 
+from src.prompts import REACT_INSTRUCTIONS
 from src.utils import (
     AsyncWeaviateKnowledgeBase,
     Configs,
     get_weaviate_async_client,
     oai_agent_items_to_gradio_messages,
+    oai_agent_stream_to_gradio_messages,
     pretty_print,
 )
 
@@ -26,14 +28,6 @@
 
 logging.basicConfig(level=logging.INFO)
 
-SYSTEM_MESSAGE = """\
-Answer the question using the search tool. \
-Always plan your actions before invoking the tool. \
-Be sure to mention the sources. \
-If the search did not return intended results, try again. \
-Do not make up information. You must use the search tool \
-for all facts that might change over time.
-"""
 
 AGENT_LLM_NAME = "gemini-2.5-flash"
 
@@ -70,19 +64,18 @@ def _handle_sigint(signum: int, frame: object) -> None:
 async def _main(question: str, gr_messages: list[ChatMessage]):
     main_agent = agents.Agent(
         name="Wikipedia Agent",
-        instructions=SYSTEM_MESSAGE,
+        instructions=REACT_INSTRUCTIONS,
         tools=[agents.function_tool(async_knowledgebase.search_knowledgebase)],
         model=agents.OpenAIChatCompletionsModel(
             model=AGENT_LLM_NAME, openai_client=async_openai_client
         ),
     )
-    gr_messages.append(ChatMessage(role="user", content=question))
-    yield gr_messages
 
-    responses = await agents.Runner.run(main_agent, input=question)
-    gr_messages += oai_agent_items_to_gradio_messages(responses.new_items)
-    pretty_print(gr_messages)
-    yield gr_messages
+    result_stream = agents.Runner.run_streamed(main_agent, input=question)
+    async for _item in result_stream.stream_events():
+        gr_messages += oai_agent_stream_to_gradio_messages(_item)
+        if len(gr_messages) > 0:
+            yield gr_messages
 
 
 demo = gr.ChatInterface(

src/2_frameworks/1_react_rag/langfuse_gradio.py

@@ -15,11 +15,12 @@
 from gradio.components.chatbot import ChatMessage
 from openai import AsyncOpenAI
 
+from src.prompts import REACT_INSTRUCTIONS
 from src.utils import (
     AsyncWeaviateKnowledgeBase,
     Configs,
     get_weaviate_async_client,
-    oai_agent_items_to_gradio_messages,
+    oai_agent_stream_to_gradio_messages,
     pretty_print,
     setup_langfuse_tracer,
 )
@@ -31,15 +32,6 @@
 
 logging.basicConfig(level=logging.INFO)
 
-SYSTEM_MESSAGE = """\
-Answer the question using the search tool. \
-Always plan your actions before invoking the tool. \
-Be sure to mention the sources. \
-If the search did not return intended results, you will always try again. \
-Do not make up information. You must use the search tool \
-for all facts that might change over time.
-"""
-
 AGENT_LLM_NAME = "gemini-2.5-flash"
 
 configs = Configs.from_env_var()
@@ -77,21 +69,24 @@ async def _main(question: str, gr_messages: list[ChatMessage]):
 
     main_agent = agents.Agent(
         name="Wikipedia Agent",
-        instructions=SYSTEM_MESSAGE,
+        instructions=REACT_INSTRUCTIONS,
         tools=[agents.function_tool(async_knowledgebase.search_knowledgebase)],
         model=agents.OpenAIChatCompletionsModel(
             model=AGENT_LLM_NAME, openai_client=async_openai_client
         ),
     )
-    gr_messages.append(ChatMessage(role="user", content=question))
-    yield gr_messages
 
     with langfuse_client.start_as_current_span(name="Agents-SDK-Trace") as span:
         span.update(input=question)
-        responses = await agents.Runner.run(main_agent, input=question)
-        span.update(output=responses.final_output)
 
-    gr_messages += oai_agent_items_to_gradio_messages(responses.new_items)
+        result_stream = agents.Runner.run_streamed(main_agent, input=question)
+        async for _item in result_stream.stream_events():
+            gr_messages += oai_agent_stream_to_gradio_messages(_item)
+            if len(gr_messages) > 0:
+                yield gr_messages
+
+        span.update(output=result_stream.final_output)
+
     pretty_print(gr_messages)
     yield gr_messages
 

src/prompts.py

@@ -0,0 +1,12 @@
+"""Centralized location for all system prompts."""
+
+REACT_INSTRUCTIONS = """\
+Answer the question using the search tool. \
+EACH TIME before invoking the function, you must explain your reasons for doing so. \
+Be sure to mention the sources in your response. \
+If the search tool did not return intended results, try again. \
+For best performance, divide complex queries into simpler sub-queries. \
+Do not make up information. \
+For facts that might change over time, you must use the search tool to retrieve the \
+most up-to-date information.
+"""

src/utils/__init__.py

@@ -5,6 +5,7 @@
 from .gradio.messages import (
     gradio_messages_to_oai_chat,
     oai_agent_items_to_gradio_messages,
+    oai_agent_stream_to_gradio_messages,
 )
 from .langfuse.oai_sdk_setup import setup_langfuse_tracer
 from .logging import set_up_logging

src/utils/gradio/messages.py

@@ -2,9 +2,15 @@
 
 from typing import TYPE_CHECKING
 
+from agents import StreamEvent, stream_events
 from agents.items import MessageOutputItem, RunItem, ToolCallItem, ToolCallOutputItem
 from gradio.components.chatbot import ChatMessage
-from openai.types.responses import ResponseFunctionToolCall, ResponseOutputText
+from openai.types.responses import (
+    ResponseCompletedEvent,
+    ResponseFunctionToolCall,
+    ResponseOutputMessage,
+    ResponseOutputText,
+)
 
 from ..pretty_printing import pretty_print
 
@@ -94,3 +100,36 @@ def oai_agent_items_to_gradio_messages(
             output.extend(maybe_messages)
 
     return output
+
+
+def oai_agent_stream_to_gradio_messages(
+    stream_event: StreamEvent,
+) -> list[ChatMessage]:
+    """Parse agent sdk "stream event" into a list of gr messages.
+
+    Adds extra data for tool use to make the gradio display informative.
+    """
+    output: list[ChatMessage] = []
+    if isinstance(stream_event, stream_events.RawResponsesStreamEvent):
+        data = stream_event.data
+        if isinstance(data, ResponseCompletedEvent):
+            for message in data.response.output:
+                if isinstance(message, ResponseOutputMessage):
+                    for _item in message.content:
+                        if isinstance(_item, ResponseOutputText):
+                            output.append(
+                                ChatMessage(role="assistant", content=_item.text)
+                            )
+
+                elif isinstance(message, ResponseFunctionToolCall):
+                    output.append(
+                        ChatMessage(
+                            role="assistant",
+                            content=f"```\n{message.arguments}\n```",
+                            metadata={
+                                "title": f"Used tool `{message.name}`",
+                            },
+                        )
+                    )
+
+    return output