@temporalio/agent-harness 0.1.0 → 0.3.0

package/skills/temporal-harness-typescript/assets/starter/agents.ts.tmpl

@@ -0,0 +1,61 @@
+import { Agent, type AgentInputItem } from "@openai/agents-core";
+import { z } from "zod";
+import {
+  TextMessage,
+  TextReply,
+  ToolApprovalPolicy,
+  defineAgent,
+  handler,
+  tool,
+} from "@temporalio/agent-harness";
+import {
+  asOpenAIAgentTool,
+  runStreamed,
+} from "@temporalio/agent-harness/ai-sdks/openai-agents-harness";
+
+const getWeather = tool({
+  name: "get_weather",
+  description: "Return sample weather for a city.",
+  inputSchema: z.object({ city: z.string() }),
+  outputSchema: z.string(),
+  inherentlySafe: true,
+  execute: async ({ city }) => `It's 72°F and sunny in ${city}.`,
+});
+
+export const OpenAIHelloAgentTs = defineAgent({
+  name: "OpenAIHelloAgentTs",
+  approvalPolicyDefault: ToolApprovalPolicy.allowInherentlySafe(),
+  handlers: {
+    ping: handler({ description: "Check the worker without a model call.", input: TextMessage, output: TextReply }),
+    ask: handler({
+      description: "Chat with the assistant. Ask about the weather to try its tool.",
+      input: TextMessage,
+      output: TextReply,
+    }),
+  },
+  create: ({ runner }) => {
+    let conversation: AgentInputItem[] = [];
+    return {
+      async ping({ text }) { return { text }; },
+      async ask({ text }) {
+        const sdkAgent = new Agent({
+          name: "Hello",
+          instructions: "Answer briefly. For weather questions, call get_weather and explain that it returns sample data.",
+          model: "gpt-5.1",
+          tools: [asOpenAIAgentTool(runner, getWeather)],
+        });
+        const input: AgentInputItem[] = [...conversation, { role: "user", content: text }];
+        const result = await runStreamed(runner, sdkAgent, input, {
+          defaultModelParams: {
+            startToCloseTimeout: "2 minutes",
+            heartbeatTimeout: "30 seconds",
+          },
+        });
+        for await (const _event of result) void _event;
+        await result.completed;
+        conversation = result.history;
+        return { text: String(result.finalOutput) };
+      },
+    };
+  },
+});

package/skills/temporal-harness-typescript/assets/starter/env.example.tmpl

@@ -0,0 +1,3 @@
+# Uncomment and set your key before trying `ask`; `ping` works without one.
+# OPENAI_API_KEY=sk-...
+# Export the same TEMPORAL_* settings in every service terminal when using a profile.

package/skills/temporal-harness-typescript/assets/starter/gitignore.tmpl

@@ -0,0 +1,6 @@
+.env.local
+.venv/
+__pycache__/
+*.egg-info/
+node_modules/
+dist/

package/skills/temporal-harness-typescript/assets/starter/package.json.tmpl

@@ -0,0 +1,35 @@
+{
+  "name": "__PROJECT_NAME__",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "schema": "npm run build && agent-harness schema ./dist/agents.js#OpenAIHelloAgentTs -o agent.schema.json",
+    "harness:dev": "uvx --from 'temporal-agent-harness[ui]==0.9.0' temporal-agent-harness dev agents.toml",
+    "start": "node --env-file-if-exists=.env.local dist/worker.js",
+    "harness:skill": "agent-harness skills install",
+    "harness:doctor": "agent-harness doctor --schema agent.schema.json"
+  },
+  "dependencies": {
+    "@temporalio/agent-harness": "__HARNESS_VERSION__",
+    "@temporalio/agent-harness-worker": "__HARNESS_VERSION__",
+    "@temporalio/agent-harness-client": "__HARNESS_VERSION__",
+    "@temporalio/activity": "1.24.0",
+    "@temporalio/client": "1.24.0",
+    "@temporalio/common": "1.24.0",
+    "@temporalio/envconfig": "1.24.0",
+    "@temporalio/plugin": "1.24.0",
+    "@temporalio/worker": "1.24.0",
+    "@temporalio/workflow": "1.24.0",
+    "@temporalio/workflow-streams": "1.24.0",
+    "@temporalio/openai-agents": "1.24.0",
+    "@openai/agents-core": "0.14.3",
+    "@openai/agents-openai": "0.14.3",
+    "openai": "6.46.0",
+    "zod": "4.6.5"
+  },
+  "devDependencies": {
+    "typescript": "7.0.2",
+    "@types/node": "22.20.4"
+  }
+}

package/skills/temporal-harness-typescript/assets/starter/tsconfig.json.tmpl

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "skipLibCheck": true,
+    "types": ["node"],
+    "rootDir": ".",
+    "outDir": "dist"
+  },
+  "include": ["agents.ts", "worker.ts"]
+}

package/skills/temporal-harness-typescript/assets/starter/worker.ts.tmpl

@@ -0,0 +1,24 @@
+import { fileURLToPath } from "node:url";
+import { loadClientConnectConfig } from "@temporalio/envconfig";
+import { NativeConnection, Worker } from "@temporalio/worker";
+import { AgentHarnessPlugin } from "@temporalio/agent-harness-worker";
+import { OpenAIAgentsPlugin } from "@temporalio/agent-harness-worker/ai-sdks/openai-agents";
+
+// `ping` needs no model, so the worker starts without a key; only `ask` fails without one.
+if (!process.env.OPENAI_API_KEY)
+  console.warn("OPENAI_API_KEY is not set: `ping` works, `ask` will fail until it is (see env.example)");
+
+const { connectionOptions, namespace } = loadClientConnectConfig();
+const connection = await NativeConnection.connect(connectionOptions);
+try {
+  const worker = await Worker.create({
+    connection,
+    namespace: namespace ?? "default",
+    taskQueue: "openai-hello-ts",
+    workflowsPath: fileURLToPath(new URL("./agents.js", import.meta.url)),
+    plugins: [new OpenAIAgentsPlugin(), new AgentHarnessPlugin()],
+  });
+  await worker.run();
+} finally {
+  await connection.close();
+}

package/skills/temporal-harness-typescript/references/advanced.md

@@ -0,0 +1,57 @@
+# Advanced TypeScript features
+
+Read the installed package's public types and the agent's generated schema for exact signatures.
+Prefer a small change to the working starter over copying internal runtime implementation.
+
+- **Observable state:** declare state on the agent, initialize it through its schema, and mutate
+  through the provided state reference. Mutations publish patches; changing an unrelated local
+  object does not publish observable state. Keep mutation callbacks synchronous.
+- **Approvals:** distinguish permission to run a tool from supplying a callback result. Preserve
+  the requesting agent and tool IDs, especially for subagents. See `api.md` for HTTP calls.
+- **Callbacks:** the tool implementation runs on the client; model execution waits for a result.
+  Use the application client's callback handlers or pending callback interface.
+- **Subagents:** expose typed handlers and compose through the harness subagent APIs. Follow
+  events using their agent identity rather than flattening the tree into the parent's transcript.
+- **Code Mode:** requires the optional Monty sandbox dependency on the worker. Expose an explicit
+  toolset; scripts run against those host functions. Filesystem mounts and durable activity
+  filesystems have separate declarations and worker registrations.
+- **Mid-turn handlers:** choose enqueue/accept/reject intentionally. Use `/api/messages` plus
+  `/api/attach` for clients that support messages joining an existing turn.
+
+For complete worked examples matching a release, use the repository's release-tagged Monty and
+OpenAI examples. A checkout is optional for normal application development. Do not assume Python
+and TypeScript model integrations or advanced feature signatures are interchangeable.
+
+## Add observable state to the starter
+
+Import `state` from `@temporalio/agent-harness`. Add a declaration to `defineAgent` and read its
+reference from the `create` context:
+
+```ts
+// Alongside handlers in defineAgent({...}):
+states: { counter: state(z.object({ messages: z.number().int().default(0) })) },
+
+// In create({ runner, state }), inside a handler:
+state.counter.mutate(draft => { draft.messages += 1; });
+```
+
+Read `state.counter.current` for the current value. Mutation callbacks must be synchronous.
+Regenerate the agent schema; client codegen then exposes the `counter` state.
+
+## Choose a tool boundary
+
+| Work | Public declaration | Registration |
+| --- | --- | --- |
+| Deterministic, fast computation | `tool({ ..., execute })` | Adapt through the model integration |
+| External I/O, database or provider calls | `activityTool({ ..., activityOptions })` | `new AgentHarnessPlugin({ tools: [toolActivity(declaration, implementation)] })` on the worker |
+| Browser/user environment | `tool({ ..., outputSchema })` without `execute` | Supply the result through the application client |
+
+Declarations come from `@temporalio/agent-harness`; `toolActivity` comes from
+`@temporalio/agent-harness-worker`. Keep implementations with Node/network imports out of the
+workflow bundle. Set timeouts and make side effects idempotent across retries. `inherentlySafe`
+is an explicit approval-policy decision. Use `injected<T>()` bindings for workflow-supplied
+values that should stay out of model input schemas.
+
+`subagentToolset` and `codeModeTool` are exported from the core package. Code Mode also needs
+`@pydantic/monty` on the worker. Inspect their installed declarations for lifecycle, mounting,
+and toolset options. Keep each child's registry, worker queue, and generated interface aligned.

package/skills/temporal-harness-typescript/references/api.md

@@ -0,0 +1,110 @@
+# Harness API and session lifecycle
+
+The shared Python server serves the same HTTP API and browser console for Python and TypeScript
+agents. Run a Temporal service, session-manager worker, API server, and your agent worker with
+the same connection and namespace. Worker task queues must match the registry.
+
+## Discover and start
+
+`GET /api/agents` lists registered workflow types, init-data schemas, and worker poller status.
+A poller indicates availability on a queue, not proof that it hosts a particular workflow type.
+`GET /api/sessions` lists sessions. Create one using the **workflow type**, not the registry key:
+
+```bash
+curl --fail-with-body http://localhost:8000/api/sessions \
+  -H 'Content-Type: application/json' \
+  -d '{"agent_workflow_type":"OpenAIHelloAgentTs"}'
+```
+
+The response's `workflow_id` is the session ID used by subsequent calls. An optional `session_id`
+lets an integration derive a stable ID from its own conversation identity; repeated creation
+with the same ID is idempotent. Supply `data` when the agent requires init data. Do not send it
+for an agent that takes none. The server checks presence and the agent validates its schema.
+Read `GET /api/agent-interface/{session_id}` for handlers and their input/output schemas.
+
+## Send and observe separately
+
+Use `POST /api/messages` for typed messages:
+
+```json
+{
+  "session_id": "the-workflow-id",
+  "message": {"type": "ask", "payload": {"text": "What's the weather in Paris?"}},
+  "request_id": "stable-id-for-this-one-delivery"
+}
+```
+
+An accepted message may open a turn, join a running turn, or be queued. Acceptance is not
+completion. Save the returned `message_id` and follow the event stream for its result. Reuse
+`request_id` only when retrying the same delivery; distinct user messages need distinct IDs.
+
+Attach with `GET /api/attach?session_id=...&from_offset=0` (URL-encode the ID). The response is
+SSE (`text/event-stream`). Events carry JSON data, including `resume_offset` when available.
+Save the last processed resume offset and pass it as `from_offset` on reconnect. Do not assume
+browser `Last-Event-ID` is the resume mechanism. Read the event's handler/message/agent identity:
+a session can contain queued messages, mid-turn handlers, and subagent events.
+
+Use the published `@temporalio/agent-harness-client`, React, or Svelte clients when possible;
+they implement stream/state handling. `POST /api/chat` is a convenience for a turn it opens;
+use message submission plus attach for general application clients and mid-turn handlers.
+
+## Human interaction
+
+`POST /api/approve` takes `session_id`, `tool_id`, `approved`, optional `reason`, and optional
+`remember`. An approval authorizes the pending tool; it does not provide a callback result.
+
+`POST /api/callback-result` takes `session_id`, `tool_id`, and `result` or `error`. A callback
+executes in the client environment. Preserve the identity of the agent requesting it; a UI may
+be answering a subagent's request. The client SDK handles routing across the agent tree.
+
+## State, status, and closing
+
+Apply a state snapshot before its subsequent patches, in stream order. Use the SDK's state
+implementation instead of treating every event as a complete state document.
+
+- `GET /api/status/{session_id}`: current turn, pending work, and agent status.
+- `GET /api/workflow-status/{workflow_id}`: execution status.
+- `POST /api/sessions/{session_id}/close`: signal the agent to wind down and settle pending interactions.
+
+Disconnecting an SSE stream does **not** close the agent. A network error is not evidence that
+its workflow has ended. Reconnect; only treat an explicit not-found/closed result as terminal.
+
+## Errors and schemas
+
+Check HTTP status before parsing a success response. Invalid init-data presence returns 422;
+other errors may contain `error`/`message` or FastAPI's `detail`. Do not retry a rejected payload
+unchanged. On a transport failure, retry a submission using its original request ID.
+
+The running server exposes `/openapi.json` and `/docs`, generated from its route declarations.
+To save the HTTP contract while the server is running:
+
+```bash
+curl --fail-with-body http://localhost:8000/openapi.json -o openapi.json
+```
+
+Generate an agent's schema from its declaration:
+
+```bash
+# Python
+temporal-agent-harness schema my_agent.workflow:OpenAIHelloAgentWorkflow -o agent.schema.json
+# TypeScript: compile first (agent-harness-schema is the same command)
+agent-harness schema ./dist/agents.js#OpenAIHelloAgentTs -o agent.schema.json
+# Either schema can generate a typed application client
+harness-codegen agent.schema.json -o Agent.ts
+```
+
+The code generator is distributed as `@temporalio/agent-harness-codegen`. Regenerate and commit
+client types after changing handlers, state, or init data. Never patch generated types manually.
+
+## Registry and deployment
+
+`agents.toml` declares a key, workflow type, task queue, label, description, and optional schema
+path relative to the TOML file. Keep the schema's agent name equal to `workflow_type`. The server
+never imports your agent implementation. The session manager caches its registry: replacing the
+registry file alone does not update an already-running manager's list. Restart with fresh local
+Temporal state only when the development sessions are disposable.
+
+The built-in local payload store is for processes sharing a host/filesystem. For a multi-host
+deployment, configure a shared offload store consistently across clients, workers, and server.
+Expose the API through your application's authentication boundary when deploying beyond local
+development. Embedding the FastAPI app lets you add your own middleware and routes.

package/skills/temporal-harness-typescript/references/authoring.md

@@ -0,0 +1,65 @@
+# TypeScript authoring
+
+Use `@temporalio/agent-harness` in workflow modules and `@temporalio/agent-harness-worker` on the
+Node worker. `npx agent-harness init ./my-agent` materializes a runnable OpenAI starter. The same
+starter is installed with this skill under `assets/starter/`; read `agents.ts.tmpl` and
+`worker.ts.tmpl` there for the complete wiring. Its exact Temporal SDK versions match the model
+plugin; keep those versions aligned. Harness package versions are separate from the underlying
+Temporal SDK versions. Compile ESM before starting.
+
+A minimal agent, with a safe inline tool and a model-free handler:
+
+```ts
+import { z } from "zod";
+import { TextMessage, TextReply, ToolApprovalPolicy, defineAgent, handler, tool } from "@temporalio/agent-harness";
+
+export const getWeather = tool({
+  name: "get_weather",
+  description: "Return sample weather for a city.",
+  inputSchema: z.object({ city: z.string() }),
+  outputSchema: z.string(),
+  inherentlySafe: true,
+  execute: async ({ city }) => `It's 72°F and sunny in ${city}.`,
+});
+
+export const HelloAgent = defineAgent({
+  name: "HelloAgent",
+  approvalPolicyDefault: ToolApprovalPolicy.allowInherentlySafe(),
+  handlers: {
+    ping: handler({ description: "Echo without a model call.", input: TextMessage, output: TextReply }),
+  },
+  create: ({ runner }) => ({
+    async ping({ text }) {
+      return { text };
+    },
+  }),
+});
+```
+
+The starter's `ask` handler adds the model turn: it passes `getWeather` through
+`asOpenAIAgentTool(runner, ...)` and awaits `runStreamed(runner, sdkAgent, input, ...)`.
+
+Public authoring imports come from `@temporalio/agent-harness`: `defineAgent`, `handler`, `tool`,
+`state`, `TextMessage`, `TextReply`, and `ToolApprovalPolicy`. Use Zod schemas for inputs and
+outputs. `defineAgent({ name, handlers, create })` returns the workflow export; `create` receives
+its runner, init data, and declared state references. Keep Node imports and external I/O in the
+worker or activities, not in the workflow module.
+
+Use `ToolApprovalPolicy.allowInherentlySafe()` for tools explicitly marked `inherentlySafe`.
+For OpenAI, import `asOpenAIAgentTool` and `runStreamed` from
+`@temporalio/agent-harness/ai-sdks/openai-agents-harness`. Consume the stream and await completion.
+Keep conversation history inside the agent instance. The worker's `OpenAIAgentsPlugin` comes from
+`@temporalio/agent-harness-worker/ai-sdks/openai-agents`, followed by `AgentHarnessPlugin`.
+Activity tool implementations are registered using `toolActivity` on the harness plugin.
+
+Point `workflowsPath` at the compiled agent module. Generate its schema with
+`agent-harness schema ./dist/agents.js#Export -o Agent.schema.json` (the `agent-harness-schema`
+binary is the same command). The registry's `workflow_type`
+must match `defineAgent`'s `name`, and its queue must match the worker. The schema CLI does not
+start Temporal. The shared Python server reads the schema without importing TypeScript code.
+
+The shared services come from the Python package: the starter's `npm run harness:dev` runs
+`temporal-agent-harness dev agents.toml` through `uvx`, beside Temporal and the Node worker.
+`npx agent-harness doctor --schema Agent.schema.json` checks the installed package, schema, API,
+and agent worker availability. For direct Temporal connection and local TOML validation, use the
+shared Python CLI's `doctor --registry agents.toml`. Both support `--json` and never reset services.

package/skills/temporal-harness-typescript/references/verification.md

@@ -0,0 +1,17 @@
+# Verification and troubleshooting
+
+Validate against the installed SDK version. Run the starter's schema command before launching
+services. A successful check includes discovering the agent, creating a session, sending a typed
+message, seeing a tool result and completed reply, and reconnecting to the same session.
+Use a scripted model for repeatable automated tests; do not claim a scripted response is a live
+provider test. Test approval/callback paths separately when your agent uses them.
+
+If the console loads but cannot start a session, check the session-manager worker. If a session
+exists but messages stall, check the agent worker, task queue, and namespace. If a model fails,
+check the worker's provider credentials and optional integration dependencies. If registration
+changes appear stale, inspect the session manager's cached registry before replacing local state.
+
+Keep the Temporal server, namespace, and task queues isolated for tests. Do not terminate unrelated
+sessions or reset a user's existing development server to make a test pass. Temporal workflow code
+must remain deterministic; move external I/O into activities. Replaying a completed activity uses
+its recorded result, but retryable activities with side effects still need idempotent design.