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

npm install -g @bluefly/openstandardagents

Quick Start

1. Set your API key

export OPENAI_API_KEY=sk-...

2. Create an agent manifest

# support-agent.ossa.yaml
apiVersion: ossa/v0.3.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

# 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

Detailed Option Descriptions

Runtime Selection ([object Object])

Choose which runtime adapter to use for executing your agent:

# Use OpenAI (default)
ossa run agent.ossa.yaml --runtime openai

# Short form
ossa run agent.ossa.yaml -r openai

Verbose Mode ([object Object])

Enable verbose output to see detailed information about tool calls and execution:

ossa run agent.ossa.yaml --verbose

# Shows:
# - Tool call names and arguments
# - Tool execution results
# - Conversation flow
# - Validation details

Single Message Mode ([object Object])

Execute a single message and exit (non-interactive):

# 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 ([object Object])

Skip manifest validation for faster startup (use with caution):

ossa run agent.ossa.yaml --no-validate

Note: Validation is recommended to catch configuration errors early.

Max Turns ([object Object])

Limit the number of tool call iterations to prevent infinite loops:

# 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

Note: Multi-runtime support is planned for v0.4.0. Currently, use the OpenAI runtime with any OpenAI-compatible API.

Adding Tools

Define tools in your manifest using the OpenAI extension:

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:

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:

export OPENAI_API_KEY=sk-your-key-here

Validation Errors

Error: Agent manifest validation failed

Solution: Check your manifest against the schema:

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):

ossa run agent.ossa.yaml --runtime openai

Max Turns Reached

Error: Max turns reached without completion

Solution: Increase the max turns limit:

ossa run agent.ossa.yaml --max-turns 20

Advanced Usage

Combining Options

You can combine multiple options:

# 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:

spec:
  llm:
    provider: openai
    model: gpt-4-turbo
    temperature: 0.8
    maxTokens: 2000

Or use the OpenAI extension:

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

# Create the manifest
cat > support.ossa.yaml << EOF
apiVersion: ossa/v0.3.3
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

# See examples/openai/swarm-agent.ossa.json for a complete example
ossa run examples/openai/swarm-agent.ossa.json -v

Next Steps

• CLI Reference - Complete command reference
• OpenAI Adapter - OpenAI adapter configuration
• Manifest Reference - Full manifest schema
• Framework Extensions - Extension system
• Migration Guides - Migrate from other frameworks