docs(agents): build clients via ApiClient.builder(), not AgentRuntime statics

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

Author: Kowser

CHANGELOG.md

@@ -12,13 +12,17 @@ All notable changes to this project will be documented in this file.
 - SSE streaming hardened: the initial connect throws `SSEUnavailableException` when the server rejects streaming (never a silently-empty stream — `stream()` degrades to status polling), `id:` frames are tracked, and mid-stream drops reconnect with a `Last-Event-ID` header; `AgentRuntime.getClient()` exposes the runtime's own `AgentClient` instance
 - Verb contract: `serve` = deploy + serve (each served agent is compiled + registered first, idempotently) with a non-blocking variant `serve(false, agents...)` that returns once workers are polling; `AgentHandle` gains the lifecycle verbs `send(message)` (now actually delivers `{"message": ...}` — it previously discarded the message), `stop()` (graceful, deterministic), `pause()`/`resume()` (un-pause; distinct from `AgentRuntime.resume(executionId, agent)` which re-attaches workers), `cancel(reason)`, and `getStatus()`
 - `RunSettings` — per-run LLM overrides (`model`, `temperature`, `maxTokens`, `reasoningEffort`, `thinkingBudgetTokens`) on `run`/`start`/`stream` and their async variants; only non-null fields override the agent (zero values apply), mutating the serialized root config so overrides flow into the LLM tasks
-- Connection environment: standard `CONDUCTOR_SERVER_URL`/`CONDUCTOR_AUTH_KEY`/`CONDUCTOR_AUTH_SECRET` now win over the legacy `AGENTSPAN_*` names (still honored as fallbacks); the default server URL is `http://localhost:8080` (was `6767`); blank variables no longer clobber the chain
+- Connection environment: standard `CONDUCTOR_SERVER_URL`/`CONDUCTOR_AUTH_KEY`/`CONDUCTOR_AUTH_SECRET` now win over the legacy `AGENTSPAN_*` names (still honored as fallbacks); the default server URL is `http://localhost:8080` (was `6767`); blank variables no longer clobber the chain. The resolution lives in the client layer — `ApiClient.builder().useEnvVariables(true)` / `new ApiClient()` — not on `AgentRuntime` (matching the Python SDK, where `AgentRuntime()` defaults to `Configuration()`); `AgentRuntime` exposes no client factories
 - `AgentConfig` knobs with lenient env parsing (invalid/empty → default): `autoStartWorkers`, `daemonWorkers`, `streamingEnabled`, `livenessEnabled`, `livenessStallSeconds`, `livenessCheckIntervalSeconds`
 - Worker credentials ride the `runtimeMetadata` wire contract: declared secret names are stamped on `TaskDef.runtimeMetadata` at (every) registration and a capable server (agentspan > 0.4.2 / conductor-oss ≥ 3.32.0-rc, conductor-oss PR #1255) delivers values on the wire-only `Task.runtimeMetadata` at poll time; dispatch is fail-closed (missing delivery → terminal failure; ambient process env is never read) — the `/workers/secrets` fetch path and its transport exceptions are deleted; see [docs/design/secret-injection-contract.md](docs/design/secret-injection-contract.md)
 - Liveness for stateful runs: a `SCHEDULED` task with zero polls beyond `livenessStallSeconds` surfaces as `WorkerStallError` from the handle's wait instead of burning the full timeout
 - Swarm hand-offs: transfer tools echo the hand-off `message`; `check_transfer` is first-wins with `transfer_message` and surfaces non-winning transfers in `dropped_transfers` (with a warning) instead of silently discarding them
 - `agent-e2e` GitHub workflow runs the e2e suites as a two-server matrix: the Conductor OSS server boot JAR `3.32.0-rc.8` (Maven Central) and the released `agentspan-server-0.4.4.jar`
 
+### Changed
+
+- `useEnvVariables(true)` (and the `new ApiClient()` no-arg constructor) no longer throws when `CONDUCTOR_SERVER_URL` is unset — it falls back to `AGENTSPAN_SERVER_URL`, then `http://localhost:8080/api`; the resolved URL is normalized to end in `/api`, and credentials gain the `AGENTSPAN_AUTH_KEY`/`AGENTSPAN_AUTH_SECRET` fallback
+
 ## [5.1.0]
 
 ### Added

docs/agents/README.md

@@ -88,7 +88,10 @@ import org.conductoross.conductor.ai.AgentConfig;
 import org.conductoross.conductor.ai.AgentRuntime;
 
 // Build the Conductor client (server URL + optional key/secret auth)…
-ApiClient client = AgentRuntime.client("http://localhost:8080", "my-key", "my-secret");
+ApiClient client = ApiClient.builder()
+        .basePath("http://localhost:8080/api")
+        .credentials("my-key", "my-secret")
+        .build();
 // …and pass worker tuning (poll interval ms, worker threads).
 AgentRuntime runtime = new AgentRuntime(client, new AgentConfig(100, 5));
 ```

docs/agents/agent-runtime-api.md

@@ -77,22 +77,26 @@ fallbacks. Invalid or empty values fall back to the default.
 
 ---
 
-## ApiClient factories
+## Building the ApiClient
 
-Build an `ApiClient` to pass to the `AgentRuntime(ApiClient)` constructor. The `ApiClient` owns server URL, auth, and HTTP timeouts.
+Build an `ApiClient` (via its own builder — client construction lives in the client layer, not on the runtime) to pass to the `AgentRuntime(ApiClient)` constructor. The `ApiClient` owns server URL, auth, and HTTP timeouts.
 
 ```java
-// From environment (same as the no-arg constructor uses internally)
-ApiClient client = AgentRuntime.clientFromEnv();
+// From environment: CONDUCTOR_SERVER_URL → AGENTSPAN_SERVER_URL → http://localhost:8080/api
+// (same resolution the no-arg AgentRuntime() constructor uses internally)
+ApiClient client = ApiClient.builder().useEnvVariables(true).build();
 
 // Unauthenticated — local dev
-ApiClient client = AgentRuntime.client("http://localhost:8080");
+ApiClient client = ApiClient.builder().basePath("http://localhost:8080/api").build();
 
 // Key/secret auth
-ApiClient client = AgentRuntime.client("http://myserver:8080", "key", "secret");
+ApiClient client = ApiClient.builder()
+        .basePath("http://myserver:8080/api")
+        .credentials("key", "secret")
+        .build();
 ```
 
-Default timeouts: `connectTimeout=10s`, `readTimeout=30s`, `writeTimeout=30s`. The `/api` base path is appended automatically.
+The no-arg `AgentRuntime()` constructor additionally applies `connectTimeout=10s`, `readTimeout=30s`, `writeTimeout=30s`. The env path normalizes the URL to end in `/api`; an explicit `basePath` is used as given.
 
 ---
 

docs/agents/api-reference.md

@@ -8,17 +8,17 @@ The SDK entry point. Thread-safe — share one instance.
 
 ```java
 // Constructors
-AgentRuntime()                                    // reads AGENTSPAN_* env vars
+AgentRuntime()                                    // client + tuning from env vars
 AgentRuntime(AgentConfig config)                  // env vars + explicit tuning
 AgentRuntime(ApiClient client)                    // explicit client
 AgentRuntime(ApiClient client, AgentConfig config)
-
-// Static factories for ApiClient
-static ApiClient clientFromEnv()
-static ApiClient client(String serverUrl)
-static ApiClient client(String serverUrl, String authKey, String authSecret)
 ```
 
+Build the `ApiClient` with its own builder (construction lives in the client
+layer): `ApiClient.builder().basePath("http://host:8080/api").credentials(key, secret).build()`,
+or `ApiClient.builder().useEnvVariables(true).build()` for the
+`CONDUCTOR_SERVER_URL` → `AGENTSPAN_SERVER_URL` → `http://localhost:8080/api` chain.
+
 ### Run
 
 ```java

docs/agents/getting-started.md

@@ -49,10 +49,13 @@ import io.orkes.conductor.client.ApiClient;
 import org.conductoross.conductor.ai.AgentRuntime;
 
 // No auth (local dev)
-ApiClient client = AgentRuntime.client("http://localhost:8080");
+ApiClient client = ApiClient.builder().basePath("http://localhost:8080/api").build();
 
 // With key/secret
-ApiClient client = AgentRuntime.client("http://myserver:8080", "key", "secret");
+ApiClient client = ApiClient.builder()
+        .basePath("http://myserver:8080/api")
+        .credentials("key", "secret")
+        .build();
 
 AgentRuntime runtime = new AgentRuntime(client);
 ```

docs/agents/spring-boot.md

@@ -125,7 +125,10 @@ public class MyAgentspanConfig {
 
     @Bean
     public ApiClient agentspanClient() {
-        return AgentRuntime.client("http://myserver:8080", "key", "secret");
+        return ApiClient.builder()
+                .basePath("http://myserver:8080/api")
+                .credentials("key", "secret")
+                .build();
     }
 }
 ```