OpenAI Workflows Skill

Execute OpenAI hosted agents and workflows seamlessly within your WebAgents, with real-time streaming and automatic cost tracking.

[!NOTE] TypeScript availability: The dedicated OpenAIAgentBuilderSkill is currently Python-only. The TypeScript SDK exposes OpenAI as a regular LLM provider via webagents/skills/llm (OpenAILLMSkill), which covers the chat.completions and responses APIs but not OpenAI's hosted Workflows / Agent Builder runtime. Track parity at internal/python-typescript-parity.md.

Overview

The OpenAI Agent Builder skill allows you to integrate OpenAI's hosted workflows as handoff handlers, enabling you to leverage OpenAI's agent building capabilities while maintaining full integration with the WebAgents platform.

Key Features:

🌊 Real-time streaming - Word-by-word response streaming

💰 Automatic cost tracking - Token usage logged for accurate billing

🔄 Session support - Multi-turn conversations with memory

🔌 Seamless handoffs - Integrates as a standard handoff handler

📊 Tracing enabled - Built-in debugging and monitoring

🧠 Thinking support - Detects and wraps reasoning model thinking in <think> tags

Installation

The OpenAI Workflows skill is included in the ecosystem skills package:

// Coming soon — track at https://github.com/robutlerai/webagents/issues
// For now, use OpenAI as a standard LLM provider:
import { OpenAILLMSkill } from 'webagents/skills/llm';

Configuration

Credential Sources (in order of precedence)

KV Storage - Credentials stored via setup form or update_openai_credentials tool (when KV skill available)

Config - Passed in skill configuration dictionary

Environment - OPENAI_API_KEY environment variable (.env file)

Parameters

workflow_id: OpenAI workflow ID (optional if using KV storage)

api_key: OpenAI API key (optional, defaults to KV storage or OPENAI_API_KEY env var)

api_base: OpenAI API base URL (default: https://api.openai.com/v1)

version: Workflow version (default: None = latest)

[!TIP] Don't specify a version unless required. When omitted, the workflow uses its default version, which automatically uses the latest stable version, benefits from workflow improvements, and reduces maintenance burden. Only specify version if you need a specific workflow structure or the default doesn't work.

Multitenancy Support

The OpenAI Workflows skill supports per-agent-owner credential storage when a KV skill is available. This allows agent owners to configure their own OpenAI credentials without requiring server-wide environment variables.

How It Works

With KV Skill Available:

Agent owners can store their OpenAI API key and workflow ID securely in KV storage

Credentials are scoped to the agent owner's namespace

All users of the agent share the agent owner's configured credentials

Fallback to environment variables if credentials not configured in KV

Without KV Skill:

Credentials loaded from environment variables (OPENAI_API_KEY) and config (workflow_id)

Traditional single-tenant behavior

Setting Up Credentials

Option 1: Setup Form (Recommended for Multitenancy)

When KV skill is available, visit the setup URL:

{agent_base_url}/{agent-name}/setup/openai

For example:

http://localhost:2224/agents/my-agent/setup/openai

This displays a web form where you can enter:

OpenAI API Key (sk-...)

Workflow ID (wf_...)

Option 2: Programmatic Update

Use the update_openai_credentials tool:

// Coming soon — track at https://github.com/robutlerai/webagents/issues

Option 3: Remove Credentials

To remove stored credentials and fall back to environment variables:

// Coming soon — track at https://github.com/robutlerai/webagents/issues

Setup Guidance

When KV skill is available but credentials aren't configured, the skill automatically provides setup instructions:

In prompt: Setup URL is included in the agent's system prompt

In errors: If execution fails due to missing credentials, error message includes setup link

Example with KV Skill

// Coming soon — track at https://github.com/robutlerai/webagents/issues
// In TypeScript, use OpenAILLMSkill directly with an API key sourced from
// RobutlerKVSkill or environment variables:
//
// import { BaseAgent } from 'webagents';
// import { OpenAILLMSkill } from 'webagents/skills/llm';
// import { RobutlerKVSkill } from 'webagents/skills/storage';
// const agent = new BaseAgent({
//   name: 'workflow-agent',
//   skills: [
//     new RobutlerKVSkill({ agentId: 'workflow-agent' }),
//     new OpenAILLMSkill({ apiKey: process.env.OPENAI_API_KEY! }),
//   ],
// });

Agent owner visits {base_url}/agents/workflow-agent/setup/openai to configure their credentials.

[!WARNING] Credentials are stored per agent owner, not per end-user. All users interacting with the agent will use the agent owner's OpenAI account.

Basic Usage

With BaseAgent

// Coming soon — see the note at the top of this page. Use OpenAILLMSkill
// from webagents/skills/llm for OpenAI chat / responses APIs:
//
// import { BaseAgent } from 'webagents';
// import { OpenAILLMSkill } from 'webagents/skills/llm';
// const agent = new BaseAgent({
//   name: 'workflow-agent',
//   skills: [new OpenAILLMSkill({ apiKey: process.env.OPENAI_API_KEY! })],
// });
// for await (const chunk of agent.runStreaming([
//   { role: 'user', content: 'Hello!' },
// ])) {
//   console.log(chunk);
// }

Environment Setup

Create a .env file:

OPENAI_API_KEY=sk-proj-your-key-here

The skill automatically loads this key at initialization.

How It Works

Message Flow

Input: Standard OpenAI chat format messages

Filter: Only user messages sent to workflow (system/assistant filtered out)

Convert: Transform to workflow input format

Stream: SSE events from OpenAI workflows API

Normalize: Convert to OpenAI completion chunks

Yield: Real-time to client

Message Filtering

OpenAI workflows don't handle system or assistant roles. The skill automatically filters:

// Input
[
  {"role": "system", "content": "You are helpful"},
  {"role": "user", "content": "Hello!"},
  {"role": "assistant", "content": "Hi there!"},
  {"role": "user", "content": "How are you?"}
]

// Sent to workflow (user messages only)
[
  {"role": "user", "content": "Hello!"},
  {"role": "user", "content": "How are you?"}
]

Streaming Deltas

The skill extracts word-by-word deltas from workflow.node.agent.response events:

workflow.started → workflow.node.agent.response (delta: "Hello")
                → workflow.node.agent.response (delta: " there")
                → workflow.node.agent.response (delta: "!")
                → workflow.finished

Each delta is immediately yielded as a streaming chunk for real-time display.

Usage Tracking

Token usage is automatically tracked and logged to context.usage:

{
  "type": "llm",
  "timestamp": 1759984808.392,
  "model": "gpt-5-nano-2025-08-07",
  "prompt_tokens": 17,
  "completion_tokens": 208,
  "total_tokens": 225,
  "streaming": true,
  "source": "openai_workflow"
}

This integrates with the Payment Skill for automatic cost calculation and billing.

Special Content Detection

The skill automatically detects and wraps special content types for proper UI rendering.

Thinking Content

Thinking/reasoning content is wrapped in <think> tags.

Type-Based Detection

Detection is based purely on the type field in OpenAI's SSE responses - no model name checking required:

Type field monitoring - Checks response_data.get('type') for keywords

Automatic wrapping - Opens <think> tag when reasoning, thinking, or summary detected

Smart closure - Closes </think> tag when type changes to regular content

Guaranteed closure - Ensures tags are closed at workflow finish

Why this works: OpenAI workflows explicitly mark content types in their SSE responses, making detection reliable regardless of which model is used.

OpenAI Workflow Format

OpenAI workflows use specific type markers in their SSE responses:

{
  "delta": "Let me think about this...",
  "type": "response.reasoning_summary_text.delta",  // Thinking content
  ...
}

{
  "delta": "Based on my analysis...",
  "type": "response.text.delta",  // Regular output
  ...
}

Example Output

For any workflow that generates thinking content (e.g., gpt5-nano, o1, o3):

<think>
**Analyzing the problem**

I need to consider:
1. The core requirements
2. Potential edge cases
3. Performance implications

Let me work through this step by step...
</think>

Based on my analysis, I recommend approach B because...

Supported Type Markers

The skill wraps content when the delta type field contains:

"reasoning" - Reasoning/chain-of-thought content

"thinking" - Internal thought process

"summary" - Reasoning summaries

Common OpenAI workflow types:

response.reasoning_summary_text.delta → Wrapped in <think>

response.text.delta → Regular output (not wrapped)

The skill automatically detects and wraps OpenAI ChatKit widgets in <widget> tags for interactive UI components.

When a workflow emits workflow.node.agent.widget events:

{
  "type": "workflow.node.agent.widget",
  "widget": "{\"type\":\"Card\",\"children\":[...]}"
}

The skill extracts the widget JSON and wraps it:

<widget>{"type":"Card","children":[...]}</widget>

Based on the OpenAI ChatKit Widget Spec:

Card - Container with optional styling and background

Row - Horizontal layout with flex alignment

Col - Vertical layout with configurable gap

Text - Display text with size and color options

Caption - Small text for labels and metadata

Image - Display images with configurable size

Spacer - Flexible space for layout

Divider - Horizontal separator line

Box - Generic container with width/height/background/border-radius

Button - Interactive button (click handlers supported)

Flight status card from your workflow:

{
  "type": "Card",
  "size": "md",
  "background": "linear-gradient(135deg, #378CD1 0%, #2B67AC 100%)",
  "children": [
    {"type": "Row", "children": [
      {"type": "Image", "src": "...", "size": 16},
      {"type": "Caption", "value": "AA247"},
      {"type": "Spacer"},
      {"type": "Caption", "value": "2025-10-09", "color": "alpha-50"}
    ]},
    {"type": "Divider", "flush": true},
    {"type": "Col", "gap": 3, "children": [
      {"type": "Row", "align": "center", "children": [
        {"type": "Text", "value": "New York, JFK"},
        {"type": "Spacer"},
        {"type": "Text", "value": "Los Angeles, LAX"}
      ]}
    ]}
  ]
}

This renders as an interactive card showing flight information with proper styling, layout, and visual hierarchy.

Advanced Configuration

Pin to Specific Version

// Coming soon — track at https://github.com/robutlerai/webagents/issues

Custom API Base

import { OpenAILLMSkill } from 'webagents/skills/llm';

new OpenAILLMSkill({
  apiKey: process.env.OPENAI_API_KEY!,
  baseUrl: 'https://custom-api.example.com/v1',
});

Testing

Test the workflow directly with curl:

curl 'https://api.openai.com/v1/workflows/wf_YOUR_WORKFLOW_ID/run' \
  -H 'authorization: Bearer YOUR_OPENAI_API_KEY' \
  -H 'content-type: application/json' \
  --data-raw '{
    "input_data": {
      "input": [{
        "role": "user",
        "content": [{"type": "input_text", "text": "hi"}]
      }]
    },
    "state_values": [],
    "session": true,
    "tracing": {"enabled": true},
    "stream": true
  }'

Handoff Integration

The skill registers itself as a streaming handoff handler:

// Coming soon — track at https://github.com/robutlerai/webagents/issues

This allows the agent to use OpenAI workflows as its primary completion handler.

Architecture

Error Handling

HTTP Errors: Captured and returned as error messages

Malformed SSE: Logged and skipped

Connection Timeouts: 120s default timeout

Workflow Failures: workflow.failed events converted to error responses

Limitations

User Messages Only: System and assistant messages are filtered out

No Tool Calling: Workflows don't support external tool integration

Workflow-Specific Versions: Each workflow has its own versioning scheme

Best Practices

✅ Use OPENAI_API_KEY from environment, not config

✅ Omit version unless you need a specific structure

✅ Test workflows with curl before integration

✅ Monitor usage logs to verify cost tracking

✅ Enable session support for multi-turn conversations

API Reference

::: webagents.agents.skills.ecosystem.openai.skill.OpenAIAgentBuilderSkill options: show_source: true members: - init - initialize - run_workflow_stream

Handoffs System

Payment Skill

Agent Skills

On this page