Document the merged durable-agent layer

README: new Durable AI Agents section (subpath quickstart mirroring
examples/agents/quickstart/01-basic-agent.ts, wrapper/testing subpaths,
docs + examples pointers) and a Documentation-table row.

AGENTS.md: src/agents feature area — repo layout additions (src/agents,
e2e/, cli-bin/, examples/agents, docs/agents), the subpath-only export rule
(root re-export ban and the OpenAPI Action collision that motivates it),
colocated-test and e2e conventions, example run story, AGENTSPAN_* config
surface, and the agent-e2e command.

CHANGELOG: additive-minor entry with a migration note for
@conductor-oss/conductor-agent-sdk users (specifier rewrite, /agents-prefixed
wrapper subpaths, optional peers, dotenv/sideEffects behavior).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: Kowser

AGENTS.md

@@ -40,13 +40,51 @@ src/open-api/                    # OpenAPI layer
   types.ts                       # Extended types - add custom fields here
 src/integration-tests/           # E2E tests against real Conductor server
   utils/                         # waitForWorkflowStatus, executeWorkflowWithRetry, etc.
+src/agents/                      # Durable agent layer (merged Agentspan TS SDK)
+  index.ts                       # Agent, AgentRuntime, tool, guardrails, handoffs, ...
+  frameworks/                    # LangGraph/LangChain/generic serializers + detection
+  testing/                       # Agent testing toolkit (/agents/testing subpath)
+  wrappers/                      # Vercel AI / LangGraph / LangChain drop-in wrappers
+  __tests__/                     # Colocated jest unit tests (picked up by test:unit)
+e2e/                             # Agent e2e suites vs live agentspan server (jest.e2e.config.mjs)
+cli-bin/                         # agentspan CLI helper scripts (Go CLI walk-up probe target)
+examples/agents/                 # Agent examples (own tsconfig; run via npx tsx)
+docs/agents/                     # Agent layer documentation
 ```
 
+### The agent layer (`src/agents/`)
+
+- **Subpath-only exports**: everything agent-flavored ships via `./agents`,
+  `./agents/testing`, `./agents/vercel-ai`, `./agents/langgraph`,
+  `./agents/langchain` (see `exports` in package.json + `tsup.config.ts`).
+  **Never re-export agent symbols from the root** — the agent layer has an
+  `Action` class that collides with the OpenAPI-generated `Action` type, and
+  the root re-exports the whole generated surface, which changes with the
+  server spec.
+- Source keeps upstream's ESM-style `.js`-suffixed relative imports (resolved
+  by `nodenext` for tsc and a `moduleNameMapper` suffix-strip for jest).
+- The only coupling to the workflow layer is in `agent-client.ts` and
+  `worker.ts` (imports from `../sdk` and `../open-api`) — keep it that way.
+- Unit tests are colocated in `src/agents/__tests__/` so the existing
+  `test:unit` glob and per-PR CI matrix pick them up with zero workflow
+  changes. Agent e2e lives in repo-root `e2e/` and runs only via
+  `npm run test:agent-e2e` (its own `.github/workflows/agent-e2e.yml` boots a
+  pinned release server JAR; needs `OPENAI_API_KEY`/`ANTHROPIC_API_KEY`
+  secrets).
+- Agent examples resolve the package name straight to `src/agents` sources via
+  `examples/agents/tsconfig.json` paths: `npx tsx examples/agents/<file>.ts`.
+  Framework subdirs (adk/, langgraph/, openai/, vercel-ai/) install their own
+  deps (`scripts/install-example-deps.sh`); `examples/agents` is excluded from
+  the root tsconfig.
+- `AGENTSPAN_*` env vars (`AGENTSPAN_SERVER_URL`, default
+  `http://localhost:6767/api`) are the agent layer's config surface — kept
+  working as-is; `CONDUCTOR_*` aliases are a possible follow-up.
+
 ## Commands
 
 ```bash
 npm test                           # Unit tests (482+ tests)
-npm run build                      # tsup (ESM + CJS dual output)
+npm run build                      # tsup (root + 5 agent entries, ESM + CJS) + verify:dist
 npm run lint                       # ESLint
 npm run generate-openapi-layer     # Regenerate from OpenAPI spec
 
@@ -55,6 +93,10 @@ CONDUCTOR_SERVER_URL=http://localhost:8080 \
 CONDUCTOR_AUTH_KEY=key CONDUCTOR_AUTH_SECRET=secret \
 ORKES_BACKEND_VERSION=5 \
 npm run test:integration:orkes-v5
+
+# Agent e2e (requires a running agentspan server + LLM keys; CI does this
+# against the pinned release JAR — see .github/workflows/agent-e2e.yml)
+AGENTSPAN_SERVER_URL=http://localhost:8080/api npm run test:agent-e2e
 ```
 
 ## Post-Change Verification (Required)

CHANGELOG.md

@@ -9,6 +9,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **Durable AI agents** -- the Agentspan TypeScript SDK (`@conductor-oss/conductor-agent-sdk`) is merged into this package as new subpath exports: `@io-orkes/conductor-javascript/agents` (core: `Agent`, `AgentRuntime`, `tool`, guardrails, handoffs, memory, schedules, streaming, HITL), `/agents/testing`, and framework wrappers `/agents/vercel-ai`, `/agents/langgraph`, `/agents/langchain`. The root export surface is unchanged (additive minor). Docs at [docs/agents/](docs/agents/README.md); 60+ examples at [examples/agents/](examples/agents/).
+  - **Migration for `@conductor-oss/conductor-agent-sdk` users:** install `@io-orkes/conductor-javascript` and rewrite import specifiers -- `@conductor-oss/conductor-agent-sdk` becomes `@io-orkes/conductor-javascript/agents`, and the wrapper subpaths gain the `/agents` prefix (e.g. `.../vercel-ai` becomes `.../agents/vercel-ai`). APIs, behavior, and `AGENTSPAN_*` env vars are unchanged.
+  - New optional peer dependencies (all lazily resolved, install only what you use): `zod`, `zod-to-json-schema`, `ai`, `@langchain/core`, `@langchain/langgraph`. `dotenv` becomes a runtime dependency (the agent entry points load it at import time; the package `sideEffects` field allowlists `dist/agents/**` so bundlers keep that bootstrap).
 - **Canonical metrics** -- opt-in harmonized metric surface via `WORKER_CANONICAL_METRICS=true`. See [METRICS.md](METRICS.md) for the full catalog, configuration, and migration guide.
 - Bounded `uri` label on `http_api_client_request_seconds`: canonical mode uses path templates (e.g. `/workflow/{workflowId}`) instead of fully-resolved paths, preventing metric cardinality explosion from dynamic IDs.
 - `TaskPaused` event type and `PollerOptions.onPaused` callback: emitted when a poll cycle is skipped because the worker is paused. Canonical mode records `task_paused_total`; legacy mode does not (see Implementation Notes in METRICS.md).

README.md

@@ -22,6 +22,7 @@ If you find [Conductor](https://github.com/conductor-oss/conductor) useful, plea
 * [Examples](#examples)
 * [API Journey Examples](#api-journey-examples)
 * [AI & LLM Workflows](#ai--llm-workflows)
+* [Durable AI Agents](#durable-ai-agents)
 * [Documentation](#documentation)
 * [Support](#support)
 * [Frequently Asked Questions](#frequently-asked-questions)
@@ -537,11 +538,50 @@ See [examples/agentic-workflows/](examples/agentic-workflows/) for all examples.
 | [rag-workflow.ts](examples/advanced/rag-workflow.ts) | End-to-end RAG: document indexing → semantic search → LLM answer |
 | [vector-db.ts](examples/advanced/vector-db.ts) | Vector DB operations: embedding generation, storage, search |
 
+## Durable AI Agents
+
+The SDK also ships a durable agent authoring layer — long-running, plan-execute,
+and event-driven AI agents whose steps run as Conductor workflow tasks, so they
+survive restarts and are observable like any workflow. It lives under the
+`/agents` subpath export:
+
+```typescript
+import { Agent, AgentRuntime } from "@io-orkes/conductor-javascript/agents";
+
+const agent = new Agent({
+  name: "greeter",
+  model: "openai/gpt-4o-mini",
+  instructions: "You are a friendly assistant. Keep responses brief.",
+});
+
+const runtime = new AgentRuntime(); // AGENTSPAN_SERVER_URL, default http://localhost:6767/api
+try {
+  const result = await runtime.run(agent, "Hello! What can you do?");
+  result.printResult();
+} finally {
+  await runtime.shutdown();
+}
+```
+
+The layer includes tools (`tool()`, with optional Zod schemas), multi-agent
+strategies (sequential, parallel, handoffs, swarm), guardrails,
+human-in-the-loop, streaming, memory, schedules, and drop-in wrappers for
+agents written with the Vercel AI SDK, LangGraph, and LangChain
+(`/agents/vercel-ai`, `/agents/langgraph`, `/agents/langchain`), plus a
+testing toolkit (`/agents/testing`).
+
+- **Docs:** [docs/agents/](docs/agents/README.md) — start with
+  [getting-started.md](docs/agents/getting-started.md)
+- **Examples:** [examples/agents/](examples/agents/) — 60+ runnable examples,
+  from a basic agent to the full [kitchen sink](examples/agents/kitchen-sink.ts);
+  run them with `npx tsx examples/agents/01-basic-agent.ts`
+
 ## Documentation
 
 | Document | Description |
 |----------|-------------|
 | [SDK Development Guide](SDK_DEVELOPMENT.md) | Architecture, patterns, pitfalls, testing |
+| [Durable AI Agents](docs/agents/README.md) | Agent authoring layer: tools, guardrails, multi-agent, HITL, framework wrappers |
 | [Metrics Reference](METRICS.md) | Legacy and canonical Prometheus metrics with migration guide |
 | [Breaking Changes](BREAKING_CHANGES.md) | v3.x migration guide |
 | [Workflow Management](docs/api-reference/workflow-executor.md) | Start, pause, resume, terminate, retry, search, signal |