@bluefly/openstandardagents 0.3.5 → 0.3.6

package/examples/migrations/swarm-to-ossa/after-triage-agent.ossa.yaml

@@ -0,0 +1,315 @@
+---
+# OSSA v0.3.6 - Customer Service Triage Agent
+#
+# This is the OSSA equivalent of before-triage-agent.py
+#
+# Benefits over OpenAI Swarm:
+# - Declarative YAML (version control, CI/CD, GitOps)
+# - Deploy to ANY platform (Anthropic, OpenAI, LangChain, CrewAI, AutoGen)
+# - Production-ready (auth, observability, rate limiting, governance)
+# - 50% less code
+# - Enterprise features built-in
+
+apiVersion: ossa/v0.3.6
+kind: Agent
+metadata:
+  name: customer-service-triage
+  version: 1.0.0
+  description: "Customer service triage agent that routes requests to specialized agents"
+
+  # Agent Catalog (for discovery and reuse)
+  catalog:
+    published: true
+    catalog_id: ossa-customer-service-triage
+    visibility: public
+    categories:
+      - customer-service
+      - triage
+      - multi-agent
+    tags:
+      - customer-support
+      - routing
+      - handoffs
+    documentation_url: https://docs.example.com/agents/customer-service-triage
+
+  labels:
+    department: customer-service
+    tier: production
+    version: v1
+
+spec:
+  # Agent role and behavior
+  role: |
+    You are a friendly customer service triage agent.
+
+    Your role is to:
+    1. Greet customers warmly
+    2. Understand their request or issue
+    3. Route them to the appropriate specialist:
+       - Sales Agent: For product inquiries, purchases, or general questions
+       - Refunds Agent: For returns, refunds, or order issues
+
+    Be concise and efficient in your routing.
+
+  # LLM Configuration
+  llm:
+    provider: anthropic  # or "openai" to keep using OpenAI
+    model: claude-sonnet-4-5
+    temperature: 0.7
+    max_tokens: 2048
+
+  # Handoffs (Swarm's "transfer functions" → OSSA handoffs)
+  # This replaces transfer_to_sales_agent() and transfer_to_refunds_agent()
+  handoffs:
+    - name: route_to_sales
+      target_agent: sales-agent
+      description: "Route customer to sales agent for purchases and product questions"
+      condition: "intent == 'purchase' or intent == 'product_info' or intent == 'general_question'"
+      trigger: automatic  # Handoff happens automatically when condition is met
+      context_transfer: full  # Transfer entire conversation history
+
+    - name: route_to_refunds
+      target_agent: refunds-agent
+      description: "Route customer to refunds agent for returns and refunds"
+      condition: "intent == 'refund' or intent == 'return' or intent == 'complaint'"
+      trigger: automatic
+      context_transfer: full
+
+  # Context variables (Swarm's context_variables → OSSA context)
+  context_propagation:
+    mode: selective  # Only propagate specified fields
+    allowed_fields:
+      - user_id
+      - account_type
+      - session_id
+      - conversation_history
+    sensitive_fields:  # These require encryption in transit
+      - payment_info
+      - personal_data
+
+  # Authentication & Authorization (NOT available in Swarm)
+  identity:
+    provider: oauth2
+    authentication:
+      method: oauth2
+      scopes:
+        - read:user
+        - write:support_ticket
+      auto_refresh: true
+
+  # Observability (NOT available in Swarm)
+  observability:
+    metrics:
+      enabled: true
+      export_interval: 30s
+      metrics:
+        - handoff_rate
+        - response_time
+        - customer_satisfaction
+    tracing:
+      enabled: true
+      sampler: always_on
+    logging:
+      level: info
+      structured: true
+      include_context: true
+
+  # Rate Limiting (NOT available in Swarm)
+  constraints:
+    rate_limits:
+      requests_per_minute: 100
+      requests_per_hour: 1000
+      tokens_per_day: 500000
+    max_conversation_turns: 50
+    timeout_seconds: 30
+
+  # Cost Control (NOT available in Swarm)
+  token_efficiency:
+    enabled: true
+    target_savings: 0.5  # 50% token reduction
+    context_management:
+      strategy: adaptive
+      pruning:
+        enabled: true
+        threshold: 0.3  # Remove low-relevance context
+    caching:
+      enabled: true
+      strategy: semantic
+      ttl: 3600
+
+---
+# Sales Agent (equivalent to sales_agent in Swarm)
+apiVersion: ossa/v0.3.6
+kind: Agent
+metadata:
+  name: sales-agent
+  version: 1.0.0
+  description: "Sales specialist agent for product questions and orders"
+
+spec:
+  role: |
+    You are a knowledgeable sales agent.
+
+    Your role is to:
+    1. Answer product questions
+    2. Help customers make purchases
+    3. Provide recommendations
+    4. Execute orders when customers are ready
+
+    Be helpful and enthusiastic about our products!
+
+  llm:
+    provider: anthropic
+    model: claude-sonnet-4-5
+    temperature: 0.8  # More creative for sales
+    max_tokens: 2048
+
+  # Capabilities (Swarm's "functions" → OSSA capabilities)
+  # This replaces execute_order() function
+  capabilities:
+    - name: execute_order
+      description: "Execute a product order for the customer"
+      input_schema:
+        type: object
+        properties:
+          product_id:
+            type: string
+            description: "The product identifier"
+            pattern: "^[A-Z0-9-]+$"
+          quantity:
+            type: integer
+            description: "Number of items to order"
+            minimum: 1
+            maximum: 100
+            default: 1
+        required:
+          - product_id
+      output_schema:
+        type: object
+        properties:
+          order_id:
+            type: string
+            description: "Generated order identifier"
+          total_price:
+            type: number
+            description: "Total order price in USD"
+          status:
+            type: string
+            enum: [confirmed, pending, failed]
+          message:
+            type: string
+            description: "Order confirmation message"
+
+  # Handoffs back to triage or to refunds
+  handoffs:
+    - name: escalate_to_refunds
+      target_agent: refunds-agent
+      condition: "customer_wants_refund == true"
+      trigger: manual  # Sales agent must explicitly decide to handoff
+
+    - name: return_to_triage
+      target_agent: customer-service-triage
+      condition: "request_type == 'other'"
+      trigger: automatic
+
+  # Observability
+  observability:
+    metrics:
+      enabled: true
+      metrics:
+        - orders_executed
+        - average_order_value
+        - conversion_rate
+
+---
+# Refunds Agent (equivalent to refunds_agent in Swarm)
+apiVersion: ossa/v0.3.6
+kind: Agent
+metadata:
+  name: refunds-agent
+  version: 1.0.0
+  description: "Refunds specialist agent for returns and refunds"
+
+spec:
+  role: |
+    You are an empathetic refunds specialist.
+
+    Your role is to:
+    1. Listen to customer concerns
+    2. Process refund requests
+    3. Explain refund policies clearly
+    4. Resolve issues with care
+
+    Be understanding and process refunds quickly.
+
+  llm:
+    provider: anthropic
+    model: claude-sonnet-4-5
+    temperature: 0.6  # Balanced for empathy and accuracy
+    max_tokens: 2048
+
+  # Capabilities (Swarm's "functions" → OSSA capabilities)
+  # This replaces process_refund() function
+  capabilities:
+    - name: process_refund
+      description: "Process a refund request for an item"
+      input_schema:
+        type: object
+        properties:
+          item_id:
+            type: string
+            description: "The item identifier to refund"
+            pattern: "^[A-Z0-9-]+$"
+          reason:
+            type: string
+            description: "Reason for the refund"
+            minLength: 10
+            maxLength: 500
+        required:
+          - item_id
+          - reason
+      output_schema:
+        type: object
+        properties:
+          refund_id:
+            type: string
+            description: "Generated refund identifier"
+          status:
+            type: string
+            enum: [processed, pending, rejected]
+          amount:
+            type: number
+            description: "Refund amount in USD"
+          message:
+            type: string
+            description: "Refund confirmation message"
+
+  # Handoffs back to sales or triage
+  handoffs:
+    - name: upsell_opportunity
+      target_agent: sales-agent
+      condition: "customer_wants_replacement == true"
+      trigger: automatic
+
+    - name: return_to_triage
+      target_agent: customer-service-triage
+      condition: "issue_resolved == false"
+      trigger: manual
+
+  # Compliance & Governance (NOT available in Swarm)
+  compliance:
+    data_retention:
+      policy: gdpr
+      retention_days: 90
+    audit_logging:
+      enabled: true
+      log_all_interactions: true
+
+  # Observability
+  observability:
+    metrics:
+      enabled: true
+      metrics:
+        - refunds_processed
+        - average_refund_amount
+        - customer_satisfaction_score

package/examples/migrations/swarm-to-ossa/before-handoffs.py

@@ -0,0 +1,373 @@
+"""
+OpenAI Swarm: Advanced Handoff Patterns
+
+This example demonstrates various handoff patterns in OpenAI Swarm:
+1. Conditional handoffs
+2. Bidirectional handoffs (agents can transfer back and forth)
+3. Context preservation across handoffs
+4. Handoff with state changes
+
+Swarm Documentation: https://github.com/openai/swarm
+"""
+
+from swarm import Swarm, Agent
+from typing import Dict, Any, Optional
+
+# Initialize Swarm client
+client = Swarm()
+
+# ============================================================================
+# Shared State (simulated database)
+# ============================================================================
+
+conversation_state = {
+    "order_id": None,
+    "customer_tier": "standard",
+    "issue_resolved": False,
+    "escalation_count": 0
+}
+
+# ============================================================================
+# Transfer Functions with Context
+# ============================================================================
+
+def transfer_to_order_verification():
+    """Transfer to order verification agent to validate order details."""
+    print("[HANDOFF] → Order Verification Agent")
+    return order_verification_agent
+
+
+def transfer_to_payment_processing():
+    """Transfer to payment processing agent after order verification."""
+    print("[HANDOFF] → Payment Processing Agent")
+    return payment_processing_agent
+
+
+def transfer_to_fulfillment():
+    """Transfer to fulfillment agent after payment is processed."""
+    print("[HANDOFF] → Fulfillment Agent")
+    return fulfillment_agent
+
+
+def transfer_to_supervisor():
+    """Escalate to supervisor for complex issues."""
+    global conversation_state
+    conversation_state["escalation_count"] += 1
+    print(f"[ESCALATION] → Supervisor (Escalation #{conversation_state['escalation_count']})")
+    return supervisor_agent
+
+
+def transfer_back_to_sales():
+    """Return customer to sales agent."""
+    print("[HANDOFF] ← Sales Agent")
+    return sales_agent
+
+
+# ============================================================================
+# Conditional Transfer Functions
+# ============================================================================
+
+def conditional_transfer_payment(context_variables: Dict[str, Any]):
+    """
+    Conditionally transfer to payment based on order total.
+    High-value orders go to supervisor for approval.
+    """
+    order_total = context_variables.get("order_total", 0)
+
+    if order_total > 10000:
+        print(f"[CONDITIONAL] High-value order (${order_total}) → Supervisor")
+        return supervisor_agent
+    else:
+        print(f"[CONDITIONAL] Standard order (${order_total}) → Payment Processing")
+        return payment_processing_agent
+
+
+# ============================================================================
+# Agent Functions
+# ============================================================================
+
+def verify_order(order_id: str, customer_id: str) -> str:
+    """Verify order details and customer eligibility."""
+    global conversation_state
+    conversation_state["order_id"] = order_id
+
+    # Simulated verification
+    return f"Order {order_id} verified for customer {customer_id}. Ready for payment."
+
+
+def process_payment(payment_method: str, amount: float) -> str:
+    """Process payment for the order."""
+    # Simulated payment processing
+    return f"Payment of ${amount:.2f} processed via {payment_method}. Transaction ID: TXN-{payment_method}-001"
+
+
+def schedule_fulfillment(order_id: str, delivery_address: str) -> str:
+    """Schedule order fulfillment and delivery."""
+    # Simulated fulfillment
+    return f"Order {order_id} scheduled for delivery to {delivery_address}. Expected delivery: 3-5 business days."
+
+
+def approve_order(order_id: str, approval_note: str) -> str:
+    """Supervisor approves high-value orders."""
+    return f"Order {order_id} approved by supervisor. Note: {approval_note}"
+
+
+# ============================================================================
+# Agent Definitions with Handoff Patterns
+# ============================================================================
+
+# Sales Agent - Entry point
+sales_agent = Agent(
+    name="Sales Agent",
+    instructions="""You are a sales agent helping customers place orders.
+
+When a customer wants to order:
+1. Collect order details (items, quantities)
+2. Calculate order total
+3. Transfer to Order Verification Agent to validate the order
+
+Be friendly and helpful!""",
+    functions=[transfer_to_order_verification]
+)
+
+# Order Verification Agent
+order_verification_agent = Agent(
+    name="Order Verification Agent",
+    instructions="""You verify order details and customer eligibility.
+
+Process:
+1. Verify the order details provided by the customer
+2. Check customer eligibility
+3. Transfer to Payment Processing Agent when verification is complete
+
+If there are issues with the order, transfer back to Sales Agent.""",
+    functions=[verify_order, transfer_to_payment_processing, transfer_back_to_sales]
+)
+
+# Payment Processing Agent
+payment_processing_agent = Agent(
+    name="Payment Processing Agent",
+    instructions="""You handle payment processing for orders.
+
+Process:
+1. Collect payment information
+2. Process the payment securely
+3. Transfer to Fulfillment Agent when payment is successful
+
+For high-value orders (>$10,000), escalate to Supervisor for approval first.
+If payment fails, transfer back to Sales Agent.""",
+    functions=[process_payment, transfer_to_fulfillment, transfer_to_supervisor, transfer_back_to_sales]
+)
+
+# Fulfillment Agent
+fulfillment_agent = Agent(
+    name="Fulfillment Agent",
+    instructions="""You handle order fulfillment and delivery.
+
+Process:
+1. Schedule order fulfillment
+2. Arrange delivery
+3. Provide tracking information
+
+Mark the issue as resolved when delivery is scheduled.""",
+    functions=[schedule_fulfillment, transfer_back_to_sales]
+)
+
+# Supervisor Agent - Handles escalations
+supervisor_agent = Agent(
+    name="Supervisor Agent",
+    instructions="""You are a supervisor handling escalated cases.
+
+Your role:
+1. Review escalated orders (especially high-value ones)
+2. Approve or modify orders as needed
+3. Resolve complex customer issues
+
+You can transfer to any other agent as needed.""",
+    functions=[
+        approve_order,
+        transfer_to_payment_processing,
+        transfer_to_fulfillment,
+        transfer_back_to_sales
+    ]
+)
+
+# ============================================================================
+# Usage Examples
+# ============================================================================
+
+def example_simple_handoff():
+    """Example 1: Simple linear handoff flow."""
+    print("\n" + "=" * 80)
+    print("Example 1: Simple Handoff Flow (Sales → Verification → Payment → Fulfillment)")
+    print("=" * 80)
+
+    messages = [
+        {"role": "user", "content": "I want to order 2 premium widgets for $500 total"}
+    ]
+
+    context_variables = {
+        "customer_id": "CUST123",
+        "customer_tier": "premium",
+        "order_total": 500
+    }
+
+    # Start with sales agent
+    response = client.run(
+        agent=sales_agent,
+        messages=messages,
+        context_variables=context_variables
+    )
+
+    print(f"Current Agent: {response.agent.name}")
+    print(f"Response: {response.messages[-1]['content']}")
+
+    # Continue to verification
+    messages = response.messages
+    messages.append({"role": "user", "content": "Yes, verify the order please"})
+
+    response = client.run(
+        agent=response.agent,
+        messages=messages,
+        context_variables=context_variables
+    )
+
+    print(f"Current Agent: {response.agent.name}")
+    print(f"Response: {response.messages[-1]['content']}")
+
+
+def example_conditional_handoff():
+    """Example 2: Conditional handoff based on order value."""
+    print("\n" + "=" * 80)
+    print("Example 2: Conditional Handoff (High-Value Order → Supervisor)")
+    print("=" * 80)
+
+    messages = [
+        {"role": "user", "content": "I want to place a large enterprise order worth $15,000"}
+    ]
+
+    context_variables = {
+        "customer_id": "CUST456",
+        "customer_tier": "enterprise",
+        "order_total": 15000
+    }
+
+    response = client.run(
+        agent=sales_agent,
+        messages=messages,
+        context_variables=context_variables
+    )
+
+    print(f"Current Agent: {response.agent.name}")
+    print(f"Context: {context_variables}")
+
+
+def example_bidirectional_handoff():
+    """Example 3: Bidirectional handoff (agent can go back)."""
+    print("\n" + "=" * 80)
+    print("Example 3: Bidirectional Handoff (Payment fails → Back to Sales)")
+    print("=" * 80)
+
+    messages = [
+        {"role": "user", "content": "My payment failed, what should I do?"}
+    ]
+
+    context_variables = {
+        "customer_id": "CUST789",
+        "payment_failed": True
+    }
+
+    # Start at payment processing agent
+    response = client.run(
+        agent=payment_processing_agent,
+        messages=messages,
+        context_variables=context_variables
+    )
+
+    print(f"Current Agent: {response.agent.name}")
+    print(f"Response: {response.messages[-1]['content']}")
+
+
+def example_context_preservation():
+    """Example 4: Context preservation across handoffs."""
+    print("\n" + "=" * 80)
+    print("Example 4: Context Preservation Across Handoffs")
+    print("=" * 80)
+
+    initial_context = {
+        "customer_id": "CUST999",
+        "customer_tier": "premium",
+        "order_total": 750,
+        "order_items": ["widget-pro", "widget-plus"],
+        "delivery_address": "123 Main St, City, State 12345"
+    }
+
+    messages = [
+        {"role": "user", "content": "I'm ready to complete my order"}
+    ]
+
+    response = client.run(
+        agent=sales_agent,
+        messages=messages,
+        context_variables=initial_context
+    )
+
+    print(f"Initial Context: {initial_context}")
+    print(f"Current Agent: {response.agent.name}")
+    print("Context is automatically preserved across all handoffs!")
+
+
+# ============================================================================
+# Swarm Handoff Limitations
+# ============================================================================
+
+def demonstrate_limitations():
+    """Demonstrate limitations of Swarm's handoff system."""
+    print("\n" + "=" * 80)
+    print("Swarm Handoff Limitations")
+    print("=" * 80)
+
+    limitations = [
+        "1. NO DECLARATIVE HANDOFF RULES: Handoffs are coded in functions, not declared",
+        "2. NO CONDITIONAL SYNTAX: Must write Python code for conditions",
+        "3. NO HANDOFF OBSERVABILITY: Can't track handoff metrics or patterns",
+        "4. NO HANDOFF POLICIES: Can't enforce rules like 'max 3 handoffs'",
+        "5. MANUAL CONTEXT MANAGEMENT: Must manually pass context_variables",
+        "6. NO HANDOFF APPROVAL: Can't require approval for certain handoffs",
+        "7. NO HANDOFF ROLLBACK: Can't undo a handoff if it was wrong",
+        "8. HARD TO TEST: Handoff logic scattered across functions",
+    ]
+
+    for limitation in limitations:
+        print(f"  ❌ {limitation}")
+
+    print("\n  ✓ OSSA solves ALL of these with declarative handoff configuration!")
+    print("  See after-handoffs.ossa.yaml for the solution.")
+
+
+# ============================================================================
+# Main
+# ============================================================================
+
+if __name__ == "__main__":
+    print("OpenAI Swarm - Advanced Handoff Patterns")
+    print("=" * 80)
+
+    # Run examples
+    example_simple_handoff()
+    example_conditional_handoff()
+    example_bidirectional_handoff()
+    example_context_preservation()
+    demonstrate_limitations()
+
+    print("\n" + "=" * 80)
+    print("Migration to OSSA")
+    print("=" * 80)
+    print("See after-handoffs.ossa.yaml for declarative handoff configuration.")
+    print("\nOSSA Benefits:")
+    print("  ✓ Declarative handoff rules (YAML, not code)")
+    print("  ✓ Conditional handoffs with expression syntax")
+    print("  ✓ Automatic context propagation (no manual passing)")
+    print("  ✓ Handoff observability (metrics, tracing, logging)")
+    print("  ✓ Handoff policies (max handoffs, approval rules)")
+    print("  ✓ Easy testing and validation")