Add OSOP workflow example — agent handoff pattern in portable format

examples/osop/README.md

@@ -0,0 +1,45 @@
+# OSOP Workflow Examples for Swarm
+
+[OSOP](https://github.com/Archie0125/osop-spec) (Open Standard for Orchestration Protocols) is a portable YAML format for describing multi-agent workflows — think OpenAPI, but for agent orchestration.
+
+## What's Here
+
+| File | Description |
+|------|-------------|
+| `swarm-customer-service.osop.yaml` | Customer service with triage agent routing to billing, technical, and sales specialists — with human escalation fallback |
+
+## Why OSOP?
+
+Swarm's lightweight agent handoff pattern is elegant and powerful. OSOP provides a **framework-agnostic way to describe** those handoff patterns so they can be:
+
+- **Documented** — readable YAML that non-developers can understand
+- **Validated** — check workflow structure before running it
+- **Ported** — same workflow definition works across Swarm, AutoGen, CrewAI, etc.
+- **Visualized** — render the workflow as a graph in the [OSOP Editor](https://github.com/Archie0125/osop-editor)
+
+## Quick Start
+
+```bash
+# Validate the workflow
+pip install osop
+osop validate swarm-customer-service.osop.yaml
+
+# Or just read the YAML — it's self-documenting
+cat swarm-customer-service.osop.yaml
+```
+
+## How It Maps to Swarm
+
+| OSOP Concept | Swarm Equivalent |
+|---|---|
+| `node` with `type: agent, subtype: coordinator` | Triage `Agent` with handoff functions |
+| `node` with `type: agent, subtype: worker` | Specialist `Agent` |
+| `edge` with `mode: conditional` | Handoff function return |
+| `edge` with `mode: fallback` | Escalation handoff |
+| `runtime.config.tools` | Agent `functions` list |
+
+## Learn More
+
+- [OSOP Spec](https://github.com/Archie0125/osop-spec) — full specification
+- [OSOP Examples](https://github.com/Archie0125/osop-examples) — 30+ workflow templates
+- [OSOP Editor](https://github.com/Archie0125/osop-editor) — visual workflow editor

examples/osop/swarm-customer-service.osop.yaml

@@ -0,0 +1,93 @@
+# OpenAI Swarm Agent Handoff Pattern in OSOP Format
+osop_version: "1.0"
+id: swarm-customer-service
+name: Swarm Customer Service Handoff
+description: Multi-agent customer service with intelligent routing and handoffs between specialist agents.
+tags: [openai, swarm, handoff, customer-service]
+
+nodes:
+  - id: triage-agent
+    type: agent
+    subtype: coordinator
+    name: Triage Agent
+    purpose: Classify customer intent and route to the appropriate specialist agent.
+    runtime:
+      provider: openai
+      model: gpt-4
+      config:
+        system_prompt: |
+          You are a customer service triage agent. Classify the customer's issue
+          and hand off to the appropriate specialist.
+        temperature: 0.3
+
+  - id: billing-agent
+    type: agent
+    subtype: worker
+    name: Billing Specialist
+    purpose: Handle billing inquiries, refunds, and payment issues.
+    runtime:
+      provider: openai
+      model: gpt-4
+      config:
+        tools: [lookup_invoice, process_refund, update_payment]
+
+  - id: technical-agent
+    type: agent
+    subtype: worker
+    name: Technical Support
+    purpose: Troubleshoot technical issues and guide users through solutions.
+    runtime:
+      provider: openai
+      model: gpt-4
+      config:
+        tools: [check_system_status, run_diagnostics, create_ticket]
+
+  - id: sales-agent
+    type: agent
+    subtype: worker
+    name: Sales Specialist
+    purpose: Handle upgrade requests, new subscriptions, and product questions.
+    runtime:
+      provider: openai
+      model: gpt-4
+      config:
+        tools: [check_pricing, create_quote, process_upgrade]
+
+  - id: escalation
+    type: human
+    name: Human Escalation
+    description: Escalate to human agent when AI cannot resolve the issue.
+
+edges:
+  - from: triage-agent
+    to: billing-agent
+    mode: conditional
+    condition: intent == 'billing'
+    label: Billing issues
+
+  - from: triage-agent
+    to: technical-agent
+    mode: conditional
+    condition: intent == 'technical'
+    label: Technical support
+
+  - from: triage-agent
+    to: sales-agent
+    mode: conditional
+    condition: intent == 'sales'
+    label: Sales inquiries
+
+  - from: billing-agent
+    to: escalation
+    mode: fallback
+    label: Cannot resolve
+
+  - from: technical-agent
+    to: escalation
+    mode: fallback
+    label: Cannot resolve
+
+  - from: sales-agent
+    to: escalation
+    mode: fallback
+    label: Cannot resolve