@bluefly/openstandardagents 0.2.9 → 0.3.0

package/examples/reference-implementations/curl-scripts/04-a2a-messaging.sh

@@ -0,0 +1,178 @@
+#!/bin/bash
+#
+# OSSA API - Agent-to-Agent Messaging Example
+#
+# Demonstrates A2A messaging capabilities.
+# Requires OSSA_TOKEN environment variable.
+#
+
+set -e
+
+# Configuration
+BASE_URL="${OSSA_BASE_URL:-https://registry.openstandardagents.org/api/v1}"
+TOKEN="${OSSA_TOKEN:-}"
+
+if [ -z "$TOKEN" ]; then
+  echo "❌ Error: OSSA_TOKEN environment variable is required"
+  echo "   Run: export OSSA_TOKEN=ossa_tok_xxx"
+  exit 1
+fi
+
+echo "💬 OSSA API - A2A Messaging Example"
+echo ""
+
+# 1. Send a simple A2A message
+echo "1️⃣  Sending A2A message..."
+MESSAGE=$(cat <<'EOF'
+{
+  "from": {
+    "publisher": "myorg",
+    "name": "my-agent",
+    "version": "1.0.0"
+  },
+  "to": {
+    "publisher": "blueflyio",
+    "name": "security-scanner",
+    "version": "2.0.0"
+  },
+  "type": "request",
+  "capability": "vulnerability-scan",
+  "payload": {
+    "target": "https://example.com",
+    "scan_type": "full",
+    "options": {
+      "check_ssl": true,
+      "check_headers": true
+    }
+  },
+  "metadata": {
+    "correlation_id": "scan-12345",
+    "priority": "high",
+    "ttl": 300
+  }
+}
+EOF
+)
+
+RESPONSE=$(curl -s "${BASE_URL}/messaging/send" \
+  -H "Authorization: Bearer ${TOKEN}" \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json" \
+  -d "${MESSAGE}")
+
+echo "$RESPONSE" | jq '{message_id: .message_id, status: .status, timestamp: .timestamp}'
+
+MESSAGE_ID=$(echo "$RESPONSE" | jq -r '.message_id')
+
+echo ""
+
+# 2. Check message status
+echo "2️⃣  Checking message status..."
+sleep 1
+curl -s "${BASE_URL}/messaging/messages/${MESSAGE_ID}" \
+  -H "Authorization: Bearer ${TOKEN}" \
+  -H "Accept: application/json" \
+  | jq '{message_id: .message_id, status: .status, delivery_attempts: .delivery_attempts}'
+
+echo ""
+
+# 3. Broadcast a message
+echo "3️⃣  Broadcasting message to security agents..."
+BROADCAST=$(cat <<'EOF'
+{
+  "message": {
+    "from": {
+      "publisher": "myorg",
+      "name": "my-agent"
+    },
+    "capability": "security-alert",
+    "payload": {
+      "alert_type": "vulnerability_detected",
+      "severity": "high",
+      "details": {
+        "cve": "CVE-2024-1234",
+        "affected_systems": ["web-server-1", "web-server-2"]
+      }
+    }
+  },
+  "filters": {
+    "domain": "security",
+    "capability": "incident-response"
+  }
+}
+EOF
+)
+
+curl -s "${BASE_URL}/messaging/broadcast" \
+  -H "Authorization: Bearer ${TOKEN}" \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json" \
+  -d "${BROADCAST}" \
+  | jq '{broadcast_id: .broadcast_id, recipients_count: .recipients_count, status: .status}'
+
+echo ""
+
+# 4. Register a webhook
+echo "4️⃣  Registering webhook..."
+WEBHOOK=$(cat <<'EOF'
+{
+  "url": "https://example.com/webhooks/ossa",
+  "events": ["agent.deployed", "agent.error", "message.received"],
+  "filters": {
+    "publisher": "blueflyio"
+  },
+  "headers": {
+    "X-Webhook-Secret": "your-secret-key"
+  },
+  "retry_config": {
+    "max_attempts": 3,
+    "backoff_strategy": "exponential"
+  }
+}
+EOF
+)
+
+WEBHOOK_RESPONSE=$(curl -s "${BASE_URL}/messaging/webhooks" \
+  -H "Authorization: Bearer ${TOKEN}" \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json" \
+  -d "${WEBHOOK}")
+
+echo "$WEBHOOK_RESPONSE" | jq '{id: .id, url: .url, events: .events, active: .active}'
+
+WEBHOOK_ID=$(echo "$WEBHOOK_RESPONSE" | jq -r '.id')
+
+echo ""
+
+# 5. List webhooks
+echo "5️⃣  Listing webhooks..."
+curl -s "${BASE_URL}/messaging/webhooks" \
+  -H "Authorization: Bearer ${TOKEN}" \
+  -H "Accept: application/json" \
+  | jq '.webhooks[] | {id: .id, url: .url, active: .active}'
+
+echo ""
+
+# 6. Subscribe to events
+echo "6️⃣  Subscribing to agent events..."
+SUBSCRIPTION=$(cat <<'EOF'
+{
+  "agent": {
+    "publisher": "blueflyio",
+    "name": "security-scanner"
+  },
+  "events": ["scan.completed", "scan.failed"],
+  "delivery_mode": "polling"
+}
+EOF
+)
+
+curl -s "${BASE_URL}/messaging/subscriptions" \
+  -H "Authorization: Bearer ${TOKEN}" \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json" \
+  -d "${SUBSCRIPTION}" \
+  | jq '{subscription_id: .subscription_id, status: .status, created_at: .created_at}'
+
+echo ""
+echo "✅ A2A messaging examples completed!"

package/examples/reference-implementations/curl-scripts/05-discovery.sh

@@ -0,0 +1,98 @@
+#!/bin/bash
+#
+# OSSA API - Discovery Example
+#
+# Demonstrates agent discovery by taxonomy, capabilities, and compliance.
+#
+
+set -e
+
+# Configuration
+BASE_URL="${OSSA_BASE_URL:-https://registry.openstandardagents.org/api/v1}"
+
+echo "🔎 OSSA API - Discovery Example"
+echo ""
+
+# 1. List taxonomies
+echo "1️⃣  List available taxonomies..."
+curl -s "${BASE_URL}/specification/taxonomies" \
+  -H "Accept: application/json" \
+  | jq '.taxonomies[] | {domain: .domain, subdomains: (.subdomains | keys)}'
+
+echo ""
+
+# 2. List capabilities
+echo "2️⃣  List capabilities in security domain..."
+curl -s "${BASE_URL}/specification/capabilities?domain=security" \
+  -H "Accept: application/json" \
+  | jq '.capabilities[] | {name: .name, description: .description, domain: .domain}'
+
+echo ""
+
+# 3. Get capability details
+echo "3️⃣  Get capability details: vulnerability-detection..."
+curl -s "${BASE_URL}/specification/capabilities/vulnerability-detection" \
+  -H "Accept: application/json" \
+  | jq '{name: .name, description: .description, example_agents: .example_agents}'
+
+echo ""
+
+# 4. List compliance profiles
+echo "4️⃣  List compliance profiles..."
+curl -s "${BASE_URL}/specification/compliance" \
+  -H "Accept: application/json" \
+  | jq '.profiles[] | {id: .id, name: .name, agent_count: .agent_count}'
+
+echo ""
+
+# 5. Discover agents by taxonomy
+echo "5️⃣  Discover agents: domain=security, subdomain=vulnerability..."
+curl -s "${BASE_URL}/agents/discover/taxonomy?domain=security&subdomain=vulnerability" \
+  -H "Accept: application/json" \
+  | jq '{taxonomy: .taxonomy, total: .total, agents: .agents[] | {publisher: .publisher, name: .name, rating: .rating}}'
+
+echo ""
+
+# 6. Discover by compliance
+echo "6️⃣  Discover agents with FedRAMP and HIPAA compliance..."
+curl -s "${BASE_URL}/agents/discover/compliance?profiles=fedramp-moderate,hipaa" \
+  -H "Accept: application/json" \
+  | jq '{
+      compliance_profiles: .compliance_profiles,
+      total: .total,
+      agents: .agents[] | {name: .name, compliance_profiles: .compliance_profiles}
+    }'
+
+echo ""
+
+# 7. Get recommendations
+echo "7️⃣  Get agent recommendations..."
+RECOMMENDATION_REQUEST=$(cat <<'EOF'
+{
+  "use_case": "I need to scan my web application for security vulnerabilities",
+  "requirements": {
+    "compliance": ["fedramp-moderate"],
+    "budget": "$100/month",
+    "performance": "high"
+  },
+  "preferences": {
+    "verified_only": true,
+    "min_rating": 4.0
+  }
+}
+EOF
+)
+
+curl -s "${BASE_URL}/agents/recommend" \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json" \
+  -d "${RECOMMENDATION_REQUEST}" \
+  | jq '.recommendations[] | {
+      agent: .agent,
+      score: .score,
+      reasoning: .reasoning,
+      compliance_match: .compliance_match
+    }'
+
+echo ""
+echo "✅ Discovery examples completed!"

package/examples/reference-implementations/curl-scripts/README.md

@@ -0,0 +1,277 @@
+# OSSA cURL Scripts
+
+Shell script examples demonstrating OSSA API usage with cURL and jq.
+
+## Features
+
+- **Simple Shell Scripts**: Easy-to-understand bash scripts
+- **Complete Coverage**: Examples for all major API operations
+- **Production Ready**: Error handling and environment variable support
+- **jq Integration**: JSON parsing and formatting with jq
+
+## Prerequisites
+
+- bash
+- curl
+- jq (for JSON parsing)
+
+Install jq:
+
+```bash
+# macOS
+brew install jq
+
+# Ubuntu/Debian
+sudo apt-get install jq
+
+# RHEL/CentOS
+sudo yum install jq
+```
+
+## Configuration
+
+Set environment variables:
+
+```bash
+# Required for authenticated operations
+export OSSA_TOKEN=ossa_tok_xxx
+
+# Optional: Override base URL
+export OSSA_BASE_URL=https://registry.openstandardagents.org/api/v1
+```
+
+## Examples
+
+### 1. Search Agents
+
+Search and filter agents using various criteria:
+
+```bash
+./01-search-agents.sh
+```
+
+Features:
+- Search by domain (security, infrastructure, etc.)
+- Full-text search
+- Filter by capability
+- Filter by verified publishers
+- Filter by compliance profile
+- Pagination
+- Combined filters
+
+### 2. Get Agent Details
+
+Retrieve detailed information about agents:
+
+```bash
+# Use default agent
+./02-get-agent-details.sh
+
+# Specify publisher and agent name
+./02-get-agent-details.sh blueflyio security-scanner
+```
+
+Features:
+- Get latest version details
+- List all versions
+- Get specific version
+- Get dependencies
+- Get download statistics
+
+### 3. Publish Agent
+
+Publish an agent to the registry (requires authentication):
+
+```bash
+export OSSA_TOKEN=ossa_tok_xxx
+./03-publish-agent.sh
+```
+
+Features:
+- Complete manifest submission
+- Package information
+- Documentation URLs
+- License and keywords
+- Verification status
+
+### 4. A2A Messaging
+
+Agent-to-agent messaging operations:
+
+```bash
+export OSSA_TOKEN=ossa_tok_xxx
+./04-a2a-messaging.sh
+```
+
+Features:
+- Send A2A messages
+- Check message status
+- Broadcast messages
+- Register webhooks
+- List webhooks
+- Subscribe to events
+
+### 5. Discovery
+
+Discover agents by taxonomy, capabilities, and compliance:
+
+```bash
+./05-discovery.sh
+```
+
+Features:
+- List taxonomies
+- List capabilities
+- Get capability details
+- List compliance profiles
+- Discover by taxonomy
+- Discover by compliance
+- Get recommendations
+
+## API Endpoints
+
+All scripts use the OSSA Registry API:
+
+```
+Base URL: https://registry.openstandardagents.org/api/v1
+```
+
+### Public Endpoints (No Auth)
+
+- `GET /agents` - Search agents
+- `GET /agents/{publisher}/{name}` - Get agent details
+- `GET /agents/{publisher}/{name}/versions` - List versions
+- `GET /specification/taxonomies` - List taxonomies
+- `GET /specification/capabilities` - List capabilities
+- `GET /specification/compliance` - List compliance profiles
+
+### Authenticated Endpoints
+
+- `POST /agents` - Publish agent
+- `DELETE /agents/{publisher}/{name}/{version}` - Unpublish
+- `POST /agents/{publisher}/{name}/{version}/deprecate` - Deprecate
+- `POST /messaging/send` - Send A2A message
+- `POST /messaging/broadcast` - Broadcast message
+- `POST /messaging/webhooks` - Register webhook
+- `POST /messaging/subscriptions` - Subscribe to events
+
+## Authentication
+
+OSSA API supports Bearer token authentication:
+
+```bash
+curl -H "Authorization: Bearer ${OSSA_TOKEN}" \
+  https://registry.openstandardagents.org/api/v1/agents
+```
+
+Get a token:
+1. Visit https://registry.openstandardagents.org
+2. Sign in with your account
+3. Navigate to Settings > API Tokens
+4. Generate a new token
+
+## Response Format
+
+All responses are JSON. Use jq for parsing:
+
+```bash
+# Get agent names only
+curl -s "${BASE_URL}/agents?domain=security" | jq '.agents[].name'
+
+# Pretty print
+curl -s "${BASE_URL}/agents" | jq '.'
+
+# Extract specific fields
+curl -s "${BASE_URL}/agents" | jq '.agents[] | {name, version, rating}'
+```
+
+## Error Handling
+
+Scripts include error handling:
+
+```bash
+RESPONSE=$(curl -s -w "\n%{http_code}" "${URL}")
+HTTP_CODE=$(echo "$RESPONSE" | tail -n1)
+BODY=$(echo "$RESPONSE" | head -n-1)
+
+if [ "$HTTP_CODE" -eq 200 ]; then
+  echo "Success!"
+  echo "$BODY" | jq '.'
+else
+  echo "Error: HTTP $HTTP_CODE"
+  echo "$BODY" | jq '.'
+  exit 1
+fi
+```
+
+## Rate Limiting
+
+The API includes rate limits:
+- Authenticated: 1000 requests/hour
+- Unauthenticated: 100 requests/hour
+
+Check rate limit headers:
+
+```bash
+curl -I "${BASE_URL}/agents" | grep -i ratelimit
+# X-RateLimit-Limit: 1000
+# X-RateLimit-Remaining: 999
+# X-RateLimit-Reset: 1234567890
+```
+
+## Common Parameters
+
+### Search Parameters
+
+- `q` - Full-text search query
+- `domain` - Filter by domain
+- `capability` - Filter by capability
+- `publisher` - Filter by publisher
+- `verified` - Only verified publishers (true/false)
+- `min_rating` - Minimum rating (1-5)
+- `sort` - Sort order (downloads, rating, updated, created, relevance)
+- `limit` - Results per page (max 100)
+- `offset` - Pagination offset
+
+### Message Parameters
+
+- `from` - Sender information
+- `to` - Recipient information
+- `type` - Message type (request, response, event, broadcast)
+- `capability` - Target capability
+- `payload` - Message payload (JSON object)
+- `metadata` - Message metadata (correlation_id, priority, ttl)
+
+## Troubleshooting
+
+**jq: command not found**
+```bash
+# Install jq (see Prerequisites section)
+brew install jq  # macOS
+```
+
+**401 Unauthorized**
+```bash
+# Check token is set
+echo $OSSA_TOKEN
+
+# Ensure token is valid
+export OSSA_TOKEN=ossa_tok_xxx
+```
+
+**429 Rate Limited**
+```bash
+# Wait for rate limit reset
+# Check X-RateLimit-Reset header for reset time
+```
+
+## Resources
+
+- [OSSA Documentation](https://docs.openstandardagents.org)
+- [API Reference](https://registry.openstandardagents.org/docs)
+- [cURL Documentation](https://curl.se/docs/)
+- [jq Manual](https://stedolan.github.io/jq/manual/)
+
+## License
+
+Apache-2.0