Skip to content
Python
5.0 KB
Raw Blame

OpenWorker Harness SDK for TypeScript

Build a desktop app, web app or Node.js utility with an agent that can use your tools and keep its conversation across restarts. Your app owns the interface; OpenWorker manages the agent loop.

SDK overview · Desktop guide · Web guide · API declarations

Install

npm install @openworkerai/harness-sdk

Requires Node.js 20+ and ESM. This documentation-only client release uses the unchanged native runtime 0.1.0-beta.3. npm selects the exact platform package; keep optional dependencies enabled. No Rust compiler or Python installation is needed. Run the SDK in Node, Electron's main process or your application server; browser code calls your app's API or IPC.

Run your first agent

Save as agent.mjs. Provide OPENAI_API_KEY and OPENWORKER_MODEL in your process environment or a private env file. Use an exact model ID available to your account.

import { resolve } from 'node:path';
import { Harness } from '@openworkerai/harness-sdk';

const model = process.env.OPENWORKER_MODEL;
if (!model) throw new Error('Set OPENWORKER_MODEL');
const harness = await Harness.start({
  stateDir: resolve('.openworker-state'), sandbox: 'off',
});
try {
  await harness.setModelProvider({
    name: 'OpenAI', api: 'responses',
    baseUrl: process.env.OPENWORKER_MODEL_URL ?? 'https://api.openai.com/v1',
    credentials: { apiKeyEnv: 'OPENAI_API_KEY', storage: 'memory' },
  });
  const agent = harness.createAgent({
    name: 'first-agent-v1', instructions: 'Give concise, helpful answers.',
    defaultModel: { provider: 'OpenAI', name: model },
    tools: [], planning: false, memory: false, scheduling: false,
  });
  const session = await agent.newSession();
  const result = await session.run('Suggest three names for a file-organizing app.');
  if (result.status !== 'completed') throw new Error(`Run ended: ${result.status}`);
  console.log(result.finalOutput);
} finally {
  await harness.shutdown();
}
node --env-file=/path/to/private.env agent.mjs

OPENWORKER_MODEL_URL optionally selects another Responses-compatible endpoint.

This text-only example exposes no tools and explicitly disables sandboxing. When adding tools, choose their execution boundary deliberately. Node callbacks retain your app's privileges; workspace alone does not confine filesystem access. See custom tools and scope.

Build with your coding agent

npx @openworkerai/openworker-harness-builder --agent claude --project .

Use --agent codex for Codex or --global for user-wide installation. Existing installs prompt before replacement; --replace-existing skips the prompt and saves a backup. The Skill's installation.json records its tested SDK version. See the Skill guide and runnable file-organizer example.

Add the next capability

You want to… Start here
Add tools and show their arguments Tools and MCP
Stream text and handle approval cards Streaming and approval loop
Change models or refresh credentials Models and credentials
Resume a conversation or delegate work Sessions and teams
Accept images, PDFs and text files Attachments
Isolate tools and inspect content OpenShell · Guardrails
Inspect turns and export traces Observability
Run a shared service Deployment options

Integration contract

  • Start one harness for the app/service lifecycle; always shut it down on exit.
  • Use createAgent and setModelProvider for new apps. Explicit executables, startup agent arrays and setConnection are advanced interfaces.
  • Agent definitions are immutable in durable state. Change the name when changing instructions, tools or approval mode. Identical registration is safe.
  • Node resolves apiKeyEnv and sends the key over private stdio. inheritEnv is unnecessary for this credential path. Memory-only keys must be resupplied after app restart; the SDK does not load env files automatically.
  • Save session.reference() and use agent.resumeSession(reference) for recovery. Stopping observation does not cancel work; use session.cancel() for Stop.
  • Never automatically retry an action whose outcome is unknown. Reconcile durable state and the external system first.

See versions and compatibility and troubleshooting.