OpenAI Adapter

The OpenAI adapter enables OSSA agents to run using OpenAI's function calling API, supporting GPT-4, GPT-3.5, and other OpenAI models.

Overview

The OpenAI adapter:

Converts OSSA manifests to OpenAI function calling format
Manages conversation history and context
Executes tool calls with custom handlers
Supports OpenAI-specific extensions
Handles streaming and token limits

Quick Start

1. Set API Key

export OPENAI_API_KEY=sk-your-key-here

2. Create Agent Manifest

apiVersion: ossa/v0.3.3
kind: Agent
metadata:
  name: my-agent
  version: 1.0.0
spec:
  role: You are a helpful assistant
  llm:
    provider: openai
    model: gpt-4o-mini

3. Run Agent

ossa run my-agent.ossa.yaml

Configuration

Model Selection

The adapter selects the model in this priority order:

OpenAI Extension (highest priority)
LLM Config
Default (gpt-4o-mini)

Using OpenAI Extension

extensions:
  openai_agents:
    model: gpt-4-turbo

Using LLM Config

spec:
  llm:
    provider: openai
    model: gpt-3.5-turbo

Default Model

If no model is specified, the adapter uses gpt-4o-mini.

System Prompt

The adapter selects the system prompt in this priority order:

OpenAI Extension Instructions (highest priority)
Spec Role

Using OpenAI Extension

extensions:
  openai_agents:
    instructions: |
      You are a specialized customer support agent.
      Always be polite and helpful.
      Escalate complex issues to human agents.

Using Spec Role

spec:
  role: You are a helpful assistant

LLM Parameters

Configure temperature, max tokens, and other parameters:

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

Parameters:

temperature (0.0-2.0): Controls randomness. Default: 0.7
maxTokens: Maximum tokens in response. Default: model's maximum

Tools and Function Calling

Tool Mapping

The OpenAI adapter converts OSSA tools to OpenAI function calling format using the tools_mapping extension.

Basic Tool Mapping

extensions:
  openai_agents:
    tools_mapping:
      - ossa_capability: search
        openai_tool_name: web_search
        description: Search the web for information
        parameters:
          type: object
          properties:
            query:
              type: string
              description: The search query
          required: [query]

Multiple Tools

extensions:
  openai_agents:
    tools_mapping:
      - ossa_capability: search
        openai_tool_name: web_search
        description: Search the web
        parameters:
          type: object
          properties:
            query:
              type: string
          required: [query]
      
      - ossa_capability: calculate
        openai_tool_name: calculator
        description: Perform mathematical calculations
        parameters:
          type: object
          properties:
            expression:
              type: string
              description: Mathematical expression to evaluate
          required: [expression]
      
      - ossa_capability: get_weather
        openai_tool_name: weather_api
        description: Get current weather for a location
        parameters:
          type: object
          properties:
            location:
              type: string
              description: City name or coordinates
            units:
              type: string
              enum: [celsius, fahrenheit]
              default: celsius
          required: [location]

Tool Parameters

Tool parameters follow the JSON Schema format:

parameters:
  type: object
  properties:
    param_name:
      type: string | number | boolean | array | object
      description: Parameter description
      enum: [value1, value2]  # Optional: restrict to specific values
      default: default_value   # Optional: default value
  required: [param1, param2]  # Optional: required parameters

Supported types:

string - Text values
number - Numeric values (integers or floats)
boolean - True/false values
array - Lists of values
object - Nested objects

Tool Naming

If openai_tool_name is not provided, the adapter uses ossa_capability as the tool name:

extensions:
  openai_agents:
    tools_mapping:
      - ossa_capability: my_tool
        # openai_tool_name defaults to "my_tool"
        description: My tool
        parameters:
          type: object
          properties: {}

Spec Tools

The adapter also supports tools defined in spec.tools:

spec:
  tools:
    - type: function
      name: simple_tool

These are converted to OpenAI functions with default parameters.

Conversation Management

Initialization

The adapter initializes conversations with a system message:

adapter.initialize();

This sets up the conversation with:

System message (from instructions or role)
Empty message history

Message History

The adapter maintains full conversation history:

[System] You are a helpful assistant
[User] What is the weather?
[Assistant] [Tool Call: get_weather]
[Tool] Weather: Sunny, 72°F
[Assistant] The weather is sunny and 72°F
[User] What about tomorrow?
[Assistant] ...

Chat Method

Send messages and get responses:

const response = await adapter.chat('Hello', {
  verbose: true,
  maxTurns: 10
});

Options:

verbose (boolean): Show tool calls and execution details
maxTurns (number): Maximum tool call iterations (default: 10)

Tool Execution

Default Behavior

Without custom handlers, tools return placeholder responses:

Tool 'tool_name' executed with args: {"param": "value"}

Custom Tool Handlers

import { OpenAIAdapter } from '@bluefly/openstandardagents';

const adapter = new OpenAIAdapter(manifest);
adapter.initialize();

// Register handler
adapter.registerToolHandler('web_search', async (args) => {
  const { query } = args;
  // Perform actual search
  const results = await searchWeb(query);
  return JSON.stringify(results);
});

// Use the agent
const response = await adapter.chat('Search for OSSA');

Error Handling

Tool execution errors are caught and returned to the agent:

adapter.registerToolHandler('risky_tool', async (args) => {
  throw new Error('Something went wrong');
});

// Agent receives: "Error executing risky_tool: Something went wrong"

Unknown Tools

If a tool is called but not registered:

Error: Tool 'unknown_tool' not found

Advanced Features

Guardrails

Configure safety limits and constraints:

extensions:
  openai_agents:
    guardrails:
      enabled: true
      max_tool_calls: 10
      timeout_seconds: 300

Note: Guardrails are defined in the manifest but enforcement depends on the implementation.

Memory Configuration

Configure conversation memory:

extensions:
  openai_agents:
    memory:
      enabled: true
      type: session
      max_messages: 50

Memory types:

session - In-memory for the current session
persistent - Saved across sessions (requires implementation)

Max Turns

Prevent infinite loops with max turns:

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

When max turns is reached:

Max turns reached without completion

API Integration

OpenAI SDK

The adapter uses the official OpenAI SDK:

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY
});

API Calls

Each chat interaction makes one or more API calls:

Initial call - Send user message
Tool calls - If the model requests tools
Follow-up call - Send tool results back
Repeat - Until response or max turns

Rate Limits

Be aware of OpenAI rate limits:

Requests per minute (RPM)
Tokens per minute (TPM)
Tokens per day (TPD)

Use --max-turns to limit API calls.

Examples

Basic Chat Agent

apiVersion: ossa/v0.3.3
kind: Agent
metadata:
  name: chat-agent
  version: 1.0.0
spec:
  role: You are a friendly chat assistant
  llm:
    provider: openai
    model: gpt-4o-mini
    temperature: 0.9

Customer Support Agent

apiVersion: ossa/v0.3.3
kind: Agent
metadata:
  name: support-agent
  version: 1.0.0
spec:
  role: You are a customer support agent
  llm:
    provider: openai
    model: gpt-4-turbo
    temperature: 0.7
extensions:
  openai_agents:
    instructions: |
      You are a customer support agent for TechCorp.
      Help customers with orders, shipping, and returns.
      Always be polite and professional.
    tools_mapping:
      - ossa_capability: order_lookup
        openai_tool_name: get_order
        description: Look up order by ID
        parameters:
          type: object
          properties:
            order_id:
              type: string
          required: [order_id]
      
      - ossa_capability: shipping_status
        openai_tool_name: get_shipping
        description: Get shipping status
        parameters:
          type: object
          properties:
            tracking_number:
              type: string
          required: [tracking_number]

Code Assistant

apiVersion: ossa/v0.3.3
kind: Agent
metadata:
  name: code-assistant
  version: 1.0.0
spec:
  role: You are a helpful coding assistant
  llm:
    provider: openai
    model: gpt-4-turbo
    temperature: 0.3
    maxTokens: 4000
extensions:
  openai_agents:
    model: gpt-4-turbo
    instructions: |
      You are an expert programming assistant.
      Help users write, debug, and optimize code.
      Provide clear explanations and examples.
    tools_mapping:
      - ossa_capability: execute_code
        openai_tool_name: run_python
        description: Execute Python code safely
        parameters:
          type: object
          properties:
            code:
              type: string
              description: Python code to execute
          required: [code]
      
      - ossa_capability: search_docs
        openai_tool_name: search_documentation
        description: Search programming documentation
        parameters:
          type: object
          properties:
            query:
              type: string
            language:
              type: string
              enum: [python, javascript, typescript, java]
          required: [query, language]

Multi-Tool Agent

apiVersion: ossa/v0.3.3
kind: Agent
metadata:
  name: multi-tool-agent
  version: 1.0.0
spec:
  role: You are a versatile assistant with multiple capabilities
  llm:
    provider: openai
    model: gpt-4o
extensions:
  openai_agents:
    model: gpt-4o
    tools_mapping:
      - ossa_capability: web_search
        description: Search the web
        parameters:
          type: object
          properties:
            query:
              type: string
          required: [query]
      
      - ossa_capability: calculator
        description: Perform calculations
        parameters:
          type: object
          properties:
            expression:
              type: string
          required: [expression]
      
      - ossa_capability: weather
        description: Get weather information
        parameters:
          type: object
          properties:
            location:
              type: string
          required: [location]
      
      - ossa_capability: translate
        description: Translate text
        parameters:
          type: object
          properties:
            text:
              type: string
            target_language:
              type: string
          required: [text, target_language]
    guardrails:
      enabled: true
      max_tool_calls: 15
      timeout_seconds: 300
    memory:
      enabled: true
      type: session
      max_messages: 100

Troubleshooting

API Key Issues

Problem: OPENAI_API_KEY environment variable not set

Solution:

export OPENAI_API_KEY=sk-your-key-here

Invalid API Key

Problem: 401 Unauthorized

Solution: Check that your API key is valid and has not expired.

Rate Limit Errors

Problem: 429 Too Many Requests

Solution:

Wait before retrying
Reduce --max-turns
Use a lower-tier model
Upgrade your OpenAI plan

Model Not Found

Problem: 404 Model not found

Solution: Check that the model name is correct:

gpt-4o-mini ✓
gpt-4-turbo ✓
gpt-3.5-turbo ✓
gpt-4 ✓

Tool Call Loops

Problem: Max turns reached without completion

Solution:

Increase --max-turns
Improve tool descriptions
Add better system instructions
Check tool handler logic

Token Limit Exceeded

Problem: This model's maximum context length is...

Solution:

Reduce maxTokens
Use a model with larger context
Implement conversation summarization
Clear conversation history

Best Practices

1. Model Selection

Use gpt-4o-mini for simple tasks (faster, cheaper)
Use gpt-4-turbo for complex reasoning
Use gpt-4o for balanced performance

2. Temperature Settings

0.0-0.3 - Deterministic, factual responses
0.4-0.7 - Balanced creativity and consistency
0.8-1.0 - Creative, varied responses
1.0+ - Highly creative (use with caution)

3. Tool Design

Keep tool descriptions clear and concise
Use descriptive parameter names
Provide parameter descriptions
Mark required parameters
Use enums for restricted values

4. Error Handling

Always handle tool execution errors
Return meaningful error messages
Log errors for debugging
Implement retry logic for transient failures

5. Cost Optimization

Use gpt-4o-mini when possible
Set reasonable maxTokens limits
Limit max_tool_calls in guardrails
Monitor API usage

6. Security

Never expose API keys in code
Use environment variables
Validate tool inputs
Sanitize tool outputs
Implement rate limiting

OpenAI Adapter

OpenAI Adapter

Overview

Quick Start

1. Set API Key

2. Create Agent Manifest

3. Run Agent

Configuration

Model Selection

Using OpenAI Extension

Using LLM Config

Default Model

System Prompt

Using OpenAI Extension

Using Spec Role

LLM Parameters

Tools and Function Calling

Tool Mapping

Basic Tool Mapping

Multiple Tools

Tool Parameters

Tool Naming

Spec Tools

Conversation Management

Initialization

Message History

Chat Method

Tool Execution

Default Behavior

Custom Tool Handlers

Error Handling

Unknown Tools

Advanced Features

Guardrails

Memory Configuration

Max Turns

API Integration

OpenAI SDK

API Calls

Rate Limits

Examples

Basic Chat Agent

Customer Support Agent

Code Assistant

Multi-Tool Agent

Troubleshooting

API Key Issues

Invalid API Key

Rate Limit Errors

Model Not Found

Tool Call Loops

Token Limit Exceeded

Best Practices

1. Model Selection

2. Temperature Settings

3. Tool Design

4. Error Handling

5. Cost Optimization

6. Security

See Also