@bluefly/openstandardagents 0.2.7 → 0.2.8

package/website/content/docs/getting-started/running-agents.md

@@ -1,309 +0,0 @@
----
-title: "Running Agents"
----
-
-# Running Agents
-
-Learn how to run OSSA agents using the CLI.
-
-## Prerequisites
-
-- Node.js 18+
-- npm or yarn
-- API key for your LLM provider
-
-## Installation
-
-```bash
-npm install -g @bluefly/open-standards-scalable-agents
-```
-
-## Quick Start
-
-### 1. Set your API key
-
-```bash
-export OPENAI_API_KEY=sk-...
-```
-
-### 2. Create an agent manifest
-
-```yaml
-# support-agent.ossa.yaml
-apiVersion: ossa/v0.2.x
-kind: Agent
-
-metadata:
-  name: support-agent
-  version: 1.0.0
-  description: Customer support agent
-
-spec:
-  role: |
-    You are a helpful customer support agent.
-    Answer questions about orders and shipping.
-
-  llm:
-    provider: openai
-    model: gpt-4o-mini
-    temperature: 0.7
-```
-
-### 3. Run the agent
-
-```bash
-# Interactive mode
-ossa run support-agent.ossa.yaml
-
-# Single message
-ossa run support-agent.ossa.yaml -m "Help me track my order"
-
-# Verbose (show tool calls)
-ossa run support-agent.ossa.yaml -v
-```
-
-## Command Options
-
-| Option | Description | Default |
-|--------|-------------|---------|
-| `-r, --runtime <runtime>` | Runtime adapter to use | `openai` |
-| `-v, --verbose` | Show detailed output including tool calls | `false` |
-| `-m, --message <message>` | Single message mode (non-interactive) | Interactive REPL |
-| `--no-validate` | Skip manifest validation before running | Validation enabled |
-| `--max-turns <turns>` | Maximum tool call iterations | `10` |
-
-### Detailed Option Descriptions
-
-#### Runtime Selection (`-r, --runtime`)
-
-Choose which runtime adapter to use for executing your agent:
-
-```bash
-# Use OpenAI (default)
-ossa run agent.ossa.yaml --runtime openai
-
-# Short form
-ossa run agent.ossa.yaml -r openai
-```
-
-#### Verbose Mode (`-v, --verbose`)
-
-Enable verbose output to see detailed information about tool calls and execution:
-
-```bash
-ossa run agent.ossa.yaml --verbose
-
-# Shows:
-# - Tool call names and arguments
-# - Tool execution results
-# - Conversation flow
-# - Validation details
-```
-
-#### Single Message Mode (`-m, --message`)
-
-Execute a single message and exit (non-interactive):
-
-```bash
-# Ask a single question
-ossa run agent.ossa.yaml -m "What is the weather today?"
-
-# Long form
-ossa run agent.ossa.yaml --message "Analyze this data"
-```
-
-#### Skip Validation (`--no-validate`)
-
-Skip manifest validation for faster startup (use with caution):
-
-```bash
-ossa run agent.ossa.yaml --no-validate
-```
-
-**Note:** Validation is recommended to catch configuration errors early.
-
-#### Max Turns (`--max-turns`)
-
-Limit the number of tool call iterations to prevent infinite loops:
-
-```bash
-# Allow up to 5 tool call iterations
-ossa run agent.ossa.yaml --max-turns 5
-
-# Default is 10
-ossa run agent.ossa.yaml --max-turns 10
-```
-
-## Supported Runtimes
-
-| Runtime | Status | Provider |
-|---------|--------|----------|
-| openai | Available | OpenAI API |
-| anthropic | Coming Soon | Anthropic Claude |
-| ollama | Coming Soon | Local LLMs |
-| gemini | Coming Soon | Google AI |
-
-## Adding Tools
-
-Define tools in your manifest using the OpenAI extension:
-
-```yaml
-extensions:
-  openai_agents:
-    tools_mapping:
-      - ossa_capability: order_tracking
-        openai_tool_name: get_order_status
-        description: Get order status by ID
-        parameters:
-          type: object
-          properties:
-            order_id:
-              type: string
-              description: The order ID to track
-          required: [order_id]
-```
-
-## Interactive REPL Mode
-
-When you run an agent without the `-m` flag, you enter interactive mode:
-
-```bash
-ossa run agent.ossa.yaml
-
-# Output:
-# ✓ Agent 'my-agent' loaded
-#   Model: gpt-4o-mini
-#   Tools: search, calculate
-#
-# Entering interactive mode. Type "exit" to quit.
-#
-# You: 
-```
-
-In interactive mode:
-- Type your messages and press Enter
-- The agent maintains conversation history
-- Type `exit` or `quit` to end the session
-- Press Ctrl+C to force quit
-
-## Troubleshooting
-
-### API Key Not Set
-
-**Error:** `OPENAI_API_KEY environment variable not set`
-
-**Solution:**
-```bash
-export OPENAI_API_KEY=sk-your-key-here
-```
-
-### Validation Errors
-
-**Error:** `Agent manifest validation failed`
-
-**Solution:** Check your manifest against the schema:
-```bash
-ossa validate agent.ossa.yaml --verbose
-```
-
-### Runtime Not Supported
-
-**Error:** `Runtime 'xyz' not supported yet`
-
-**Solution:** Use the OpenAI runtime (currently the only supported runtime):
-```bash
-ossa run agent.ossa.yaml --runtime openai
-```
-
-### Max Turns Reached
-
-**Error:** `Max turns reached without completion`
-
-**Solution:** Increase the max turns limit:
-```bash
-ossa run agent.ossa.yaml --max-turns 20
-```
-
-## Advanced Usage
-
-### Combining Options
-
-You can combine multiple options:
-
-```bash
-# Verbose single message with custom max turns
-ossa run agent.ossa.yaml -v -m "Complex query" --max-turns 15
-
-# Skip validation in verbose mode
-ossa run agent.ossa.yaml --no-validate --verbose
-```
-
-### Using with Different Models
-
-Specify the model in your manifest:
-
-```yaml
-spec:
-  llm:
-    provider: openai
-    model: gpt-4-turbo
-    temperature: 0.8
-    maxTokens: 2000
-```
-
-Or use the OpenAI extension:
-
-```yaml
-extensions:
-  openai_agents:
-    model: gpt-4-turbo
-    instructions: Custom system prompt
-```
-
-### Environment Variables
-
-The run command respects these environment variables:
-
-- `OPENAI_API_KEY` - Your OpenAI API key (required)
-- `OPENAI_ORG_ID` - Your OpenAI organization ID (optional)
-
-## Examples
-
-### Customer Support Agent
-
-```bash
-# Create the manifest
-cat > support.ossa.yaml << EOF
-apiVersion: ossa/v0.2.4
-kind: Agent
-metadata:
-  name: support-agent
-  version: 1.0.0
-spec:
-  role: You are a helpful customer support agent
-  llm:
-    provider: openai
-    model: gpt-4o-mini
-EOF
-
-# Run interactively
-ossa run support.ossa.yaml
-
-# Or single message
-ossa run support.ossa.yaml -m "How do I reset my password?"
-```
-
-### Code Assistant with Tools
-
-```bash
-# See examples/openai/swarm-agent.ossa.json for a complete example
-ossa run examples/openai/swarm-agent.ossa.json -v
-```
-
-## Next Steps
-
-- [CLI Reference](/docs/cli/run-command) - Complete command reference
-- [OpenAI Adapter](/docs/adapters/openai-adapter) - OpenAI adapter configuration
-- [Manifest Reference](/docs/schema-reference) - Full manifest schema
-- [Framework Extensions](/docs/openapi-extensions) - Extension system
-- [Migration Guides](/docs/migration-guides) - Migrate from other frameworks

package/website/content/docs/getting-started.md

@@ -1,91 +0,0 @@
----
-title: "Getting Started"
----
-
-# Getting Started with OSSA
-
-## What is OSSA?
-
-OSSA (Open Standard for Scalable AI Agents) is a specification standard for AI agents, similar to how OpenAPI standardizes REST APIs.
-
-**OSSA is NOT a framework** - it's a standard that defines the contract.
-
-## Installation
-
-```bash
-npm install -g @bluefly/openstandardagents
-```
-
-## Quick Start
-
-### 1. Initialize a New Agent
-
-```bash
-ossa init my-agent --type worker
-cd .agents/my-agent
-```
-
-### 2. Edit Agent Manifest
-
-Edit `agent.yml`:
-
-```yaml
-ossaVersion: "0.2.6"
-
-agent:
-  id: my-agent
-  name: My Agent
-  version: "1.0.0"
-  role: worker
-  
-  runtime:
-    type: docker
-    
-  capabilities:
-    - name: process_data
-      description: Process incoming data
-      input_schema:
-        type: object
-        properties:
-          data:
-            type: string
-      output_schema:
-        type: object
-        properties:
-          result:
-            type: string
-```
-
-### 3. Validate
-
-```bash
-ossa validate agent.yml
-```
-
-### 4. Deploy
-
-OSSA doesn't dictate deployment. Deploy to YOUR infrastructure:
-- Docker / Kubernetes
-- AWS / GCP / Azure
-- On-premise
-- Serverless
-
-## CLI Commands
-
-- `ossa init <name>` - Initialize new agent project
-- `ossa validate <path>` - Validate against OSSA 1.0 schema
-- `ossa generate <type>` - Generate from template
-- `ossa migrate <source>` - Migrate v0.1.9 → 1.0
-
-## Next Steps
-
-- Review [Examples](Examples/)
-- Read the [Specification](Specification/ossa-1.0.schema.json)
-- Visit the [GitHub Repository](https://github.com/blueflyio/openstandardagents)
-
-## Need More Features?
-
-For production features like GitLab integration, Kubernetes deployment, and monitoring, see:
-
-**[agent-buildkit](https://github.com/blueflyio/openstandardagents)** - Reference implementation with production tooling
-

package/website/content/docs/integrations/aiflow.md

@@ -1,104 +0,0 @@
-# AIFlow Framework Integration with OSSA
-
-## Overview
-
-AIFlow is a Python-based social agent framework that enables personality-driven, emotionally intelligent AI agents for autonomous social media content generation. This integration demonstrates how AIFlow agents are wrapped in OSSA 1.0 manifests for Kubernetes orchestration and deployment through agent-buildkit.
-
-For complete integration analysis, see: [agent-buildkit AIFlow Integration Guide](https://github.com/blueflyio/openstandardagents/wiki/AIFlow-Integration-with-OSSA-BuildKit-and-K-Agent)
-
-## Core Components
-
-### OSSA Manifest
-
-**Location**: [agent-buildkit/examples/aiflow-integration/social-agent-aiflow.ossa.yaml](https://github.com/blueflyio/openstandardagents/blob/development/examples/aiflow-integration/social-agent-aiflow.ossa.yaml)
-
-The manifest defines the agent's identity, runtime configuration, capabilities, and deployment requirements. It conforms to OSSA 1.0 specification.
-
-**Key Manifest Sections**:
-
-- **Agent Identity**: `social-agent-aiflow`, version 1.0.0, role: chat
-- **Runtime**: Docker image `aiflow/agent:1.0.0`, Python 3.12+, resource requirements
-- **Capabilities**: `generate_post`, `generate_response` with defined schemas
-- **Dependencies**: Required integration with `agent-brain` for cognitive functions
-- **Environment**: Required secrets for Anthropic API, Twitter API, Telegram Bot, PostgreSQL
-
-### OpenAPI Specification
-
-**Location**: [agent-buildkit/openapi/aiflow-agent.openapi.yml](https://github.com/blueflyio/openstandardagents/blob/development/openapi/aiflow-agent.openapi.yml)
-
-The OpenAPI 3.1 specification defines the REST API interface for the AIFlow agent, including:
-- FastAPI bridge endpoints for AIFlow Sia runtime
-- Request/response schemas for all capabilities
-- Kubernetes metadata extensions (x-k-agent) for orchestration
-- Health check endpoints and observability metrics
-
-### OSSA Schema
-
-**Location**: [OSSA/spec/v0.2.6/ossa-0.2.6.schema.json](https://github.com/blueflyio/openstandardagents/blob/development/spec/v0.2.6/ossa-0.2.6.schema.json)
-
-JSON Schema definition for OSSA 1.0 manifest validation. All agent manifests must conform to this schema.
-
-## Validation
-
-### OSSA Manifest Validation
-
-Validate the manifest against OSSA 1.0 schema:
-
-```yaml
-ossa validate examples/aiflow-integration/social-agent-aiflow.ossa.yaml
-```
-
-This checks:
-- Schema compliance against OSSA 1.0 specification
-- Required fields and type correctness
-- Capability schema definitions
-- Dependency declarations
-- Environment variable definitions
-
-### OpenAPI Specification Validation
-
-Validate OpenAPI spec with strict mode and K-Agent metadata checks:
-
-```yaml
-buildkit openapi validate --spec openapi/aiflow-agent.openapi.yml --strict
-```
-
-This validates:
-- OpenAPI 3.1 syntax and semantics
-- x-k-agent extension metadata for Kubernetes
-- Endpoint schemas match OSSA capability definitions
-- Health check endpoint compliance
-
-## Deployment
-
-Deploy via agent-buildkit orchestration:
-
-```yaml
-buildkit orchestrate deploy --manifest examples/aiflow-integration/social-agent-aiflow.ossa.yaml
-```
-
-This generates Kubernetes manifests and deploys the agent with:
-- Rolling deployment strategy
-- Horizontal Pod Autoscaling (HPA)
-- Health checks and readiness probes
-- Service account and RBAC configuration
-- ConfigMap for character definitions
-- Persistent volume for memory database
-
-## Integration Architecture
-
-1. **OSSA Manifest** → Defines agent structure and requirements
-2. **OpenAPI Spec** → REST API contract with K8s metadata
-3. **FastAPI Bridge** → Wraps AIFlow Sia runtime in REST API
-4. **BuildKit Deployment** → Generates and applies K8s manifests
-5. **Runtime Orchestration** → Kubernetes manages agent lifecycle
-
-## Resources
-
-- **AIFlow Repository**: https://github.com/AIFlow-agent/AIFlow-Agent
-- **OSSA Project**: [openapi-ai-agents-standard](https://github.com/blueflyio/openstandardagents)
-- **Integration Guide**: [agent-buildkit Wiki](https://github.com/blueflyio/openstandardagents/wiki/AIFlow-Integration-with-OSSA-BuildKit-and-K-Agent)
-- **OSSA Specification Schema**: [OSSA 1.0 Schema](https://github.com/blueflyio/openstandardagents/blob/development/spec/v0.2.6/ossa-0.2.6.schema.json)
-- **Example Manifest**: [social-agent-aiflow.ossa.yaml](https://github.com/blueflyio/openstandardagents/blob/development/examples/aiflow-integration/social-agent-aiflow.ossa.yaml)
-- **OpenAPI Spec**: [aiflow-agent.openapi.yml](https://github.com/blueflyio/openstandardagents/blob/development/openapi/aiflow-agent.openapi.yml)
-

package/website/content/docs/integrations/drupal.md

@@ -1,105 +0,0 @@
----
-title: "Drupal Integration"
----
-
-# Drupal Integration
-
-Integrate OSSA agents with Drupal's LLM Platform.
-
-## Overview
-
-The OSSA Drupal modules provide:
-- Agent management UI
-- Workflow orchestration
-- CrewAI integration
-- Marketplace for agents
-
-## Available Modules
-
-| Module | Description |
-|--------|-------------|
-| ai_agents_ossa | Core OSSA integration |
-| ai_agents_orchestra | Workflow orchestration |
-| ai_agents_crewai | CrewAI framework bridge |
-| ai_agents_marketplace | Agent marketplace |
-| ai_agents_huggingface | HuggingFace models |
-
-## Installation
-
-### Via Composer
-
-```bash
-composer require drupal/ai_agents_ossa
-drush en ai_agents_ossa
-```
-
-### Configuration
-
-1. Go to `/admin/config/ai/agents`
-2. Configure LLM provider credentials
-3. Import OSSA manifests
-
-## Creating Agents in Drupal
-
-### Using the UI
-
-1. Navigate to `/admin/content/agents`
-2. Click "Add Agent"
-3. Upload OSSA manifest or configure inline
-
-### Using Drush
-
-```bash
-# Import agent from manifest
-drush ai:agent:import path/to/agent.ossa.yaml
-
-# List agents
-drush ai:agent:list
-
-# Run agent
-drush ai:agent:run my-agent "Hello"
-```
-
-## Workflow Orchestration
-
-The `ai_agents_orchestra` module enables multi-agent workflows:
-
-```yaml
-# workflow.ossa.yaml
-apiVersion: ossa/v0.2.x
-kind: AgentGraph
-
-metadata:
-  name: support-workflow
-
-spec:
-  agents:
-    - ref: triage-agent
-    - ref: resolver-agent
-  edges:
-    - from: triage-agent
-      to: resolver-agent
-  process: sequential
-```
-
-## ECA Integration
-
-OSSA agents work with Drupal's ECA (Event-Condition-Action):
-
-- Trigger agents on content events
-- Use agent responses in conditions
-- Chain multiple agents
-
-## API Endpoints
-
-| Endpoint | Method | Description |
-|----------|--------|-------------|
-| `/api/agents` | GET | List agents |
-| `/api/agents/{id}/run` | POST | Run agent |
-| `/api/agents/{id}/status` | GET | Agent status |
-
-## Next Steps
-
-- [OSSA Manifest Reference](/docs/schema-reference)
-- [Orchestra Module Docs](https://github.com/blueflyio/drupal/ai_agents_orchestra)
-- [CrewAI Integration](/docs/migration-guides/crewai-to-ossa)