feat(sdk): AgentClient + agent WorkflowClient live in sdk/clients, exposed via OrkesClients

Moves the agent control-plane client and the agent-flavored workflow
client from src/agents/ to src/sdk/clients/agent/ (names kept — nothing
on the root surface collides: Conductor's workflow client is
WorkflowExecutor). OrkesClients gains getAgentClient() and
getAgentWorkflowClient(); AgentClient's constructor accepts an optional
pre-built client ((AgentConfigOptions & {client?}) | AgentConfig) which
pre-seeds the memoized promise, so the factory path reuses one Conductor
client across workflow + schedule surfaces. The /agent/* raw transport
and JWT mint path are unchanged; decodeJwtExp stays exported.

Cycle guard: the moved files import createConductorClient and the agent
domain modules via deep paths, never the sdk barrel; madge reports no
new cycles (the AgentClient↔WorkflowClient type-only edge predates the
move). The ./agents subpath re-exports everything from the new homes —
its surface is unchanged. The enriched ConductorClient type is not
re-exported at root (the deprecated bare alias keeps that name).

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

Author: Kowser

src/agents/__tests__/agent-client-auth.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, jest, beforeEach, afterEach } from "@jest/globals";
-import { AgentClient, decodeJwtExp } from "../agent-client.js";
+import { AgentClient, decodeJwtExp } from "../../sdk/clients/agent/AgentClient.js";
 
 /** Build a minimal JWT with the given `exp` (epoch seconds). */
 function makeJwt(exp: number): string {

src/agents/index.ts

@@ -146,10 +146,10 @@ export {
 } from "./runtime.js";
 
 // ── Control-plane / Workflow clients ────────────────────
-export type { ClientHandle } from "./agent-client.js";
-export { AgentClient, decodeJwtExp } from "./agent-client.js";
-export type { WorkflowExecution, WorkflowTokenUsage } from "./workflow-client.js";
-export { WorkflowClient } from "./workflow-client.js";
+export type { ClientHandle, AgentClientOptions } from "../sdk/clients/agent/AgentClient.js";
+export { AgentClient, decodeJwtExp } from "../sdk/clients/agent/AgentClient.js";
+export type { WorkflowExecution, WorkflowTokenUsage } from "../sdk/clients/agent/WorkflowClient.js";
+export { WorkflowClient } from "../sdk/clients/agent/WorkflowClient.js";
 
 // ── Scheduling ──────────────────────────────────────────
 export {

src/agents/runtime.ts

@@ -24,8 +24,8 @@ import type { HandoffContext } from "./handoff.js";
 import { detectFramework } from "./frameworks/detect.js";
 import type { Schedule } from "../sdk/clients/agent/schedule.js";
 import type { SchedulerClient } from "../sdk/clients/scheduler/SchedulerClient.js";
-import { AgentClient } from "./agent-client.js";
-import { WorkflowClient } from "./workflow-client.js";
+import { AgentClient } from "../sdk/clients/agent/AgentClient.js";
+import { WorkflowClient } from "../sdk/clients/agent/WorkflowClient.js";
 import { serializeFrameworkAgent } from "./frameworks/serializer.js";
 import { serializeLangGraph } from "./frameworks/langgraph-serializer.js";
 import { serializeLangChain } from "./frameworks/langchain-serializer.js";

src/sdk/OrkesClients.ts

@@ -1,6 +1,9 @@
 import type { Client } from "../open-api";
 import type { OrkesApiConfig } from "./types";
 import { createConductorClient } from "./createConductorClient";
+import { AgentClient } from "./clients/agent/AgentClient";
+import type { ConductorClient } from "./clients/agent/AgentClient";
+import { WorkflowClient as AgentWorkflowClient } from "./clients/agent/WorkflowClient";
 import { ApplicationClient } from "./clients/application";
 import { AuthorizationClient } from "./clients/authorization";
 import { EventClient } from "./clients/event";
@@ -64,6 +67,25 @@ export class OrkesClients {
     return new SchedulerClient(this._client);
   }
 
+  /**
+   * Agent control-plane client (`/agent/*`: run/deploy/schedule/status),
+   * reusing this factory's Conductor client for the Conductor-side calls.
+   * The client must have been built by `createConductorClient` (always true
+   * for `OrkesClients.from(...)`).
+   */
+  getAgentClient(): AgentClient {
+    return new AgentClient({ client: this._client as ConductorClient });
+  }
+
+  /**
+   * Agent-flavored workflow reads (agent-execution 404 fallback + token
+   * rollup) — the same instance `getAgentClient().workflows` returns. For
+   * general workflow operations use `getWorkflowClient()` (WorkflowExecutor).
+   */
+  getAgentWorkflowClient(): AgentWorkflowClient {
+    return this.getAgentClient().workflows;
+  }
+
   getSecretClient(): SecretClient {
     return new SecretClient(this._client);
   }

src/sdk/__tests__/OrkesClients.agent.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from "@jest/globals";
+import { OrkesClients } from "../OrkesClients";
+import { AgentClient } from "../clients/agent/AgentClient";
+import { WorkflowClient } from "../clients/agent/WorkflowClient";
+import { SchedulerClient } from "../clients/scheduler/SchedulerClient";
+import type { Client } from "../../open-api";
+
+const fakeClient = { getConfig: () => ({}) } as unknown as Client;
+
+describe("OrkesClients agent getters", () => {
+  it("getAgentClient returns an AgentClient reusing the factory's client", async () => {
+    const clients = new OrkesClients(fakeClient);
+    const agentClient = clients.getAgentClient();
+
+    expect(agentClient).toBeInstanceOf(AgentClient);
+    // The injected client is pre-seeded — getClient() must resolve to the
+    // exact instance, not build a fresh one via createConductorClient.
+    await expect(agentClient.getClient()).resolves.toBe(fakeClient);
+  });
+
+  it("getAgentWorkflowClient matches getAgentClient().workflows behavior", () => {
+    const clients = new OrkesClients(fakeClient);
+    const viaFactory = clients.getAgentWorkflowClient();
+    const viaAgentClient = clients.getAgentClient().workflows;
+
+    expect(viaFactory).toBeInstanceOf(WorkflowClient);
+    expect(viaAgentClient).toBeInstanceOf(WorkflowClient);
+  });
+
+  it("agent schedules ride the injected client too", () => {
+    const clients = new OrkesClients(fakeClient);
+    expect(clients.getAgentClient().schedules).toBeInstanceOf(SchedulerClient);
+  });
+});

src/agents/agent-client.ts src/sdk/clients/agent/AgentClient.tssrc/agents/agent-client.ts renamed to src/sdk/clients/agent/AgentClient.ts

@@ -20,22 +20,22 @@
  * carry that JWT as `X-Authorization` (see {@link _authHeaders}).
  */
 
-import { createConductorClient } from "../sdk";
-import type { AgentResult, AgentStatus, DeploymentInfo, RunOptions } from "./types.js";
-import { AgentAPIError } from "./errors.js";
-import { AgentConfig } from "./config.js";
-import type { AgentConfigOptions } from "./config.js";
-import { Agent } from "./agent.js";
-import { AgentConfigSerializer } from "./serializer.js";
-import { detectFramework } from "./frameworks/detect.js";
-import { serializeFrameworkAgent } from "./frameworks/serializer.js";
-import { serializeLangGraph } from "./frameworks/langgraph-serializer.js";
-import { serializeLangChain } from "./frameworks/langchain-serializer.js";
-import { Schedule } from "../sdk/clients/agent/schedule.js";
-import { SchedulerClient } from "../sdk/clients/scheduler/SchedulerClient.js";
-import { WorkflowClient } from "./workflow-client.js";
-import { makeAgentResult, TERMINAL_STATUSES } from "./result.js";
-import { AgentStream } from "./stream.js";
+import { createConductorClient } from "../../createConductorClient";
+import type { AgentResult, AgentStatus, DeploymentInfo, RunOptions } from "../../../agents/types.js";
+import { AgentAPIError } from "../../../agents/errors.js";
+import { AgentConfig } from "../../../agents/config.js";
+import type { AgentConfigOptions } from "../../../agents/config.js";
+import { Agent } from "../../../agents/agent.js";
+import { AgentConfigSerializer } from "../../../agents/serializer.js";
+import { detectFramework } from "../../../agents/frameworks/detect.js";
+import { serializeFrameworkAgent } from "../../../agents/frameworks/serializer.js";
+import { serializeLangGraph } from "../../../agents/frameworks/langgraph-serializer.js";
+import { serializeLangChain } from "../../../agents/frameworks/langchain-serializer.js";
+import { Schedule } from "./schedule.js";
+import { SchedulerClient } from "../scheduler/SchedulerClient.js";
+import { WorkflowClient } from "./WorkflowClient.js";
+import { makeAgentResult, TERMINAL_STATUSES } from "../../../agents/result.js";
+import { AgentStream } from "../../../agents/stream.js";
 
 /**
  * The resource client returned by `createConductorClient`. The package's
@@ -77,6 +77,16 @@ export function decodeJwtExp(token: string): number {
 /** Default client-side ceiling for {@link AgentClient.run}/`wait()` when no `timeoutSeconds` is given. */
 const DEFAULT_WAIT_MS = 600_000; // 10 min — mirrors the C# SDK's HttpClient cap
 
+/**
+ * {@link AgentClient} construction options: the agent config plus an optional
+ * pre-built Conductor client to reuse (as handed out by `OrkesClients`). The
+ * injected client must originate from `createConductorClient` — it carries
+ * the attached `*Resource` members the workflow client reads.
+ */
+export type AgentClientOptions = AgentConfigOptions & {
+  client?: ConductorClient;
+};
+
 export class AgentClient {
   readonly config: AgentConfig;
 
@@ -90,8 +100,16 @@ export class AgentClient {
   private _tokenExp = 0; // epoch seconds; 0 == "no decodable expiry" (not cached)
   private _mintPromise?: Promise<string>; // single-flight guard for concurrent mints
 
-  constructor(options?: AgentConfigOptions | AgentConfig) {
-    this.config = options instanceof AgentConfig ? options : new AgentConfig(options);
+  constructor(options?: AgentClientOptions | AgentConfig) {
+    if (options instanceof AgentConfig) {
+      this.config = options;
+    } else {
+      const { client, ...configOptions } = options ?? {};
+      this.config = new AgentConfig(configOptions);
+      // Pre-seed the memoized promise; getClient() then reuses the injected
+      // client instead of building its own via createConductorClient.
+      if (client) this._clientPromise = Promise.resolve(client);
+    }
     this.serializer = new AgentConfigSerializer();
   }
 
@@ -362,7 +380,7 @@ export class AgentClient {
     if (opts?.credentials) payload.credentials = opts.credentials;
     if (opts?.context) payload.context = opts.context;
     if (opts?.plan !== undefined) {
-      const { coercePlan } = await import("./plans.js");
+      const { coercePlan } = await import("../../../agents/plans.js");
       payload.static_plan = coercePlan(opts.plan as Parameters<typeof coercePlan>[0]);
     }
 

src/agents/workflow-client.ts src/sdk/clients/agent/WorkflowClient.tssrc/agents/workflow-client.ts renamed to src/sdk/clients/agent/WorkflowClient.ts

@@ -8,7 +8,7 @@
  * shared Conductor client rather than ad-hoc HTTP on the runtime.
  */
 
-import type { ConductorClient } from "./agent-client.js";
+import type { ConductorClient } from "./AgentClient.js";
 
 /** Conductor workflow shape (subset we read). */
 export interface WorkflowExecution {

src/sdk/clients/agent/index.ts

@@ -1,3 +1,10 @@
+export { AgentClient, decodeJwtExp } from "./AgentClient";
+// NOTE: the enriched `ConductorClient` type stays on the module (import it
+// from "./AgentClient") — re-exporting it here would collide with the
+// deprecated bare `ConductorClient = Client` alias on the root barrel.
+export type { AgentClientOptions, ClientHandle } from "./AgentClient";
+export { WorkflowClient } from "./WorkflowClient";
+export type { WorkflowExecution, WorkflowTokenUsage } from "./WorkflowClient";
 export {
   Schedule,
   ScheduleError,