@salesforce/sfdx-agent-harness-openai

OpenAI Agents SDK-backed AgentHarness implementation for @salesforce/sfdx-agent-sdk.

Closed source. This package is published to npm under the Salesforce Public Code License and is for use by Salesforce only.

Milestone F — closeout (this release). All six milestones (A–F) have landed: A's connectivity + streamed turn, B's disk-backed sessions / thread lifecycle / message history, C's tool approval + consumer-executed tools, D's MCP server lifecycle + updateAgent preservation (#541), E's compaction / telemetry / hooks, and F's full conformance-gate + e2e closeout. Every AgentHarness method has a working implementation, the shared cross-harness conformance gate is green, and the harness passes the SDK's describe.each e2e matrix under --harness openai against the real gateway. MCP-tool approval gating IS supported (added post-F): a require-approval / deny policy on an MCP tool surfaces a tool-approval-request and honors the parked-approval lifecycle. When a policy gates MCP tools (or a redaction hook is set), the harness materializes MCP tools via getAllMcpTools(...) and stamps a needsApproval predicate on each, so the run loop raises the interruption the coordinator already routes. Consumer-tool approval + submitToolResult, and tool-result redaction, are likewise supported. AgentConfig.rules composition IS supported (added post-F, W-23546667): createAgent / updateAgent load each rule file/directory, strip YAML frontmatter, and compose the bodies onto the effective system prompt — so the harness rejoins the dual-harness rules e2e. AgentConfig.skills composition IS supported (added post-F, W-23546666): createAgent / updateAgent load config.skills into a skill catalog exposed to the model as load_skill / read_skill_file function tools (the latter serving a skill's sibling files), so the harness rejoins the dual-harness skills e2e including multi-file skill reachability. Multimodal image/file input IS supported (added post-F, W-23546665): chat() / stream() and addContext accept image / file MessageParts and round-trip them to the model, so the harness rejoined the multimodal e2e matrix. MCP tool-progress IS supported (W-23558557): @openai/agents exposes no onprogress seam on its own MCP client, so the harness owns its own @modelcontextprotocol/sdk Client per server and surfaces an upstream server's notifications/progress as tool-progress ChatEvents on the consumer's eventStream.

What it is

A third implementation of the SDK's AgentHarness contract, alongside the Mastra and Claude harnesses. It is backed by the OpenAI Agents SDK — an agentic framework (it owns the run loop, tool orchestration, and sessions), peer to Mastra and the Claude Agent SDK, not a model. GPT models are already served through the Mastra harness's /responses pass-through; this harness exists to provide an OpenAI-maintained run loop and a genuine third implementation that stress-validates the AgentHarness contract's harness-agnosticism.

The harness advertises supportedProviderHints: ['openai-responses', 'openai'].

Quick start

import { createAgentManager } from '@salesforce/sfdx-agent-sdk';
import { OpenAIAgentsHarnessFactory } from '@salesforce/sfdx-agent-harness-openai';

const manager = await createAgentManager(storageRootFolder, new OpenAIAgentsHarnessFactory());

The SDK's AgentConnectivityResolver supplies the gateway URL, native model id, provider hint, and per-request auth headers as a ModelConnectivityInfo bag; the factory carries only harness-internal concerns.

Observability compatibility

This in-process harness emits structured llm-request / llm-response wire events. Matching events carry the harness-generated correlationId; llm-response provides best-effort responseText and timeToFirstTokenMs after the streaming body terminates. It also emits the debug-only mcp-tool-call-completed event; its durationMs is an adapter/coordinator-observed window and can include a model round-trip. It does not emit llm-retry telemetry because its stateless fetch layer has no observable retry attempt counter. See the SDK README's cross-harness coverage table for the complete contract and cross-harness comparison.

Public API

| Export | Kind | Description | | ---------------------------------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | OpenAIAgentsHarnessFactory | class | HarnessFactory that constructs the harness. Pass to createAgentManager. | | OpenAIAgentsHarnessFactoryConfig | type | Optional factory configuration. Carries toolApprovalTimeoutMs (per-toolCallId approval timeout, default 600_000 ms); connectivity flows in from the SDK's resolver, not the factory. | | OPENAI_BUILT_IN_TOOL_POLICIES | const | The harness's built-in tool-approval tier fed to resolveToolApprovalPolicy (the tiers.harness slice). Empty today — the harness registers no runtime built-in tools of its own. Mirrors the Mastra / Claude *_BUILT_IN_TOOL_POLICIES surfaces. |

Connectivity flows in from the SDK as a ModelConnectivityInfo bag — for Salesforce-org gateway routing use DefaultAgentConnectivityResolver from @salesforce/sfdx-agent-sdk (or any custom resolver); for direct-OpenAI / BYOK paths use ApiKeyConnectivityResolver.

Development

See DEVELOPING.md for build, test, and packaging commands, and ARCHITECTURE.md for internal design.