@bluefly/openstandardagents 0.2.9 → 0.3.0

package/examples/observability/gitlab-ci-template.yml

@@ -0,0 +1,304 @@
+# GitLab CI/CD Template for OSSA Agents with Ultimate Observability
+#
+# Version: 0.3.0
+# Last Updated: 2025-12-11
+# OSSA Spec Version: 0.3.0
+#
+# This template demonstrates how to integrate OSSA agents with GitLab Ultimate's
+# observability features including distributed tracing, error tracking, and
+# performance monitoring.
+#
+# Prerequisites:
+# - GitLab Ultimate subscription
+# - OSSA CLI v0.3.0 or later: npm install -g @bluefly/openstandardagents@0.3.0
+# - GITLAB_OBSERVABILITY_TOKEN set in CI/CD variables
+# - ANTHROPIC_API_KEY or OPENAI_API_KEY set in CI/CD variables
+#
+# Usage:
+#   include:
+#     - remote: 'https://gitlab.com/blueflyio/openstandardagents/-/raw/v0.3.0/examples/observability/gitlab-ci-template.yml'
+#   # Or for local development:
+#   include:
+#     - local: 'examples/observability/gitlab-ci-template.yml'
+
+# Global variables for OpenTelemetry configuration
+variables:
+  # GitLab Observability OTLP endpoint
+  OTEL_EXPORTER_OTLP_ENDPOINT: "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/observability/v1/traces"
+  OTEL_EXPORTER_OTLP_HEADERS: "PRIVATE-TOKEN=${GITLAB_OBSERVABILITY_TOKEN}"
+
+  # Service identification
+  OTEL_SERVICE_NAME: "ossa-agents"
+  OTEL_SERVICE_VERSION: "${CI_COMMIT_SHORT_SHA}"
+
+  # Default resource attributes
+  OTEL_RESOURCE_ATTRIBUTES: "deployment.environment=${CI_ENVIRONMENT_NAME},service.namespace=llm-platform,git.commit.sha=${CI_COMMIT_SHA},git.branch=${CI_COMMIT_REF_NAME}"
+
+  # OpenTelemetry configuration
+  OTEL_TRACES_EXPORTER: "otlp"
+  OTEL_METRICS_EXPORTER: "otlp"
+  OTEL_LOGS_EXPORTER: "otlp"
+  OTEL_EXPORTER_OTLP_PROTOCOL: "http/protobuf"
+
+# Pipeline stages
+stages:
+  - validate
+  - test
+  - deploy
+  - monitor
+
+# Reusable configuration for agent jobs
+.agent-base:
+  image: node:18-alpine
+  before_script:
+    # Install OSSA CLI
+    - npm install -g @bluefly/openstandardagents
+
+    # Verify observability token is set
+    - |
+      if [ -z "$GITLAB_OBSERVABILITY_TOKEN" ]; then
+        echo "Error: GITLAB_OBSERVABILITY_TOKEN is not set"
+        exit 1
+      fi
+
+    # Set agent-specific resource attributes
+    - export OTEL_RESOURCE_ATTRIBUTES="${OTEL_RESOURCE_ATTRIBUTES},ossa.agent.name=${AGENT_NAME},ossa.agent.version=${AGENT_VERSION}"
+
+  # Capture trace data as artifacts
+  artifacts:
+    reports:
+      dotenv: agent-trace.env
+    paths:
+      - agent-trace.env
+      - logs/
+    expire_in: 7 days
+    when: always
+
+# Stage 1: Validation
+validate-agents:
+  stage: validate
+  image: node:18-alpine
+  script:
+    - npm install -g @bluefly/openstandardagents
+    - ossa validate agents/*.yaml
+  artifacts:
+    reports:
+      junit: test-results.xml
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+    - if: '$CI_COMMIT_BRANCH == "main"'
+    - if: '$CI_COMMIT_BRANCH == "development"'
+
+# Stage 2: Testing
+test-code-review-agent:
+  extends: .agent-base
+  stage: test
+  variables:
+    AGENT_NAME: "code-review"
+    AGENT_VERSION: "1.0.0"
+  script:
+    - ossa run agents/code-review-agent.yaml --trace --dry-run
+  environment:
+    name: test
+    deployment_tier: testing
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+
+test-documentation-agent:
+  extends: .agent-base
+  stage: test
+  variables:
+    AGENT_NAME: "documentation"
+    AGENT_VERSION: "1.2.0"
+  script:
+    - ossa run agents/docs-agent.yaml --trace --dry-run
+  environment:
+    name: test
+    deployment_tier: testing
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+
+# Stage 3: Production Deployment
+deploy-code-review-agent:
+  extends: .agent-base
+  stage: deploy
+  variables:
+    AGENT_NAME: "code-review"
+    AGENT_VERSION: "1.0.0"
+  script:
+    # Run agent with full observability
+    - ossa run agents/code-review-agent.yaml --trace --log-level debug
+
+    # Export trace ID for linking
+    - echo "TRACE_ID=$(cat logs/latest-trace-id.txt)" >> agent-trace.env
+    - echo "AGENT_NAME=${AGENT_NAME}" >> agent-trace.env
+  environment:
+    name: production
+    deployment_tier: production
+    url: "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/environments/production"
+  rules:
+    - if: '$CI_COMMIT_BRANCH == "main"'
+      when: manual
+  retry:
+    max: 2
+    when:
+      - api_failure
+      - runner_system_failure
+
+deploy-documentation-agent:
+  extends: .agent-base
+  stage: deploy
+  variables:
+    AGENT_NAME: "documentation"
+    AGENT_VERSION: "1.2.0"
+  script:
+    - ossa run agents/docs-agent.yaml --trace --log-level debug
+    - echo "TRACE_ID=$(cat logs/latest-trace-id.txt)" >> agent-trace.env
+    - echo "AGENT_NAME=${AGENT_NAME}" >> agent-trace.env
+  environment:
+    name: production
+    deployment_tier: production
+  rules:
+    - if: '$CI_COMMIT_BRANCH == "main"'
+      when: manual
+  retry:
+    max: 2
+    when:
+      - api_failure
+      - runner_system_failure
+
+deploy-compliance-agent:
+  extends: .agent-base
+  stage: deploy
+  variables:
+    AGENT_NAME: "compliance"
+    AGENT_VERSION: "2.0.0"
+  script:
+    - ossa run agents/compliance-agent.yaml --trace --log-level debug
+    - echo "TRACE_ID=$(cat logs/latest-trace-id.txt)" >> agent-trace.env
+    - echo "AGENT_NAME=${AGENT_NAME}" >> agent-trace.env
+  environment:
+    name: production
+    deployment_tier: production
+  rules:
+    - if: '$CI_COMMIT_BRANCH == "main"'
+      when: manual
+  retry:
+    max: 2
+    when:
+      - api_failure
+      - runner_system_failure
+
+# Stage 4: Monitoring & Alerting
+monitor-agent-health:
+  stage: monitor
+  image: curlimages/curl:latest
+  script:
+    # Query GitLab observability API for recent errors
+    - |
+      curl --fail-with-body \
+        --header "PRIVATE-TOKEN: ${GITLAB_OBSERVABILITY_TOKEN}" \
+        "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/observability/errors?per_page=10"
+
+    # Check for high error rates (> 5%)
+    - |
+      ERROR_RATE=$(curl -s \
+        --header "PRIVATE-TOKEN: ${GITLAB_OBSERVABILITY_TOKEN}" \
+        "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/observability/metrics?query=agent_error_rate" \
+        | jq -r '.data.result[0].value[1]')
+
+      if [ "$ERROR_RATE" != "null" ] && [ $(echo "$ERROR_RATE > 0.05" | bc) -eq 1 ]; then
+        echo "WARNING: High error rate detected: ${ERROR_RATE}"
+        exit 1
+      fi
+  rules:
+    - if: '$CI_COMMIT_BRANCH == "main"'
+      when: delayed
+      start_in: 5 minutes
+  allow_failure: true
+
+# Optional: Scheduled agent execution
+scheduled-compliance-scan:
+  extends: .agent-base
+  stage: deploy
+  variables:
+    AGENT_NAME: "compliance-scan"
+    AGENT_VERSION: "2.0.0"
+  script:
+    - ossa run agents/compliance-agent.yaml --trace
+  environment:
+    name: production
+    deployment_tier: production
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "schedule"'
+  retry:
+    max: 3
+    when: always
+
+# Optional: Performance testing with load
+performance-test:
+  extends: .agent-base
+  stage: test
+  variables:
+    AGENT_NAME: "performance-test"
+    AGENT_VERSION: "1.0.0"
+  script:
+    # Run multiple instances to test performance
+    - |
+      for i in {1..10}; do
+        ossa run agents/test-agent.yaml --trace &
+      done
+      wait
+
+    # Analyze performance metrics
+    - echo "Performance test completed. Check traces in GitLab Monitor."
+  environment:
+    name: performance-test
+    deployment_tier: testing
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "schedule"'
+    - when: manual
+  allow_failure: true
+
+# Security scanning with OIDC authentication
+security-scan:
+  stage: validate
+  image: node:18-alpine
+  id_tokens:
+    GITLAB_OIDC_TOKEN:
+      aud: https://gitlab.com
+  script:
+    - npm install -g @bluefly/openstandardagents
+
+    # Use OIDC token for authentication
+    - ossa run agents/security-scan-agent.yaml --trace --auth-token $GITLAB_OIDC_TOKEN
+  environment:
+    name: security-scan
+    deployment_tier: testing
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+    - if: '$CI_COMMIT_BRANCH == "main"'
+      when: manual
+
+# Notification job on failure
+notify-on-failure:
+  stage: monitor
+  image: curlimages/curl:latest
+  script:
+    - |
+      curl -X POST "${SLACK_WEBHOOK_URL}" \
+        -H 'Content-Type: application/json' \
+        -d "{
+          \"text\": \"OSSA Agent Pipeline Failed\",
+          \"blocks\": [{
+            \"type\": \"section\",
+            \"text\": {
+              \"type\": \"mrkdwn\",
+              \"text\": \"*Pipeline:* ${CI_PIPELINE_URL}\\n*Branch:* ${CI_COMMIT_REF_NAME}\\n*Commit:* ${CI_COMMIT_SHORT_SHA}\"
+            }
+          }]
+        }"
+  rules:
+    - if: '$CI_COMMIT_BRANCH == "main"'
+      when: on_failure
+  allow_failure: true

package/examples/openai/basic-agent.ossa.yaml

@@ -1,4 +1,4 @@
-apiVersion: ossa/v0.2.9
+apiVersion: ossa/v0.3.0
 kind: Agent
 
 metadata:

package/examples/openai/multi-tool-agent.ossa.json

@@ -1,5 +1,5 @@
 {
-  "apiVersion": "ossa/v0.2.9",
+  "apiVersion": "ossa/v0.3.0",
   "kind": "Agent",
   "metadata": {
     "name": "multi-tool-agent",

package/examples/openai/swarm-agent.ossa.json

@@ -1,5 +1,5 @@
 {
-  "apiVersion": "ossa/v0.2.9",
+  "apiVersion": "ossa/v0.3.0",
   "kind": "Agent",
   "metadata": {
     "name": "swarm-agent",

package/examples/production/document-analyzer-openai.yml

@@ -1,7 +1,7 @@
 # OSSA Agent with OpenAI Bridge Configuration Example
 # Document Analyzer Agent - Proof of Concept
 
-apiVersion: ossa/v0.2.9
+apiVersion: ossa/v0.3.0
 kind: Agent
 metadata:
   name: document-analyzer

package/examples/quickstart/support-agent.ossa.yaml

@@ -1,7 +1,7 @@
 # OSSA Quickstart Example - Customer Support Agent
 # Run with: ossa run examples/quickstart/support-agent.ossa.yaml
 
-apiVersion: ossa/v0.2.9
+apiVersion: ossa/v0.3.0
 kind: Agent
 
 metadata:

package/examples/rag-agent/README.md

@@ -0,0 +1,136 @@
+# RAG Agent Reference Implementation
+
+This example demonstrates a Retrieval-Augmented Generation (RAG) agent using the `@ossa/runtime` SDK.
+
+## Overview
+
+The RAG agent combines semantic search with document retrieval to answer questions based on indexed knowledge. It demonstrates:
+
+- Loading an agent from an OSSA manifest
+- Registering multiple capabilities with handlers
+- Using vector search for document retrieval
+- Generating answers using retrieved context
+
+## Capabilities
+
+### 1. `search`
+Search documents using semantic search.
+
+**Input:**
+```json
+{
+  "query": "string",
+  "limit": 5
+}
+```
+
+**Output:**
+```json
+{
+  "results": [
+    {
+      "id": "doc1",
+      "content": "...",
+      "score": 0.95,
+      "metadata": {}
+    }
+  ]
+}
+```
+
+### 2. `answer`
+Answer questions using the RAG pattern.
+
+**Input:**
+```json
+{
+  "question": "What is OSSA?",
+  "context_limit": 3
+}
+```
+
+**Output:**
+```json
+{
+  "answer": "OSSA is...",
+  "sources": [
+    {
+      "id": "doc1",
+      "content": "...",
+      "score": 0.95
+    }
+  ]
+}
+```
+
+### 3. `index`
+Index new documents into the vector store.
+
+**Input:**
+```json
+{
+  "documents": [
+    {
+      "id": "doc5",
+      "content": "...",
+      "metadata": {}
+    }
+  ]
+}
+```
+
+**Output:**
+```json
+{
+  "indexed": 1
+}
+```
+
+## Usage
+
+```typescript
+import { createRagAgent } from './index.js';
+
+// Create agent
+const agent = await createRagAgent();
+
+// Search documents
+const result = await agent.execute('search', {
+  query: 'OSSA runtime',
+  limit: 5
+});
+
+// Answer question
+const answer = await agent.execute('answer', {
+  question: 'What is OSSA?'
+});
+```
+
+## Running the Example
+
+```bash
+cd examples/rag-agent
+npm install
+npm run build
+node dist/index.js
+```
+
+## Architecture
+
+```
+RAG Agent
+├── Vector Store (semantic search)
+├── Embeddings Service (text → vectors)
+└── LLM (answer generation)
+```
+
+## Production Considerations
+
+This is a reference implementation. For production use:
+
+1. **Replace MockVectorStore** with a real vector database (Qdrant, Pinecone, Weaviate)
+2. **Add embeddings service** for generating vectors from text
+3. **Integrate LLM** for actual answer generation
+4. **Add caching** for frequently accessed documents
+5. **Implement error handling** and retry logic
+6. **Add observability** (metrics, tracing, logging)