Skip to main content

Developers

For Developers

Build OSSA-compliant agents using your preferred framework and deploy anywhere.

Quick Start

1. Install OSSA CLI

npm install -g @bluefly/openstandardagents

2. Generate Your First Agent

ossa generate chat --name "My Agent" --output agent.ossa.yaml

3. Validate

ossa validate agent.ossa.yaml

4. Deploy

Use your preferred deployment method - OSSA doesn't care!

Development Workflow

Build with Your Framework

OSSA is framework-agnostic. Build agents with:

  • LangChain - Python-based agent framework
  • Anthropic SDK - TypeScript/Python SDK
  • Custom Code - Your own implementation
  • Any Framework - OSSA works with all

Validate with OSSA

Once built, validate against OSSA:

ossa validate my-agent.ossa.yaml

Deploy Anywhere

Deploy to:

  • Kubernetes
  • Docker
  • Serverless (AWS Lambda, Google Cloud Functions)
  • On-premise
  • Your infrastructure

Migration from Existing Frameworks

LangChain → OSSA

See: Migration Guide: LangChain

Anthropic SDK → OSSA

OSSA supports Anthropic's Model Context Protocol (MCP) natively. See the MCP Integration Guide for details on using Claude with OSSA agents.

Custom Framework → OSSA

  1. Map your agent structure to OSSA format
  2. Define tools/capabilities
  3. Configure LLM settings
  4. Add observability
  5. Validate

API Reference

CLI Commands

# Validate agent
ossa validate <path> [--schema <version>] [--verbose]

# Generate agent
ossa generate <type> [--name <name>] [--output <file>]

# Migrate agent
ossa migrate <source> [--target-version <version>]

Programmatic API

import { ValidationService } from '@bluefly/open-standards-scalable-agents/validation';
import { GenerationService } from '@bluefly/open-standards-scalable-agents/generation';

// Validate
const validationService = new ValidationService();
const result = await validationService.validate(manifest, '0.3.0');

// Generate
const generationService = new GenerationService();
const manifest = await generationService.generate(template);

Best Practices

1. Use Descriptive Names

metadata:
  name: customer-support-agent  # Good
  # name: agent1  # Bad

2. Add Comprehensive Descriptions

metadata:
  description: |
    Customer support agent that handles:
    - Product inquiries
    - Order status
    - Returns and refunds

3. Configure Constraints

constraints:
  cost:
    maxTokensPerDay: 100000
    maxCostPerDay: 10.00
  performance:
    maxLatencySeconds: 5.0

4. Enable Observability

observability:
  tracing:
    enabled: true
  metrics:
    enabled: true
  logging:
    level: info

Common Patterns

Pattern 1: Simple Chat Agent

spec:
  role: You are a helpful assistant
  llm:
    provider: openai
    model: gpt-3.5-turbo
  tools: []

Pattern 2: Agent with Tools

spec:
  role: You are a research assistant
  llm:
    provider: openai
    model: gpt-4
  tools:
    - type: http
      name: web_search
      endpoint: https://api.search.com/search

Pattern 3: Multi-Agent Orchestration

See: Integration Patterns

Testing

Validate Before Deployment

ossa validate agent.ossa.yaml --verbose

Test with Examples

# Validate all examples
npm run validate:examples

Troubleshooting

Validation Errors

# Get detailed error messages
ossa validate agent.ossa.yaml --verbose

Common Issues

  1. Missing required fields: Check schema reference
  2. Invalid tool types: Use supported types (http, function, mcp, etc.)
  3. LLM provider not supported: Check provider enum values

Resources