Skip to content

README-OPENAPI.md

Latest commit

 

History

History
233 lines (185 loc) · 5.02 KB

README-OPENAPI.md

File metadata and controls

233 lines (185 loc) · 5.02 KB
Raw

OpenAPI Agent Implementation

A custom OpenAPI-compatible agent that works with any OpenAI-compatible API endpoint.

Features

  • ✅ Universal Compatibility: Works with any OpenAI-compatible API
  • ✅ Streaming Support: Full support for streaming responses
  • ✅ Tool Calling: Supports function/tool calling
  • ✅ Conversation History: Maintains chat context per conversation
  • ✅ Model Discovery: Auto-discovers available models from endpoint
  • ✅ Authentication: Supports API key authentication (optional)

Supported Endpoints

The OpenAPI agent works with:

Local AI Servers

  • LM Studio - http://localhost:1234
  • Ollama (with OpenAI compatibility) - http://localhost:11434/v1
  • LocalAI - http://localhost:8080
  • vLLM - http://localhost:8000
  • Text Generation WebUI - http://localhost:5000

Cloud Providers

  • Any OpenAI-compatible cloud endpoint
  • Custom deployed models with OpenAI-compatible APIs

Usage

Basic Configuration

import { OpenAPIAgent } from '@computer-use-agent/agent-core'

const config = {
    provider: 'custom',
    model: {
        id: 'llama-3-8b-instruct',
        label: 'Llama 3 8B Instruct',
        provider: 'custom',
    },
    credentials: {
        baseUrl: 'http://localhost:1234',
        apiKey: 'optional-api-key', // Optional
    },
}

const agent = new OpenAPIAgent(config)

Getting Available Models

const models = await agent.getModels()
console.log(models)
// [{ id: 'llama-3-8b-instruct', label: 'llama-3-8b-instruct', provider: 'custom' }, ...]

Sending Messages

const stream = await agent.sendMessage(
    'What is the capital of France?',
    'llama-3-8b-instruct', // optional model ID
    'conversation-1' // optional conversation ID
)

// Process the stream
for await (const chunk of stream) {
    console.log(chunk)
}

Stream Event Types

The agent emits several event types:

// Text delta (incremental content)
event: message
data: {"type":"text-delta","delta":"Hello"}

// Tool execution result
event: tool-result
data: {"type":"tool-result","toolName":"mouse_move","result":{...}}

// Error during tool execution
event: error
data: {"type":"tool-error","error":"Tool execution failed"}

// Completion
event: meta
data: {"type":"completed"}

Examples

LM Studio Setup

  1. Download and install LM Studio
  2. Download a model (e.g., Llama 3)
  3. Start the local server (default: http://localhost:1234)
  4. Configure the agent:
const lmStudioAgent = new OpenAPIAgent({
    provider: 'custom',
    model: {
        id: 'llama-3-8b-instruct',
        label: 'Llama 3 8B Instruct',
        provider: 'custom',
    },
    credentials: {
        baseUrl: 'http://localhost:1234',
    },
})

Ollama Setup

  1. Install Ollama
  2. Pull a model: ollama pull llama3.2
  3. Ollama's OpenAI-compatible endpoint is at /v1
  4. Configure the agent:
const ollamaAgent = new OpenAPIAgent({
    provider: 'custom',
    model: {
        id: 'llama3.2',
        label: 'Llama 3.2',
        provider: 'custom',
    },
    credentials: {
        baseUrl: 'http://localhost:11434/v1',
    },
})

Custom Endpoint with Authentication

const customAgent = new OpenAPIAgent({
    provider: 'custom',
    model: {
        id: 'custom-model-id',
        label: 'Custom Model',
        provider: 'custom',
    },
    credentials: {
        baseUrl: 'https://api.example.com',
        apiKey: 'your-api-key-here',
    },
})

API Specification

The agent expects the endpoint to implement these OpenAI-compatible routes:

List Models

  • Endpoint: GET /v1/models
  • Response:
{
    "data": [
        { "id": "model-id", "object": "model", ... }
    ]
}

Chat Completions (Streaming)

  • Endpoint: POST /v1/chat/completions
  • Request:
{
    "model": "model-id",
    "messages": [
        { "role": "user", "content": "Hello" }
    ],
    "stream": true,
    "tools": [...]
}
  • Response: Server-Sent Events (SSE) stream

Implementation Details

Conversation Management

  • Each conversation is identified by a chatId
  • Conversation history is maintained in memory
  • Messages are automatically added to history

Tool Calling

  • Automatically includes all available tools in requests
  • Executes tools when model requests them
  • Returns tool results in the stream

Error Handling

  • Gracefully falls back to default models on error
  • Provides detailed error messages in stream
  • Handles network failures and timeouts

Testing

Run tests:

pnpm test openapi-agent

Architecture

OpenAPIAgent
├── implements Agent<'custom'>
├── manages conversation history
├── handles streaming responses
├── executes tool calls
└── supports model discovery

Contributing

When adding features:

  1. Maintain OpenAI compatibility
  2. Add tests for new functionality
  3. Update documentation
  4. Ensure streaming works correctly

License

MIT