Update README.md

README.md

@@ -46,7 +46,7 @@ You can override the shared client by calling the init function.
 import workflowai
 
 workflowai.init(
-    url=..., # defaults to WORKFLOWAI_API_URL env var or https://api.workflowai.com
+    url=..., # defaults to WORKFLOWAI_API_URL env var or https://run.workflowai.com (our [globally distributed, highly available endpoint](https://docs.workflowai.com/workflowai-cloud/reliability))
     api_key=..., # defaults to WORKFLOWAI_API_KEY env var
 )
 ```
@@ -335,7 +335,7 @@ image = Image(content_type='image/jpeg', data='<base 64 encoded data>')
 image = Image(url="https://example.com/image.jpg")
 ```
 
-An example of using image as input is available in [city_identifier.py](./examples/images/city_identifier.py).
+An example of using image as input is available in [07_image_agent.py](./examples/07_image_agent.py).
 
 ### Files (PDF, .txt, ...)
 

examples/01_basic_agent.py

@@ -61,13 +61,13 @@ async def main():
     # Example 1: Basic usage with Paris
     print("\nExample 1: Basic usage with Paris")
     print("-" * 50)
-    run = await get_capital_info(CityInput(city="Paris"))
+    run = await get_capital_info.run(CityInput(city="Paris"))
     print(run)
 
     # Example 2: Using Tokyo
     print("\nExample 2: Using Tokyo")
     print("-" * 50)
-    run = await get_capital_info(CityInput(city="Tokyo"))
+    run = await get_capital_info.run(CityInput(city="Tokyo"))
     print(run)
 
 

examples/07_image_agent.py

@@ -13,7 +13,7 @@
 from pydantic import BaseModel, Field  # pyright: ignore [reportUnknownVariableType]
 
 import workflowai
-from workflowai import Run, WorkflowAIError
+from workflowai import WorkflowAIError
 from workflowai.core.domain.model import Model
 from workflowai.fields import Image
 
@@ -31,8 +31,8 @@ class ImageOutput(BaseModel):
     )
 
 
-@workflowai.agent(id="city-identifier", model=Model.GEMINI_1_5_FLASH_LATEST)
-async def identify_city_from_image(_: ImageInput) -> Run[ImageOutput]:
+@workflowai.agent(id="city-identifier", model=Model.GEMINI_2_0_FLASH_LATEST)
+async def identify_city_from_image(image_input: ImageInput) -> ImageOutput:
     """
     Analyze the provided image and identify the city and country shown in it.
     If the image shows a recognizable landmark or cityscape, identify the city and country.
@@ -62,9 +62,8 @@ async def main():
 
     image = Image(content_type="image/jpeg", data=content)
     try:
-        agent_run = await identify_city_from_image(
+        agent_run = await identify_city_from_image.run(
             ImageInput(image=image),
-            use_cache="auto",
         )
     except WorkflowAIError as e:
         print(f"Failed to run task. Code: {e.error.code}. Message: {e.error.message}")
@@ -77,9 +76,8 @@ async def main():
     # Example using URL for Image
     image_url = "https://t4.ftcdn.net/jpg/02/96/15/35/360_F_296153501_B34baBHDkFXbl5RmzxpiOumF4LHGCvAE.jpg"
     image = Image(url=image_url)
-    agent_run = await identify_city_from_image(
+    agent_run = await identify_city_from_image.run(
         ImageInput(image=image),
-        use_cache="auto",
     )
 
     print("\n--------\nAgent output:\n", agent_run.output, "\n--------\n")

examples/11_ecommerce_chatbot.py

@@ -2,25 +2,17 @@
 This example demonstrates how to create an e-commerce chatbot that:
 1. Understands customer queries about products
 2. Provides helpful responses with product recommendations
-3. Maintains context through conversation
+3. Maintains context through conversation using .reply
 4. Returns structured product recommendations
 """
 
 import asyncio
-from enum import Enum
 from typing import Optional
 
 from pydantic import BaseModel, Field
 
 import workflowai
-from workflowai import Model, Run
-
-
-class Role(str, Enum):
-    """Enum representing possible message roles."""
-
-    USER = "user"
-    ASSISTANT = "assistant"
+from workflowai import Model
 
 
 class Product(BaseModel):
@@ -56,30 +48,18 @@ class Product(BaseModel):
     )
 
 
-class Message(BaseModel):
-    """Model representing a chat message."""
+class AssistantMessage(BaseModel):
+    """Model representing a message from the assistant."""
 
-    role: Role = Field()
     content: str = Field(
         description="The content of the message",
-        examples=[
-            "I'm looking for noise-cancelling headphones for travel",
-            "Based on your requirements, here are some great headphone options...",
-        ],
     )
     recommended_products: Optional[list[Product]] = Field(
         default=None,
         description="Product recommendations included with this message, if any",
     )
 
 
-class AssistantMessage(Message):
-    """Model representing a message from the assistant."""
-
-    role: Role = Role.ASSISTANT
-    content: str = ""
-
-
 class ChatbotOutput(BaseModel):
     """Output model for the chatbot response."""
 
@@ -89,12 +69,8 @@ class ChatbotOutput(BaseModel):
 
 
 class ChatInput(BaseModel):
-    """Input model containing the user's message and conversation history."""
+    """Input model containing the user's message."""
 
-    conversation_history: Optional[list[Message]] = Field(
-        default=None,
-        description="Previous messages in the conversation, if any",
-    )
     user_message: str = Field(
         description="The current message from the user",
     )
@@ -104,7 +80,7 @@ class ChatInput(BaseModel):
     id="ecommerce-chatbot",
     model=Model.LLAMA_3_3_70B,
 )
-async def get_product_recommendations(chat_input: ChatInput) -> Run[ChatbotOutput]:
+async def get_product_recommendations(chat_input: ChatInput) -> ChatbotOutput:
     """
     Act as a knowledgeable e-commerce shopping assistant.
 
@@ -142,63 +118,34 @@ async def main():
     print("\nExample 1: Looking for headphones")
     print("-" * 50)
 
-    chat_input = ChatInput(
-        user_message="I'm looking for noise-cancelling headphones for travel. My budget is around $300.",
+    run = await get_product_recommendations.run(
+        ChatInput(user_message="I'm looking for noise-cancelling headphones for travel. My budget is around $300."),
     )
-
-    run = await get_product_recommendations(chat_input)
     print(run)
 
-    # Example 2: Follow-up question with conversation history
+    # Example 2: Follow-up question using reply
     print("\nExample 2: Follow-up about battery life")
     print("-" * 50)
 
-    chat_input = ChatInput(
-        user_message="Which one has the best battery life?",
-        conversation_history=[
-            Message(
-                role=Role.USER,
-                content="I'm looking for noise-cancelling headphones for travel. My budget is around $300.",
-            ),
-            run.output.assistant_message,
-        ],
-    )
-
-    run = await get_product_recommendations(chat_input)
+    run = await run.reply(user_message="Which one has the best battery life?")
     print(run)
 
     # Example 3: Specific question about a previously recommended product
     print("\nExample 3: Question about a specific product")
     print("-" * 50)
 
-    chat_input = ChatInput(
-        user_message="Tell me more about the noise cancellation features of the first headphone you recommended.",
-        conversation_history=[
-            Message(
-                role=Role.USER,
-                content="I'm looking for noise-cancelling headphones for travel. My budget is around $300.",
-            ),
-            run.output.assistant_message,
-            Message(
-                role=Role.USER,
-                content="Which one has the best battery life?",
-            ),
-            run.output.assistant_message,
-        ],
+    run = await run.reply(
+        user_message=(
+            "Tell me more about the noise cancellation features of the first headphone you recommended."
+        ),
     )
-
-    run = await get_product_recommendations(chat_input)
     print(run)
 
     # Example 4: Different product category
     print("\nExample 4: Looking for a TV")
     print("-" * 50)
 
-    chat_input = ChatInput(
-        user_message="I need a good TV for gaming. My budget is $1000.",
-    )
-
-    run = await get_product_recommendations(chat_input)
+    run = await run.reply(user_message="I need a good TV for gaming. My budget is $1000.")
     print(run)
 
 

examples/13_rag.py

@@ -2,7 +2,7 @@
 This example demonstrates how to create a RAG-enabled chatbot that:
 1. Uses a search tool to find relevant information from a knowledge base
 2. Incorporates search results into its responses
-3. Maintains conversation context
+3. Maintains context through conversation using .reply
 4. Provides well-structured, informative responses
 
 Note: WorkflowAI does not manage the RAG implementation (yet). You need to provide your own
@@ -11,20 +11,11 @@
 """
 
 import asyncio
-from enum import Enum
-from typing import Optional
 
 from pydantic import BaseModel, Field
 
 import workflowai
-from workflowai import Model, Run
-
-
-class Role(str, Enum):
-    """Enum representing possible message roles."""
-
-    USER = "user"
-    ASSISTANT = "assistant"
+from workflowai import Model
 
 
 class SearchResult(BaseModel):
@@ -79,38 +70,25 @@ async def search_faq(query: str) -> list[SearchResult]:
     ]
 
 
-class Message(BaseModel):
-    """Model representing a chat message."""
+class AssistantMessage(BaseModel):
+    """Model representing a message from the assistant."""
 
-    role: Role
     content: str = Field(
         description="The content of the message",
     )
 
 
-class AssistantMessage(Message):
-    """Model representing a message from the assistant."""
-
-    role: Role = Role.ASSISTANT
-    content: str = ""
-
-
 class ChatbotOutput(BaseModel):
     """Output model for the chatbot response."""
 
     assistant_message: AssistantMessage = Field(
-        default_factory=AssistantMessage,
         description="The chatbot's response message",
     )
 
 
 class ChatInput(BaseModel):
-    """Input model containing the user's message and conversation history."""
+    """Input model containing the user's message."""
 
-    conversation_history: Optional[list[Message]] = Field(
-        default=None,
-        description="Previous messages in the conversation, if any",
-    )
     user_message: str = Field(
         description="The current message from the user",
     )
@@ -124,7 +102,7 @@ class ChatInput(BaseModel):
     # The agent will automatically handle calling the tool and incorporating the results.
     tools=[search_faq],
 )
-async def chat_agent(chat_input: ChatInput) -> Run[ChatbotOutput]:
+async def chat_agent(chat_input: ChatInput) -> ChatbotOutput:
     """
     Act as a knowledgeable assistant that uses search to find and incorporate relevant information.
 
@@ -165,15 +143,27 @@ async def chat_agent(chat_input: ChatInput) -> Run[ChatbotOutput]:
 
 
 async def main():
-    # Example: Question about return policy
-    print("\nExample: Question about return policy")
+    # Example 1: Initial question about return policy
+    print("\nExample 1: Question about return policy")
     print("-" * 50)
 
-    chat_input = ChatInput(
-        user_message="What is your return policy? Can I return items I bought online?",
+    run = await chat_agent.run(
+        ChatInput(user_message="What is your return policy? Can I return items I bought online?"),
     )
+    print(run)
+
+    # Example 2: Follow-up question about shipping
+    print("\nExample 2: Follow-up about shipping")
+    print("-" * 50)
+
+    run = await run.reply(user_message="How long does shipping usually take?")
+    print(run)
+
+    # Example 3: Specific question about refund processing
+    print("\nExample 3: Question about refunds")
+    print("-" * 50)
 
-    run = await chat_agent(chat_input)
+    run = await run.reply(user_message="Once I return an item, how long until I get my refund?")
     print(run)