@bluefly/openstandardagents 0.2.4 → 0.2.7

package/website/content/docs/core-concepts/project-structure.md

@@ -1,348 +0,0 @@
----
-title: OSSA Project Structure
-description: Understanding the .agents and .agents-workspace folders, and how OSSA organizes agent projects
----
-
-# OSSA Project Structure
-
-Understanding how OSSA organizes your agent projects is essential for effective development. This guide explains the core folders and their purposes.
-
-## Directory Structure Overview
-
-```
-my-ossa-project/
-├── .agents/                    # Agent definitions (version controlled)
-│   ├── my-agent/
-│   │   ├── manifest.json      # Agent configuration
-│   │   ├── prompts/           # Agent prompts
-│   │   └── tools/             # Agent-specific tools
-│   └── another-agent/
-│       └── manifest.json
-├── .agents-workspace/          # Agent runtime workspace (NOT version controlled)
-│   ├── my-agent/
-│   │   ├── context/           # Runtime context
-│   │   ├── memory/            # Agent memory/state
-│   │   └── logs/              # Execution logs
-│   └── another-agent/
-│       └── context/
-├── examples/                   # Example agents and workflows
-└── ossa.yaml                   # Project configuration
-```
-
-## `.agents/` - Agent Definitions
-
-The `.agents/` directory contains your **agent definitions**. This folder **should be version controlled** (committed to git).
-
-### Purpose
-
-- **Declarative agent configuration**: Each agent is defined by a `manifest.json` file
-- **Source of truth**: The canonical definition of what each agent does
-- **Shareable**: Can be exported, migrated, and shared across teams
-- **Platform-agnostic**: Works with any OSSA-compliant runtime
-
-### Structure
-
-Each agent gets its own subdirectory within `.agents/`:
-
-```json
-.agents/
-└── customer-support-agent/
-    ├── manifest.json           # Required: Agent metadata and configuration
-    ├── prompts/
-    │   ├── system.md          # System prompt
-    │   ├── context.md         # Context instructions
-    │   └── examples.md        # Few-shot examples
-    ├── tools/
-    │   ├── search.json        # Tool definition
-    │   └── create-ticket.json # Tool definition
-    └── schema/
-        └── openapi.yaml       # OpenAPI schema if using x-ossa extensions
-```
-
-### manifest.json
-
-The manifest is the core of each agent. It defines:
-
-- **Agent metadata**: Name, description, version
-- **Capabilities**: What the agent can do
-- **Tools**: Which tools the agent has access to
-- **Configuration**: Runtime settings and parameters
-- **Taxonomy**: Agent classification (see below)
-
-Example manifest:
-
-```json
-{
-  "name": "customer-support-agent",
-  "version": "1.0.0",
-  "description": "Handles customer support inquiries",
-  "taxonomy": {
-    "role": "worker",
-    "domain": "customer-service",
-    "capabilities": ["qa", "ticket-creation", "escalation"]
-  },
-  "tools": [
-    {
-      "name": "search_knowledge_base",
-      "type": "function",
-      "source": "./tools/search.json"
-    },
-    {
-      "name": "create_support_ticket",
-      "type": "function",
-      "source": "./tools/create-ticket.json"
-    }
-  ],
-  "prompts": {
-    "system": "./prompts/system.md",
-    "context": "./prompts/context.md"
-  }
-}
-```
-
-## `.agents-workspace/` - Agent Runtime Workspace
-
-The `.agents-workspace/` directory is where agents **run and store runtime data**. This folder **should NOT be version controlled** (add to `.gitignore`).
-
-### Purpose
-
-- **Execution environment**: Where agents execute tasks
-- **State management**: Agent memory, context, and session data
-- **Logs and telemetry**: Runtime logs, metrics, and debugging info
-- **Temporary artifacts**: Generated files, cached data, etc.
-
-### Structure
-
-Each agent gets a workspace directory that mirrors its `.agents/` structure:
-
-```
-.agents-workspace/
-└── customer-support-agent/
-    ├── context/
-    │   ├── session-abc123.json    # Active session context
-    │   └── thread-xyz789.json     # Conversation thread
-    ├── memory/
-    │   ├── short-term.json        # Recent context window
-    │   ├── long-term.db           # Persistent memory (vector store)
-    │   └── preferences.json       # Learned user preferences
-    ├── logs/
-    │   ├── 2025-11-18.log         # Daily logs
-    │   └── metrics.json           # Performance metrics
-    └── artifacts/
-        ├── generated-email.txt    # Generated content
-        └── analysis-report.pdf    # Work products
-```
-
-### Why Separate from `.agents/`?
-
-1. **Clean version control**: Don't pollute git with runtime data
-2. **Security**: Keep sensitive runtime data (API keys, user data) out of version control
-3. **Performance**: Large runtime files don't slow down git operations
-4. **Reproducibility**: Agent definitions in `.agents/` can be reproduced anywhere, but runtime state is environment-specific
-
-### `.gitignore` Recommendation
-
-Always add `.agents-workspace/` to your `.gitignore`:
-
-```gitignore
-# OSSA runtime workspace (never commit this!)
-.agents-workspace/
-
-# Keep agent definitions (DO commit this)
-# .agents/  # <-- NOT ignored, should be committed
-```
-
-## Agent Taxonomy
-
-OSSA uses a **taxonomy system** to classify and organize agents. This helps with:
-
-- **Discovery**: Find agents by role, domain, or capability
-- **Routing**: Direct tasks to appropriate agents
-- **Orchestration**: Compose multi-agent workflows
-- **Governance**: Apply policies based on agent classification
-
-### Taxonomy Structure
-
-```json
-{
-  "taxonomy": {
-    "role": "worker | supervisor | coordinator | specialist",
-    "domain": "customer-service | data-analysis | content-creation | ...",
-    "capabilities": ["capability-1", "capability-2", "..."],
-    "tags": ["optional", "custom", "tags"]
-  }
-}
-```
-
-### Taxonomy Fields
-
-#### `role` (Required)
-
-The agent's primary role in a system:
-
-- **`worker`**: Executes specific tasks (e.g., customer support agent, data fetcher)
-- **`supervisor`**: Manages and coordinates workers (e.g., team lead, orchestrator)
-- **`coordinator`**: Routes tasks between agents (e.g., dispatcher, load balancer)
-- **`specialist`**: Domain expert for complex tasks (e.g., legal advisor, data scientist)
-
-#### `domain` (Required)
-
-The business/functional domain:
-
-- `customer-service`
-- `data-analysis`
-- `content-creation`
-- `software-development`
-- `compliance`
-- `sales`
-- (custom domains allowed)
-
-#### `capabilities` (Optional but Recommended)
-
-Specific capabilities the agent possesses:
-
-```json
-{
-  "capabilities": [
-    "natural-language-understanding",
-    "ticket-creation",
-    "escalation-routing",
-    "sentiment-analysis",
-    "multi-language-support"
-  ]
-}
-```
-
-#### `tags` (Optional)
-
-Freeform tags for additional classification:
-
-```json
-{
-  "tags": ["production", "high-priority", "customer-facing", "v2"]
-}
-```
-
-### Example Taxonomy Usage
-
-**Worker Agent (Customer Support)**:
-```json
-{
-  "taxonomy": {
-    "role": "worker",
-    "domain": "customer-service",
-    "capabilities": ["qa", "ticket-creation", "escalation"],
-    "tags": ["tier-1-support", "email-only"]
-  }
-}
-```
-
-**Supervisor Agent (Support Team Lead)**:
-```json
-{
-  "taxonomy": {
-    "role": "supervisor",
-    "domain": "customer-service",
-    "capabilities": ["task-assignment", "quality-review", "escalation-handling"],
-    "tags": ["tier-2-support", "manager"]
-  }
-}
-```
-
-**Specialist Agent (Data Analyst)**:
-```json
-{
-  "taxonomy": {
-    "role": "specialist",
-    "domain": "data-analysis",
-    "capabilities": ["sql-queries", "data-visualization", "statistical-analysis"],
-    "tags": ["python", "pandas", "power-bi"]
-  }
-}
-```
-
-### Using Taxonomy for Routing
-
-Taxonomy enables intelligent routing in multi-agent systems:
-
-```typescript
-// Find all customer service workers
-const supportAgents = await ossa.findAgents({
-  taxonomy: {
-    role: 'worker',
-    domain: 'customer-service'
-  }
-});
-
-// Find agents with specific capability
-const escalationHandlers = await ossa.findAgents({
-  taxonomy: {
-    capabilities: ['escalation-handling']
-  }
-});
-
-// Route task to appropriate agent
-const agent = await ossa.routeTask(task, {
-  requiredCapabilities: ['sql-queries', 'data-visualization']
-});
-```
-
-## Project Initialization
-
-When you run `osa init`, OSSA creates the proper structure:
-
-```bash
-$ osa init my-project
-✅ Created .agents/ directory (version controlled)
-✅ Created .agents-workspace/ directory (not version controlled)
-✅ Created .gitignore with .agents-workspace/
-✅ Created ossa.yaml project configuration
-```
-
-## Best Practices
-
-### ✅ DO
-
-- **Commit `.agents/`** to version control (git)
-- **Ignore `.agents-workspace/`** in `.gitignore`
-- **Use taxonomy** to classify all agents
-- **Document agent roles** in manifest descriptions
-- **Version your manifests** (semver recommended)
-
-### ❌ DON'T
-
-- **Don't commit `.agents-workspace/`** (contains runtime data, secrets, logs)
-- **Don't hardcode secrets** in agent manifests (use environment variables)
-- **Don't mix runtime state** with agent definitions
-- **Don't skip taxonomy** (makes discovery and routing harder)
-
-## Migration from Other Frameworks
-
-When migrating from other frameworks (LangChain, CrewAI, etc.), use `osa migrate`:
-
-```bash
-# Migrate LangChain agents to OSSA structure
-$ osa migrate --from langchain --input ./langchain-agents --output ./.agents
-
-✅ Created .agents/ with migrated agent definitions
-✅ Created .agents-workspace/ for runtime
-✅ Updated ossa.yaml with agent references
-```
-
-See [Migration Guides](/docs/migration-guides) for framework-specific instructions.
-
-## Summary
-
-| Folder | Purpose | Version Control | Contains |
-|--------|---------|-----------------|----------|
-| `.agents/` | Agent definitions | ✅ YES | Manifests, prompts, tool definitions |
-| `.agents-workspace/` | Agent runtime | ❌ NO | Logs, memory, context, artifacts |
-
-**Key Takeaway**: `.agents/` defines **what** agents do (commit to git). `.agents-workspace/` is **where** they work (never commit).
-
-## Next Steps
-
-- [Create Your First Agent](/docs/getting-started/first-agent)
-- [Agent Manifest Reference](/docs/quick-reference#manifest)
-- [Taxonomy Best Practices](/docs/for-audiences/architects#taxonomy)
-- [Multi-Agent Systems](/docs/examples#multi-agent)

package/website/content/docs/examples/Migration-Guides.md

@@ -1,214 +0,0 @@
----
-title: "Migration Guides"
----
-
-# Migration Guides
-
-Migrate agents from existing frameworks to OSSA format.
-
-## Available Migration Guides
-
-### LangChain → OSSA
-
-**Location**: [examples/migration-guides/from-langchain-to-ossa.yaml](https://github.com/blueflyio/openstandardagents/blob/main/examples/migration-guides/from-langchain-to-ossa.yaml)
-
-**Covers**:
-- Simple LangChain agents
-- Agents with custom tools
-- Multi-agent systems
-- ReAct agents
-
-**Key Differences**:
-- LangChain: Code-based (Python)
-- OSSA: Declarative (YAML/JSON)
-- LangChain: Framework-specific
-- OSSA: Framework-agnostic
-
-### Anthropic SDK → OSSA
-
-**Status**: Coming soon
-
-**Will Cover**:
-- Anthropic SDK agent structure
-- Tool definitions
-- Message handling
-- Migration patterns
-
-### MCP-Only Agents → OSSA
-
-**Status**: Coming soon
-
-**Will Cover**:
-- MCP server integration
-- Tool exposure
-- Protocol bridging
-
-### Custom Framework → OSSA
-
-**General Approach**:
-
-1. **Map Agent Structure**
-   - Identify agent components
-   - Map to OSSA format
-   - Define capabilities
-
-2. **Define Tools**
-   - List available tools
-   - Map to OSSA tool types
-   - Configure endpoints
-
-3. **Configure LLM**
-   - Identify LLM provider
-   - Map model settings
-   - Set parameters
-
-4. **Add Observability**
-   - Configure tracing
-   - Set up metrics
-   - Enable logging
-
-5. **Validate**
-   - Use OSSA CLI
-   - Fix validation errors
-   - Test functionality
-
-## Migration Checklist
-
-### Pre-Migration
-
-- [ ] Inventory existing agents
-- [ ] Identify framework dependencies
-- [ ] Document current capabilities
-- [ ] Plan migration order
-
-### Migration
-
-- [ ] Convert agent structure
-- [ ] Map tools/capabilities
-- [ ] Configure LLM settings
-- [ ] Add observability
-- [ ] Set constraints
-
-### Post-Migration
-
-- [ ] Validate with OSSA CLI
-- [ ] Test functionality
-- [ ] Compare behavior
-- [ ] Update documentation
-- [ ] Deploy and monitor
-
-## Migration Tools
-
-### OSSA CLI
-
-```bash
-# Migrate agent between versions
-ossa migrate agent.yaml --target-version 0.2.2
-```
-
-### Manual Migration
-
-1. Use migration guide examples
-2. Follow step-by-step instructions
-3. Validate at each step
-4. Test thoroughly
-
-## Common Migration Patterns
-
-### Pattern 1: Simple Agent
-
-**Before** (Framework-specific):
-```python
-# Framework code
-agent = create_agent(llm, tools)
-```
-
-**After** (OSSA):
-```yaml
-apiVersion: ossa/v0.2.3
-kind: Agent
-spec:
-  role: Agent description
-  llm: { ... }
-  tools: [ ... ]
-```
-
-### Pattern 2: Agent with Tools
-
-**Before**:
-```python
-tools = [Tool1(), Tool2()]
-agent = create_agent(llm, tools)
-```
-
-**After**:
-```yaml
-spec:
-  tools:
-    - type: function
-      name: tool1
-    - type: http
-      name: tool2
-      endpoint: https://api.example.com
-```
-
-### Pattern 3: Multi-Agent System
-
-**Before**:
-```python
-orchestrator = create_orchestrator()
-worker1 = create_worker()
-worker2 = create_worker()
-```
-
-**After**:
-```yaml
-# orchestrator.ossa.yaml
-spec:
-  tools:
-    - type: http
-      name: invoke_worker
-      endpoint: http://worker:8080/api
-
-# worker.ossa.yaml
-spec:
-  role: Worker agent
-  # ...
-```
-
-## Validation
-
-### Validate Migrated Agent
-
-```bash
-ossa validate migrated-agent.ossa.yaml --verbose
-```
-
-### Compare Behavior
-
-1. Run original agent with test inputs
-2. Run OSSA agent with same inputs
-3. Compare outputs
-4. Verify functionality
-
-## Troubleshooting
-
-### Common Issues
-
-1. **Missing Fields**: Check schema reference
-2. **Invalid Tool Types**: Use supported types
-3. **LLM Provider**: Verify provider support
-4. **Tool Configuration**: Check endpoint/auth config
-
-### Getting Help
-
-- [GitHub Issues](https://github.com/blueflyio/openstandardagents/issues)
-- [Documentation](../Technical/Specification-Deep-Dive)
-- [Examples](../Getting-Started-Examples)
-
-## Related
-
-- [Getting Started](../Getting-Started/Hello-World)
-- [Schema Reference](../Technical/Schema-Reference)
-- [Integration Patterns](Integration-Patterns)
-

package/website/content/docs/examples.md

@@ -1,71 +0,0 @@
----
-title: "Examples"
----
-
-# OSSA OpenAPI Extensions - Examples
-
-Complete working examples demonstrating OSSA OpenAPI extensions.
-
-## Example Specifications
-
-### [Minimal Agent API](./examples/openapi-extensions/minimal-agent-api.openapi.yml)
-
-Basic example showing:
-- Root-level `x-ossa` and `x-agent` extensions
-- Single operation with `x-ossa-capability`, `x-ossa-autonomy`, and `x-ossa-llm`
-- Minimal configuration for a simple greeting agent
-
-**Use Case**: Starting point for new OSSA-compliant agents
-
-### [Worker Agent API](./examples/openapi-extensions/worker-agent-api.openapi.yml)
-
-Comprehensive worker agent example showing:
-- Full `x-ossa-metadata` with governance and compliance
-- All operation-level extensions (capability, autonomy, constraints, tools, llm)
-- Parameter extensions (`X-OSSA-Agent-ID`, `X-OSSA-Version`)
-- Schema extensions (`x-ossa-capability-schema`)
-- Real-world scenario: Kubernetes troubleshooting agent
-
-**Use Case**: Production-ready worker agent with full OSSA compliance
-
-### [Orchestrator Agent API](./examples/openapi-extensions/orchestrator-agent-api.openapi.yml)
-
-Advanced orchestrator agent showing:
-- Multi-agent coordination patterns
-- Workflow execution capabilities
-- Complex input/output schemas
-- Orchestrator-specific autonomy and constraints
-
-**Use Case**: Coordinating multiple specialized agents
-
----
-
-## Validating Examples
-
-All examples can be validated using the OSSA CLI:
-
-```bash
-# Validate a specific example
-ossa validate examples/openapi-extensions/worker-agent-api.openapi.yml --openapi --verbose
-
-# Or validate all examples
-for spec in examples/openapi-extensions/*.openapi.yml; do
-  echo "Validating $spec..."
-  ossa validate "$spec" --openapi
-done
-```
-
----
-
-## Integration with OSSA Manifests
-
-These OpenAPI specs complement OSSA agent manifests (`.ossa.yaml` files):
-
-- **OSSA Manifest** - Declarative agent definition with full configuration
-- **OpenAPI Spec with Extensions** - API interface with agent metadata
-
-Together they provide a complete picture of agent behavior and external interfaces.
-
----
-
-**See Also**: [OpenAPI-Extensions](./OpenAPI-Extensions) · [Quick-Reference](./Quick-Reference)