Release v0.3.1: Anthropic client, test fixes, and enhancements

Added:
- Anthropic Claude model client with full API support
- GitHub Models integration example
- Agent-as-tool result strategies for flexible output handling
- Context engineering examples with token tracking
- Anthropic optional dependency in pyproject.toml

Changed:
- Updated model client tests for better coverage
- Improved workflow integration tests
- Enhanced WebUI workflow view components

Fixed:
- Anthropic model name in tests (claude-3-5-haiku-20241022)
- CancellationToken import path in workflow tests
- Workflow step progress events test signatures
- OpenAI test model (gpt-4.1-mini)

Author: victordibia

README.md

@@ -128,6 +128,43 @@ response = await agent.run("What's the weather in Paris?")
 print(response.messages[-1].content)
 ```
 
+### Model Client Setup
+
+PicoAgents supports multiple LLM providers through a unified interface. Each provider requires minimal setup—just API credentials and switching the client class. Chapter 4 covers building custom model clients for any provider.
+
+| Provider | Client Class | Setup | Example | Source |
+|----------|-------------|-------|---------|--------|
+| **OpenAI** | [`OpenAIChatCompletionClient`](picoagents/src/picoagents/llm/_openai.py) | 1. Get API key from [platform.openai.com](https://platform.openai.com)<br>2. `export OPENAI_API_KEY='sk-...'` | [`basic-agent.py`](examples/agents/basic-agent.py) | [`_openai.py`](picoagents/src/picoagents/llm/_openai.py) |
+| **Azure OpenAI** | [`AzureOpenAIChatCompletionClient`](picoagents/src/picoagents/llm/_azure_openai.py) | 1. Deploy model on [Azure Portal](https://portal.azure.com)<br>2. Set endpoint, key, deployment name | [`agent_azure.py`](examples/agents/agent_azure.py) | [`_azure_openai.py`](picoagents/src/picoagents/llm/_azure_openai.py) |
+| **Anthropic** | [`AnthropicChatCompletionClient`](picoagents/src/picoagents/llm/_anthropic.py) | 1. Get API key from [console.anthropic.com](https://console.anthropic.com)<br>2. `export ANTHROPIC_API_KEY='sk-...'` | [`agent_anthropic.py`](examples/agents/agent_anthropic.py) | [`_anthropic.py`](picoagents/src/picoagents/llm/_anthropic.py) |
+| **GitHub Models** | [`OpenAIChatCompletionClient`](picoagents/src/picoagents/llm/_openai.py)<br>+ `base_url` | 1. Get token from [github.com/settings/tokens](https://github.com/settings/tokens)<br>2. `export GITHUB_TOKEN='ghp_...'`<br>3. Set `base_url="https://models.github.ai/inference"` | [`agent_githubmodels.py`](examples/agents/agent_githubmodels.py) | Uses [`_openai.py`](picoagents/src/picoagents/llm/_openai.py) |
+| **Local/Custom** | [`OpenAIChatCompletionClient`](picoagents/src/picoagents/llm/_openai.py)<br>+ `base_url` | Point to any OpenAI-compatible endpoint<br>(Ollama, LM Studio, vLLM, etc.) | Use `base_url="http://localhost:8000"` | Uses [`_openai.py`](picoagents/src/picoagents/llm/_openai.py) |
+
+**Quick Examples:**
+
+```python
+# OpenAI (default)
+from picoagents import OpenAIChatCompletionClient
+client = OpenAIChatCompletionClient(model="gpt-4.1-mini")
+
+# Anthropic
+from picoagents import AnthropicChatCompletionClient
+client = AnthropicChatCompletionClient(model="claude-3-5-sonnet-20241022")
+
+# GitHub Models (free tier)
+client = OpenAIChatCompletionClient(
+    model="openai/gpt-4.1-mini",
+    api_key=os.getenv("GITHUB_TOKEN"),
+    base_url="https://models.github.ai/inference"
+)
+
+# Local LLM (e.g., Ollama)
+client = OpenAIChatCompletionClient(
+    model="llama3.2",
+    base_url="http://localhost:11434/v1"
+)
+```
+
 ### Launch the Web UI
 
 ![PicoAgents Web UI](./docs/images/picoagents_screenshot.png)

docs/images/dashboard.png

@@ -0,0 +1,134 @@
+#!/usr/bin/env python3
+"""
+Anthropic Claude Agent Example
+
+Shows how to use Claude models with PicoAgents.
+Demonstrates both tool calling and structured outputs with Claude Sonnet 4.5.
+
+Requires: ANTHROPIC_API_KEY environment variable
+Run: python examples/agents/agent_anthropic.py
+"""
+
+import asyncio
+import os
+from typing import List
+from pydantic import BaseModel
+
+from picoagents import Agent
+from picoagents.llm import AnthropicChatCompletionClient
+
+
+# Define structured output format
+class TravelRecommendation(BaseModel):
+    """Structured travel recommendation."""
+    destination: str
+    best_months: List[str]
+    attractions: List[str]
+    estimated_budget: str
+    travel_tips: List[str]
+
+
+def get_weather(location: str) -> str:
+    """Get current weather for a given location."""
+    return f"The weather in {location} is sunny, 75°F with clear skies"
+
+
+def get_flight_info(origin: str, destination: str) -> str:
+    """Get flight information between two cities."""
+    return f"Direct flights from {origin} to {destination} available daily, starting at $450"
+
+
+async def main():
+    """Run examples with Claude."""
+    print("=== Claude Agent Examples ===\n")
+
+    # Example 1: Basic tool calling
+    print("1. Tool Calling Example:")
+    print("-" * 40)
+
+    tool_agent = Agent(
+        name="travel_assistant",
+        description="A travel planning assistant",
+        instructions="You are a helpful travel assistant with access to weather and flight information.",
+        model_client=AnthropicChatCompletionClient(
+            model="claude-sonnet-4-5",  # Supports all features
+            api_key=os.getenv("ANTHROPIC_API_KEY")
+        ),
+        tools=[get_weather, get_flight_info],
+        example_tasks=[
+            "What's the weather in San Francisco?",
+            "Are there flights from NYC to London?",
+        ],
+    )
+
+    # Simple tool calling with streaming
+    async for event in tool_agent.run_stream(
+        "What's the weather in Paris and are there flights from San Francisco?",
+        stream_tokens=False
+    ):
+        print(event)
+
+    print("\n" + "=" * 50 + "\n")
+
+    # Example 2: Structured output
+    print("2. Structured Output Example:")
+    print("-" * 40)
+
+    structured_agent = Agent(
+        name="travel_planner",
+        description="A travel recommendation agent",
+        instructions="You are a travel expert. Provide detailed recommendations for destinations.",
+        model_client=AnthropicChatCompletionClient(
+            model="claude-sonnet-4-5",  # Required for structured outputs
+            api_key=os.getenv("ANTHROPIC_API_KEY")
+        ),
+        output_format=TravelRecommendation
+    )
+
+    response = await structured_agent.run(
+        "Recommend a beach vacation in Southeast Asia"
+    )
+
+    # Access structured output from the assistant message
+    last_message = response.messages[-1]
+    if hasattr(last_message, 'structured_content') and last_message.structured_content:
+        rec = last_message.structured_content
+        print(f"\nStructured Recommendation:")
+        print(f"  Destination: {rec.destination}")
+        print(f"  Best Months: {', '.join(rec.best_months[:3])}")
+        print(f"  Top Attractions: {', '.join(rec.attractions[:3])}")
+        print(f"  Budget: {rec.estimated_budget}")
+        print(f"  Key Tip: {rec.travel_tips[0]}")
+    else:
+        # The content is JSON but not parsed as structured_content
+        print(f"\nResponse (JSON format):")
+        print(f"  {last_message.content[:200]}...")
+
+    print("\n" + "=" * 50 + "\n")
+
+    # Example 3: Streaming with structured output
+    print("3. Streaming Structured Output:")
+    print("-" * 40)
+
+    print("Getting recommendation for Japan...")
+    event_count = 0
+    async for event in structured_agent.run_stream(
+        "Recommend a cultural trip to Japan",
+        stream_tokens=False  # Structured output comes at the end
+    ):
+        event_count += 1
+        if hasattr(event, 'structured_content') and event.structured_content:
+            print(f"\n✓ Received structured recommendation:")
+            print(f"  Destination: {event.structured_content.destination}")
+            print(f"  Best time: {', '.join(event.structured_content.best_months[:2])}")
+        # Show a sample of the streaming events
+        if event_count <= 3:
+            print(f"  Event {event_count}: {str(event)[:80]}...")
+
+
+if __name__ == "__main__":
+    if not os.getenv("ANTHROPIC_API_KEY"):
+        print("Please set ANTHROPIC_API_KEY environment variable")
+        print("export ANTHROPIC_API_KEY='your-key-here'")
+    else:
+        asyncio.run(main())

examples/agents/agent_anthropic.py

@@ -56,15 +56,24 @@ def tool_agents():
 
 
 # Create coordinator that uses both specialists as tools
+# Note: You can control how results are extracted using result_strategy:
+# - "last" (default): Returns only the final message
+# - "last:N": Returns last N messages concatenated
+# - "all": Returns all messages
+# - Custom callable: Function that processes messages and returns a string
 agent = Agent(
     name="research_coordinator",
     description="Coordinates research tasks using specialist agents",
     instructions="You solve tasks by delegating to the relevant agents or tools",
     model_client=model_client,
-    tools=[weather_agent.as_tool(), analysis_agent.as_tool()],
+    tools=[
+        weather_agent.as_tool(),  # Default: last message only
+        analysis_agent.as_tool(result_strategy="last:2"),  # Last 2 messages
+    ],
     example_tasks=[
         "Get the current weather in New York and analyze recent sales data.",
-        "Provide a brief report on the weather in San Francisco and its impact on outdoor events.",]
+        "Provide a brief report on the weather in San Francisco and its impact on outdoor events.",
+    ],
 )
 
 

examples/agents/agent_as_tool.py

@@ -0,0 +1,54 @@
+"""
+GitHub Models Agent Example
+
+Shows how to use GitHub Models with PicoAgents via base_url.
+Requires: GITHUB_TOKEN environment variable
+
+Run: python examples/agents/agent_githubmodels.py
+"""
+
+import asyncio
+import os
+
+from picoagents import Agent, OpenAIChatCompletionClient
+
+
+def get_weather(location: str) -> str:
+    """Get current weather for a given location."""
+    return f"The weather in {location} is sunny, 75°F"
+
+
+# Create agent with GitHub Models endpoint
+agent = Agent(
+    name="github_models_assistant",
+    description="An assistant powered by GitHub Models",
+    instructions="You are a helpful assistant with weather access.",
+    model_client=OpenAIChatCompletionClient(
+        model="openai/gpt-4.1-mini",
+        api_key=os.getenv("GITHUB_TOKEN"),
+        base_url="https://models.github.ai/inference"
+    ),
+    tools=[get_weather],
+    example_tasks=[
+        "What's the weather in San Francisco?",
+        "Is it sunny in Tokyo?",
+    ],
+)
+
+
+async def main():
+    """Run example with GitHub Models."""
+    print("=== GitHub Models Agent ===\n")
+
+    async for event in agent.run_stream(
+        "What's the weather in Paris?",
+        stream_tokens=False
+    ):
+        print(event)
+
+
+if __name__ == "__main__":
+    if not os.getenv("GITHUB_TOKEN"):
+        print("Set GITHUB_TOKEN environment variable first")
+    else:
+        asyncio.run(main())

examples/agents/agent_githubmodels.py

@@ -41,14 +41,16 @@ async def process_request(self, context):
                         if re.search(pattern, message.content, re.IGNORECASE):
                             # Block the operation entirely - never reaches model or logs
                             raise ValueError(f"Blocked potentially malicious input")
-        return context
+        yield context
 
     async def process_response(self, context, result):
         """No response processing needed."""
-        return result
+        yield result
 
     async def process_error(self, context, error):
         """No error recovery."""
+        if False:  # Type checker hint
+            yield
         raise error
 
 

examples/agents/middleware.py

@@ -124,7 +124,7 @@ def _filter_content(self, content: str) -> str:
 
         return filtered_content
 
-    async def process_request(self, context: MiddlewareContext) -> MiddlewareContext:
+    async def process_request(self, context: MiddlewareContext):
         """Apply security checks before operations."""
 
         # Maintenance mode check
@@ -151,19 +151,21 @@ async def process_request(self, context: MiddlewareContext) -> MiddlewareContext
         logger.info(
             f"🛡️  Security check passed for {context.operation} (user: {user_id})"
         )
-        return context
+        yield context
 
-    async def process_response(self, context: MiddlewareContext, result: Any) -> Any:
+    async def process_response(self, context: MiddlewareContext, result: Any):
         """No response filtering needed for this example."""
-        return result
+        yield result
 
     async def process_error(
         self, context: MiddlewareContext, error: Exception
-    ) -> Optional[Any]:
+    ):
         """Log security events."""
         if "🚫" in str(error):
             user_id = context.agent_context.metadata.get("user_id", "anonymous")
             logger.warning(f"Security block for user {user_id}: {error}")
+        if False:  # Type checker hint
+            yield
         raise error
 
 
@@ -271,19 +273,21 @@ def _trim_context_intelligently(self, messages: List) -> List:
 
         return result
 
-    async def process_request(self, context: MiddlewareContext) -> MiddlewareContext:
+    async def process_request(self, context: MiddlewareContext):
         """Apply intelligent context management."""
         if context.operation == "model_call" and isinstance(context.data, list):
             context.data = self._trim_context_intelligently(context.data)
 
-        return context
+        yield context
 
-    async def process_response(self, context: MiddlewareContext, result: Any) -> Any:
-        return result
+    async def process_response(self, context: MiddlewareContext, result: Any):
+        yield result
 
     async def process_error(
         self, context: MiddlewareContext, error: Exception
-    ) -> Optional[Any]:
+    ):
+        if False:  # Type checker hint
+            yield
         raise error
 
 
@@ -391,8 +395,9 @@ async def process_error(
         error_msg = str(error)[:100] + "..." if len(str(error)) > 100 else str(error)
         logger.error(f"❌ Failed {context.operation} after {duration:.3f}s: {error_msg}")
 
+        if False:  # Type checker hint
+            yield
         raise error
-        yield  # pragma: no cover
 
 
 # =============================================================================

examples/agents/middleware_custom.py

@@ -201,7 +201,12 @@ async def main():
 
     print("\n" + "-" * 70)
     print("TASK 1 COMPLETE")
-    print(f"Final message: {response1.context.messages[-1].content if response1.context.messages else 'No messages'}")
+    final_msg = (
+        response1.context.messages[-1].content
+        if response1.context and response1.context.messages
+        else "No messages"
+    )
+    print(f"Final message: {final_msg}")
     print(f"Usage: {response1.usage}")
     print("-" * 70)
 
@@ -225,7 +230,12 @@ async def main():
 
     print("\n" + "-" * 70)
     print("TASK 2 COMPLETE")
-    print(f"Final message: {response2.context.messages[-1].content if response2.context.messages else 'No messages'}")
+    final_msg = (
+        response2.context.messages[-1].content
+        if response2.context and response2.context.messages
+        else "No messages"
+    )
+    print(f"Final message: {final_msg}")
     print(f"Usage: {response2.usage}")
     print("-" * 70)
 
@@ -250,7 +260,12 @@ async def main():
 
     print("\n" + "-" * 70)
     print("TASK 3 COMPLETE")
-    print(f"Final message: {response3.context.messages[-1].content if response3.context.messages else 'No messages'}")
+    final_msg = (
+        response3.context.messages[-1].content
+        if response3.context and response3.context.messages
+        else "No messages"
+    )
+    print(f"Final message: {final_msg}")
     print(f"Usage: {response3.usage}")
     print("-" * 70)