Feat/sdk parity clients and docs - #290
Closed
v1r3n wants to merge 42 commits into
Closed
Conversation
…xample modernization Bring the Python, TypeScript, and C# SDKs to parity with the Java reference, add end-user docs to every SDK, and modernize all examples to the current API. SDK feature parity (closed all conformance gaps): - C#: TextGate, handoff triggers (OnTextMention/OnToolResult/OnCondition), callable dynamic instructions, composable CallbackHandler + agent/tool callbacks, event-targeted HITL (ApproveAsync(event)/WaitUntilWaitingAsync), worker-tuning env vars, [AgentDef] + Agent.FromInstance. - Python: event-targeted HITL (approve/reject/respond(event=...)), Agent.from_instance. - TypeScript: waitForMessageTool (pull_workflow_messages). Control-plane client (rename + run/schedule, matching Java's AgentClient): - Python & C#: AgentHttpClient -> AgentClient (C# public; Python keeps a back-compat alias); add control-plane run/start/deploy/schedule + Schedules; runtime exposes the client. - TypeScript: extract AgentClient + WorkflowClient on @io-orkes/conductor-javascript. Orkes JWT auth on /agent/* (was the original "concrete bug"): all SDKs now mint a JWT (X-Authorization) from key/secret and cache it — TS via the conductor client's tokenResource, C# via a new AgentAuthHandler. (Java/Python already did.) Docs: new docs/ in Python, C#, TypeScript and an expanded Java docs/ — getting started (<30s), writing agents, framework agents, advanced, API reference; plus design docs (sdk-design-guide, sdk-conformance, runtime-init-alignment). Fixed real API errors in existing Java docs and the stale Java/C# READMEs. Fixes + production-readiness: - Restore the lost agentspan.agents.runtime._liveness module (+ unit test); result.py imported it but a partial merge had dropped the file. - Fix test_guardrail_matrix collection (wrong factory/tool names). - TS e2e credential helper writes via /api/secrets (was shelling to a CLI bound to a stale managed-server port). - Modernize all examples to compile/import/build green (TS tsc 0 errors, Python imports clean, C# 175 projects build, Java compiles); quickstart run_all exposes prompt/agent. Verified: Python unit 1687, TS unit 830, C# unit 23 + e2e 135, plus targeted Py/TS e2e — all passing.
…yPI conductor-ai-sdk) Package dir src/agentspan → src/conductor/ai with a pkgutil extend_path shim so 'conductor.ai' and conductor-python's 'conductor.client' coexist. ~1,761 import-path rewrites across 444 files; pyproject entry-point RHS + coverage source updated (script command names kept). AGENTSPAN_* env, __agentspan_* wire keys, and the agentspan CLI/binary strings preserved. Verified: import conductor.ai + conductor.client coexist; unit 1687 passed; ruff clean.
…nductor-ai-sdk package.json name + all import specifiers (incl. subpaths) + vitest alias + examples/tsconfig paths + examples dep + lockfile. src uses relative imports. AGENTSPAN_* env and agentspan CLI refs preserved. Verified: tsc 0 errors, build, unit 830, examples tsc 0 errors.
…dirs (NuGet conductor-ai-sdk)
src dirs/csprojs and Agentspan.sln → Conductor.AI*; RootNamespace/AssemblyName, ~76 namespace decls, ~455 using directives, 250 ProjectReference paths, 86 example RootNamespaces. Adapter PackageIds: conductor-ai-sdk-{openai,google-adk,semantic-kernel}. Test assembly name AgentspanE2eTests + matching InternalsVisibleTo preserved; AGENTSPAN_* env, agentspan.agents ActivitySource, agentspan_code_ prefix preserved. Verified: solution builds 0 errors, 175 example projects build, 158 tests pass.
…fixes - TS package.json: merge the duplicate `overrides` keys (the second silently overwrote the first via JSON last-key-wins), restoring the dropped `undici@^7.28.0` security pin from ec26c1c. Verified undici@7.28.0 now resolves in the tree. (Also fixes the stale @agentspan-ai/sdk ref the rename left in yarn.lock.) - JWT exp contract unified across SDKs: a token with no decodable `exp` is no longer cached forever (TS + Python now match C#'s refresh-on-undecodable). Added a Python test asserting opaque tokens are re-minted, not cached. - TS auth: mint failures now surface (AgentAPIError) instead of silently downgrading to an anonymous request that 401s with the cause erased; the no-creds OSS anonymous path is preserved. Token mint is single-flight to avoid a concurrent-first-call stampede. - TS AgentClient.wait(): bounded by a client-side deadline (from RunOptions.timeoutSeconds + grace, else a 600s default) instead of an unbounded poll; AbortSignal still overrides. - TS WorkflowClient.getWorkflow: fall back to the agent-execution endpoint only on 404, so a transient 5xx propagates with its real status. - Surface previously-silent swallows: TS getExecution / token-usage reads log at debug; C# CancelAgentAsync traces a non-success status (leaked/billable exec). Verified: TS tsc/build/unit 830 + examples 0 errors + undici pin applied; Python unit 1688 (+1); C# solution builds + auth suite 4.
…eep conductor.ai namespace) Coordinate-only rename conductor-ai-sdk -> conductor-agent-sdk: Java Maven artifact (+ -spring), PyPI name, C# NuGet PackageId (+ -openai/-google-adk/-semantic-kernel adapters), and the TS npm name (which is the import specifier, so 269 import refs + vitest alias + examples tsconfig + lockfiles updated). Code import namespaces are UNCHANGED (conductor.ai / Conductor.AI / org.conductoross.conductor.ai). Docs/READMEs: SDK product name -> 'Conductor Agent SDK', install commands updated, and stale src/Agentspan/ paths + AgentHttpClient.cs struct-tree ref fixed. Runtime contracts unchanged (AGENTSPAN_* env, agentspan CLI/server, agentspan.* URLs). Verified: TS tsc/build/unit 830 + examples 0; Python conductor.ai imports + uv sync; C# solution builds; Java examples compile.
Update the registry-visible descriptions (npm/NuGet/PyPI) from 'Agentspan SDK' to 'Conductor Agent SDK', matching the conductor-agent-sdk coordinate. Left intentionally: csproj <Authors>Agentspan</Authors> (publishing entity), AgentspanE2eTests assembly name, and pytest markers referencing the Agentspan server / AGENTSPAN_* env (runtime contracts).
…r Agent" #2: TypeScript package version 1.0.0 -> 0.1.0 (coordinated 0.1.0 first release across Java/Python/C#/TS under the conductor-agent-sdk name). #3: rebrand product/SDK prose 'Agentspan' -> 'Conductor Agent' across all four SDKs' docs + READMEs (38 edits, reworded to avoid awkward doubling), plus the mkdocs site title and the agent-schema.json title. Preserved (real runtime/contract names): 'Agentspan server', secrets store, AGENTSPAN_* env, the agentspan CLI, agentspan.dev/.ai platform links, code symbols (AgentspanJson/Error/Config), AgentspanE2eTests, and copyright. Also corrected 2 stale post-rename refs (C# Package/Namespace + src path).
…r-compose Consistency review of server/: - README run commands pointed at build/libs/agentspan-runtime.jar, but the multi-module build outputs to conductor-agentspan-server/build/libs/ (matches CI and the Dockerfile). Fixed all 6 occurrences. - README project-structure tree showed a single-module layout; replaced with the actual two-module layout (conductor-agentspan library + conductor-agentspan-server runnable). - README API-docs regen block referenced non-existent paths (ui/api-docs-ui/..., ./docs/regenerate.sh); corrected to ui/api-docs.json + ui/regenerate.sh + ui/src/docs/. - README Python RAG snippet imported from the old 'agentspan.agents' namespace; now 'conductor.ai.agents'. - Noted the docker build must run from the repo root. - application-postgres.properties connected to db 'coss' with postgres/postgres, but docker-compose.yml provisions db/user/password 'conductor' and the README documents the same. 'coss' was referenced nowhere else and CI never uses this profile, so aligned the profile defaults to the compose file — the documented 'docker compose up -d' + --spring.profiles.active=postgres flow now connects out of the box (still env-overridable).
docs/ had design docs interleaved with user docs. Moved all design material
into the top-level design/ folder so docs/ contains only user-facing docs,
concepts, examples, and references (the set published by mkdocs.yml).
Moved (git mv, history preserved):
- docs/sdk-design/** -> design/sdk-design/ (SDK design guide, conformance,
per-language translation guides,
kitchen-sink spec, dated design docs)
- docs/superpowers/** -> design/superpowers/ (e2e-validation plans + specs)
- docs/typescript-sdk/plan.md -> design/sdk-design/typescript-sdk-plan.md
- docs/python-sdk/{design,requirements,validation-design,compilation-comparison,
sentinel-agents,next-steps}.md -> design/python-sdk/ (design/spec/roadmap docs;
user references like api-reference,
memory, skills, streaming stay in docs/)
- docs/agentspan-as-a-library.md -> design/ ("Module Split & SPI Design")
- docs/local-code-execution-design.md -> design/
Reference integrity:
- Fixed all move-caused markdown links (verified with a link-checker: 0 dangling
links introduced; remaining reports are pre-existing site-absolute /docs/ URLs
and legacy SDK-doc links, untouched).
- Rewrote repo-relative path references in design docs (docs/sdk-design/ -> design/sdk-design/,
docs/superpowers/ -> design/superpowers/) and the two shipped kitchen-sink example comments.
- Restored a broken anchor in design/secrets.md (#7 separator had been dropped).
mkdocs.yml: dropped now-stale exclude_docs/not_in_nav entries for the moved trees;
added ocg-agent-flow.md (unpublished feature doc still in docs/) so strict builds stay clean.
All 46 nav targets verified present.
Single-source the SDK docs in sdk/<lang>/docs and surface them in the root mkdocs site, matching the existing docs/java-sdk -> ../sdk/java/docs pattern. - docs/typescript-sdk -> ../sdk/typescript/docs (new symlink) - docs/csharp-sdk -> ../sdk/csharp/docs (new symlink) - docs/python-sdk: retired the stale legacy copy (6 pages on the old `agentspan` namespace, ~3760 lines, unpublished) and replaced it with a symlink -> ../sdk/python/docs (the rebranded conductor.ai set). Per decision: retire legacy. mkdocs.yml: - Added Python SDK, TypeScript SDK, and C# SDK nav sections (Overview, Getting Started, Writing Agents, Framework Agents, Advanced, API Reference). - Completed the Java SDK nav: added the 6 pages that existed in sdk/java/docs but were never linked (Stateful, Structured Output, Streaming & HITL, Callbacks, Deploy/Serve/Run, LangGraph4j). - Dropped python-sdk/** from exclude_docs/not_in_nav (now published). Validated structurally (mkdocs not installed locally): all 70 nav targets resolve through the symlinks, 0 orphan .md (none un-navved/un-excluded), and the python/ts/csharp docs have no docs-tree-escaping relative links. Recommend a `mkdocs build --strict` in CI to fully confirm.
…docs/
- Removed the redundant standalone Java docs sub-site config
(sdk/java/docs/mkdocs.yml). The root mkdocs.yml is now the single config for
all docs; CI (docs.yml) only ever built the root site, and Java is already
included via the docs/java-sdk symlink + root nav.
- Moved design/analysis artifacts out of docs/ into design/ (they were
unpublished and on the dead `agentspan` namespace):
docs/guardrails.md -> design/guardrails-analysis.md ("Conceptual Analysis & SDK Review")
docs/langchain-integration.md -> design/langchain-integration.md (platform translation explainer)
docs/langgraph-integration.md -> design/langgraph-integration.md (platform translation explainer)
docs/ocg-agent-flow.md -> design/ocg-agent-flow.md (stale feature spec)
Fixed the one cross-link (ocg -> Python SDK api-reference) and removed the
dangling OCG bullet from docs/index.md.
- Dropped the now-empty exclude_docs/not_in_nav blocks from mkdocs.yml.
Result: docs/ holds only user docs + the four SDK doc symlinks; design material
lives in design/. Validated: single mkdocs.yml, all 70 nav targets resolve,
0 orphan .md, no move-caused broken links.
Resolved conflicts: - design/agentspan-validation-readiness.md: main added it (with agentspan-as-a-library.md) under server/docs/; both are design/assessment artifacts, so kept in design/ alongside agentspan-as-a-library.md (which merged there automatically as identical content). - sdk/python/src/conductor/ai/__main__.py: main added src/agentspan/__main__.py; placed it at the renamed conductor/ai path and updated namespace to conductor.ai.cli. - sdk/typescript/tests/e2e/test_suite17_guardrail_matrix.test.ts: kept the renamed package specifier @conductoross/conductor-agent-sdk. Post-merge drift fixed: two new main test files (test_main_entrypoint.py, test_cli_binary.py) used the old agentspan import namespace -> updated module paths to conductor.ai.cli / conductor.ai.__main__ (binary name 'agentspan', AGENTSPAN_* and error strings preserved). Validated: 6/6 affected python tests pass; conductor.ai imports; pyproject/package.json rename intact (conductor-agent-sdk / @conductoross/conductor-agent-sdk); single root mkdocs.yml with 70 nav targets, 0 orphans.
Three CI jobs failed after merging main into this branch: 1. Build source docs (mkdocs --strict): docs/scheduling.md linked to ../design/scheduling.md and ../design/plans/..., which live outside docs_dir, so mkdocs aborted with 2 strict warnings. Repointed both at the GitHub source URLs (design/ is intentionally not part of the published site). Verified locally: `mkdocs build --strict` now exits 0. 2. csharp-sdk-tests: our rename had renamed Agentspan.sln -> Conductor.AI.sln, but ci.yml hardcodes `dotnet build Agentspan.sln` (workflow not editable here). The .sln filename is build tooling, not a published coordinate/namespace, so renamed it back to Agentspan.sln (consistent with keeping AgentspanE2eTests / the agentspan CLI). Also fixed the two Conductor.AI.sln refs in the C# README. Verified: `dotnet build Agentspan.sln -c Release` succeeds, 0 errors. 3. typescript-unit-tests: the `npm audit --omit=dev --audit-level=high` gate failed. Our branch's package-lock.json was stale (langsmith 0.3.87, ai 4.3.19, @ai-sdk/provider-utils 2.2.8 — all with recent high-severity advisories), while main had already moved to patched versions (0.7.1 / 6.0.146 / 4.0.22). Re-based the lockfile on main's and reconciled with our package.json (name/version/ overrides). Verified: audit gate exits 0 (0 vulns), build + tsc + 830 unit tests pass.
… ci consistency The previous lockfile fix was inconsistent with the examples workspace (npm ci rejected it). Root cause: a fresh resolve from this branch's package.json picked vulnerable transitive versions (langsmith <=0.5.26, pulling @langchain/core <0.3.80). - Removed the redundant 'undici: ^7.28.0' override (the tree already resolves undici 7.28.0 without it, same as main). - Added a 'langsmith: >=0.5.27' override (langsmith is transitive, so overridable; @langchain/core is a direct dep and can't be overridden). This resolves langsmith to 0.7.12 and lets @langchain/core dedupe to the patched 0.3.80. - Regenerated a clean, self-consistent package-lock.json. Verified locally (exact CI steps): npm ci EXIT 0, npm audit --omit=dev --audit-level=high EXIT 0 (0 vulns), build, tsc, 830 unit tests, and the examples tsc gate all pass.
…gn docs
Removed 10 docs that are process checks, implementation tracking, test output,
or superseded requirements — not final design:
- python-sdk/compilation-comparison.md (local-vs-server parity test report)
- agentspan-validation-readiness.md (validation scope/gaps working notes)
- sdk-design/sdk-conformance.md (SDK conformance checklist)
- sdk-design/2026-03-30-agent-skills-plan.md (implementation plan, 49 checkboxes)
- sdk-design/typescript-sdk-plan.md (JS SDK implementation plan)
- sdk-design/runtime-init-alignment.md ("proposed — no code changed yet" review)
- lease-extension-and-ts-sdk-migration.md (completed-migration plan/tracking)
- sdk-design/2026-03-23-agent-signals-requirements.md (superseded by agent-signals-design.md)
- python-sdk/requirements.md (superseded by python-sdk/design.md)
- python-sdk/next-steps.md (v0.0.1 roadmap/TODO)
Also dropped the now-dangling **Requirements:** pointer in agent-signals-design.md.
All final design docs (architecture, specs, contracts, translation guides, as-built
designs) are kept.
Removed design/plans/ (14 "…Implementation Plan" docs, 21–96 checkboxes each) and design/superpowers/plans/2026-04-07-e2e-validation-framework.md — all feature- implementation tracking, not final design. Kept the matching design specs (design/specs/* and design/superpowers/specs/…-design.md). Also dropped the now-dead implementation-plan link from docs/scheduling.md (the design-rationale link is retained).
Ensure the implementation-plan link in docs/scheduling.md and the Requirements pointer in agent-signals-design.md are actually removed (earlier commits didn't capture these edits due to a working-tree sync lag).
Rename spine docs to canonical names + group kept references:
- spines -> agentspan-design / api-design / sdk-design / guardrails-design /
tool-execution-and-credentials-design / sentinel-agents / framework-integration
- per-language idiom guides -> sdk-design/languages/
- python-sdk/design + typescript-sdk-design -> sdk-design/{python,typescript}-implementation.md
- validation docs -> design/validation/
Content merge of secondary sources follows per-bucket.
Merged ~29 overlapping design docs into 8 canonical, deduplicated docs and
dropped 3 legacy/superseded specs. Each consolidated doc opens with a clear
title + scope + "Status: Consolidated 2026-06-26".
8 canonical docs:
- agentspan-design.md (a) platform architecture + server features (HITL/DAG/signals/CLI deploy)
- api-design.md (c) api_tool + AgentConfig wire schema + API conventions
- sdk-design.md (d) multi-language SDK authoring (+ links to languages/, kitchen-sink, impl refs)
- guardrails-design.md (e) API + Conductor compilation + rationale
- tool-execution-and-credentials-design.md (f) code execution + secrets (as-built) + injection contract + UI
- sentinel-agents.md (g) scheduling (shipped) + trigger roadmap
- stateful-agents.md (b) task-to-domain routing (kept; header only)
- framework-integration.md (h) langgraph/langchain/openai/adk/claude/ocg passthrough
Kept as references: design/sdk-design/languages/{6}, kitchen-sink.md,
{python,typescript}-implementation.md, and design/validation/{3}.
Dropped as superseded: langgraph-langchain-support-design, credential-management-design,
universal-credential-support-design.
Fixes: repointed cross-links to merged docs; corrected package coordinate
conductor-ai-sdk -> conductor-agent-sdk in sentinel-agents.md; updated the
design-rationale link in docs/scheduling.md to design/sentinel-agents.md.
…uages/
Refresh the two existing per-SDK implementation write-ups, add Java + C#, and
group all four under design/sdk-design/languages/ as the canonical
"reference implementation" docs (how each shipped SDK is built internally).
- python-implementation.md — de-staled: agentspan -> conductor.ai.agents,
conductor-agent-sdk, 1701 tests, py 3.10-3.13; corrected to always-server-side compile.
- typescript-implementation.md — de-staled (@conductoross/conductor-agent-sdk; corrected
the @io-orkes TaskManager wrapping) and trimmed the completed rewrite-plan sections
(Implementation Order / Success Criteria / Acceptance Test); 2166 -> ~340 lines.
- java-implementation.md (new) — AgentRuntime/AgentClient, WorkerManager + lease-extension,
@Tool->worker, SseClient, ThreadLocal credential injection, -spring autoconfig.
- csharp-implementation.md (new) — Conductor.AI core + OpenAI/GoogleADK/SemanticKernel
adapters, async runtime, WorkerPollLoop dispatch, JWT auth, conductor-csharp dependency.
Wiring: each shipped-SDK idiom guide (languages/{java,typescript,csharp}.md) now links its
**As-built internals** doc; sdk-design.md references all four. Also fixed the dangling
`Base Spec` refs to the deleted multi-language-sdk-design.md across the idiom guides +
kitchen-sink.md (-> sdk-design.md). Test counts in java/csharp flagged in-doc as approximate.
Mirror the reference-implementation structure for design/validation/: one "Validation & E2E" doc per SDK + a cross-cutting methodology overview. - README.md (was e2e-validation-framework-design.md) — rewritten as the methodology overview + index: the two approaches (deterministic e2e [no LLM judge, per CLAUDE.md] in all 4 SDKs; examples-quality framework with LLM judge in py/ts), shared harness, per-SDK table. - python-validation.md (was python-validation-design.md) — refreshed; folded in the sdk/python/e2e/ suites (Suite 1–24) alongside the validation framework; fixed the dead root e2e-orchestrator.sh ref to the real e2e/orchestrator.sh + `uv run pytest e2e/`. - typescript-validation.md (was typescript-validation-framework-design.md) — refreshed; de-staled to @conductoross/conductor-agent-sdk; added the tests/e2e/ vitest suites + CI. - java-validation.md (new) — sdk/java/e2e JUnit5 suites, -Pe2e gate, CI; deterministic-only (no quality framework). Captures the stale-jar gotcha. - csharp-validation.md (new) — AgentspanE2eTests (xUnit, SkippableFact server-gating) + 90_GuardrailE2eTests, CI; deterministic-only. Wiring: each languages/<lang>-implementation.md Testing section links its validation doc; sdk-design.md points to the validation overview + per-SDK docs. Java/C# note no examples- quality framework; grep-based test counts flagged approximate in-doc.
Audited all canonical design docs against the SDK + server source (3 passes:
audit → fix → re-verify). Removed proposed/draft content that had been written as
if shipped, fixed wrong API/endpoint/coordinate details, and added reality notes
for cross-SDK gaps.
agentspan-design.md: agent-signals rewritten to the real single `_signal_injection`
variable + one POST /{id}/signal endpoint (deleted the fictional state machine);
HITL rewritten to the real "waiting" SSE + POST /{id}/respond (removed the
nonexistent hitl registry/GET /api/agent/hitl); DAG path fixed to POST /api/agent/execution;
SPI list cut to the real 5 (dropped invented ExecutionTokenIssuer/MasterKeyProvider;
ExecutionTokenService is concrete); dropped invented per-tool-timeout override,
agentspan.context.maxSizeBytes property, and signalMode.
tool-execution-and-credentials-design.md: Credential* naming + single credentials_store
table (removed invented secret_tags/secret_disclosures/users/api_keys); masking/disclosure
marked Enterprise (OSS masker is no-op); UI rewritten to the real /secrets page (removed
the /credentials login narrative); env-seeder count ~35; per-SDK code-executor reality
(Python all-4, TS Jupyter stub, Java Docker-only, C# none); fixed hallucinated Java
accessor -> real ToolContext.getCredential / internal.CredentialContext.
guardrails-design.md: tool guardrails documented as BOTH in-process + server-compiled gate
tasks; default on_fail divergence (Python/Java retry, TS raise, C# mixed); max_retries min 1;
custom path output.result.on_fail; added max_tokens; human+input is Python-only.
framework-integration.md: OCG max_results/traversal_level corrected to fixed 100/1; Claude
package claude-code-sdk / import claude_code_sdk; passthrough injects child tasks; per-SDK
detection + availability (Claude=Python-only, Vercel AI=TS-only, OCG=Python-only).
api-design.md: claude-code native routing (detect_framework returns None for native Agents);
toolType literal api (not apiTool); api_tool missing in Java, claude-code only Python/TS.
sdk-design.md: env var AGENTSPAN_SECRET_STRICT_MODE; softened "~89 features"; SDK parity-status
note (SemanticMemory/code-exec/api_tool/external-guardrail gaps in Java/C#); clarified only
4 SDKs ship (Go/Kotlin/Ruby are guide-only).
sentinel-agents.md: removed nonexistent schedules.executions()/runNowAndWait; runNow takes
ScheduleInfo in Java/C#; namespace fixes.
stateful-agents.md: noted Java/C# stateful doc-comments describe the wrong semantics.
sdk-design/languages/java.md: Maven coordinates org.conductoross.conductor:conductor-agent-sdk.
Global: replaced stale `from agentspan.agents` examples with `conductor.ai.agents`
(kept AGENTSPAN_* env, the agentspan CLI, and the server's dev.agentspan.* packages).
Implement the gaps + contract inconsistencies found in the design review.
Each fix is test-first (deterministic unit tests, no LLM/server). All SDKs green:
Python 1695, TypeScript 844, Java (gradle test ok), C# 25 (+0 build errors).
Feature gaps:
- Java: add ApiTool (toolType "api", maxTools default 64, ${NAME} cred validation) and
SemanticMemory (client-side keyword store, parity with Python/C#).
- C#: add ConversationMemory, DockerCodeExecutor, Guardrail.External, and a tier-1
credential accessor (ToolContext.GetCredential / Secrets.Get via AsyncLocal scope set
by WorkerManager); add ${NAME} credential validation to ApiTools.Create.
Contract standardization:
- Guardrail default on_fail -> RAISE across ALL SDKs (was retry in Python/Java, mixed in
C#). Deliberate behavior change to the reference SDK for consistency.
- schedules.runNow: name-keyed everywhere + a synchronous wait variant everywhere
(Java runNow(name)/runNowAndWait, C# RunNowAsync(name)/(name,wait), TS runNow(name,{wait})
/runNowAndWait) mirroring Python run_now(name, wait=True).
- human+input guardrail validation (reject on_fail=human with position=input) now enforced
in TS/Java/C# (was Python-only).
- agent-schema.json: add `api` to the toolType description.
Note: SemanticMemory is a client-side keyword-overlap store (not a vector-DB/embedding
feature) — matched to the actual Python/C# reference.
Update the design docs to match the code after this round of fixes:
- guardrails-design: default on_fail now uniform `raise` across all 4 SDKs;
human+input validation now enforced in all 4 (was Python-only).
- api-design: api_tool now in all 4 SDKs (Java added); schema toolType lists `api`.
- tool-execution-and-credentials: C# code-exec matrix now has Docker
(DockerCodeExecutor); tier-1 credential accessor now in all 4 (C# added
ToolContext.GetCredential / Secrets.Get). Kept still-open notes.
- sentinel-agents: runNow name-keyed + wait variant in all 4 (noted Java wait
returns Workflow vs TS/C# AgentResult).
- sdk-design: rewrote the SDK parity-status note from "Java/C# have real gaps"
to near-full parity; corrected SemanticMemory to a client-side keyword
(Jaccard) store (not vector-DB/embeddings, not wire-serialized).
- java-implementation: added ApiTool + SemanticMemory.
- csharp-implementation: added ConversationMemory, DockerCodeExecutor,
Guardrail.External, tier-1 credential accessor, ApiTools ${NAME} validation,
and the thinkingConfig/promptTemplate/maxTurns wire fixes.
Still-open (documented honestly, not fixed): C#/TS omit some optional config
fields; server maskedFields is accepted but never applied (0 callers); claude-code/
Claude-SDK/Vercel-AI/OCG provider asymmetries unchanged.
…Result Round 2 of the cross-SDK fixes (test-first; all SDKs green: Python 1697, TS 854, Java 274, C# 56). #2 config-field parity: - C#: now emits synthesize, prefillTools, cliConfig (+workingDir), reasoningEffort, contextWindowBudget, maskedFields (exact Python/Java wire keys; wired up the previously-unused CliConfig record). - TypeScript: now emits reasoningEffort, contextWindowBudget, maskedFields. (maskedFields is emitted for parity though the server still no-ops it.) #3 schedules.runNow wait variant returns AgentResult in ALL SDKs: - Python run_now(wait=True) and Java runNowAndWait now return AgentResult (reusing each SDK's existing workflow->AgentResult extraction; no duplicated logic). TS/C# already returned AgentResult. #5 full code-executor set (Local/Docker/Jupyter/Serverless) in every SDK: - Java + C#: added LocalCodeExecutor, JupyterCodeExecutor, ServerlessCodeExecutor (had Docker); C# WorkerManager now delegates local exec to LocalCodeExecutor. - TypeScript: implemented JupyterCodeExecutor (was a stub). - Jupyter mechanism is language-idiomatic (Python in-process jupyter_client, TS `jupyter run` CLI, Java/C# Kernel Gateway) — worker-side runtime, not wire/AgentConfig. #4 (provider asymmetry: claude-code/Claude-SDK/Vercel-AI/OCG) intentionally left as-is.
…ult, C#/TS fields) - tool-execution-and-credentials: all 4 executors now in all 4 SDKs (idiomatic Jupyter mechanism noted); C# WorkerManager delegates to LocalCodeExecutor. - sentinel-agents: runNow wait variant returns AgentResult uniformly (removed Java-Workflow caveat). - sdk-design: parity status now essentially complete; only open items = server maskedFields no-op + provider/framework asymmetries. - java/csharp-implementation: full executor family; Java runNowAndWait->AgentResult; C# 6 new emitted fields.
maskedFields was accepted on AgentConfig but never written to the Conductor WorkflowDef (0 callers), so the requested input/output field redaction in execution history/UI silently never happened — a silent data-exposure gap despite the SDK API + javadoc promising it. Fix: wire config.getMaskedFields() -> WorkflowDef.setMaskedFields(...) once in AgentCompiler.compile()'s shared post-processing step, so it covers every compile shape (simple/tools/multi-agent/hybrid/router/passthrough/graph). Recursively- compiled sub-agents pass back through the same point and carry their own masked fields; purely-internal helper sub-workflows correctly don't. Direct List<String> pass-through (conductor-common WorkflowDef.maskedFields is List<String>). Test-first (CLAUDE.md): MaskedFieldsCompilerTest asserts compiled WorkflowDef carries the masked fields for single-agent, tools, and multi-agent paths (failed before the fix, pass after). `:conductor-agentspan:test` BUILD SUCCESSFUL. Docs: flipped the design notes from "maskedFields no-op" to "now applied" (sdk-design.md parity status; csharp-implementation.md). Provider/framework asymmetry is now the only remaining open parity item.
Format the new/edited Java (server compiler test + Java SDK executors, guardrail, memory store, schedules, tests) with palantir-java-format + import ordering so spotlessCheck passes. No logic changes.
Rebrand the product name in user-facing and design docs from "Agentspan" to "Conductor Agents", and align install/package coordinates with the published SDK names. Documentation only — no code changes. - docs/, design/, sdk/*/docs, sdk/*/examples/*.md, root + server README, AGENTS.md, SKILL.md, mkdocs.yml - Install coords: pip install agentspan → conductor-agent-sdk; @agentspan-ai/sdk → @conductoross/conductor-agent-sdk; PyPI badges retargeted - Kept (runtime contracts, unchanged): agentspan CLI binary, AGENTSPAN_* env vars, agentspan-runtime.jar, dev.agentspan.* / Agentspan* code symbols, github.com/agentspan-ai/agentspan + agentspan.ai URLs, link targets
…tor" Reverse the prior Conductor Agents prose rename. The framework keeps the name Agentspan, positioned as "a durable runtime for AI agents, built for Conductor." This realigns docs prose with the code: every runtime contract is already agentspan (CLI, AGENTSPAN_* env, agentspan-runtime.jar, dev.agentspan.*). The SDK packages remain Conductor-branded (conductor-agent-sdk / @conductoross / conductor.ai) and are framed as "the Conductor agent SDK" you install to build on the Agentspan runtime. - "Conductor Agents" -> "Agentspan" across 87 .md/.yml files (prose only) - Hero tagline set in index.md, why-agentspan.md, README.md; mkdocs site_name "Agentspan Docs" + site_description updated - Kept: conductor-agent-sdk install coords + PyPI badges, all agentspan runtime contracts, agentspan-ai/agentspan + agentspan.ai URLs, link targets - No code changed (2 .py docstrings with the old phrase left untouched) Also relocate mkdocs config: mkdocs.yml -> docs/mkdocs.yml (docs_dir: ., site_dir: ../site, exclude_docs); update serve-docs.sh and AGENTS.md refs.
mkdocs serve rejects a config that lives inside its own docs_dir
("docs_dir should not be the parent directory of the config file"), so the
docs/mkdocs.yml layout (docs_dir: .) built but could not be served for local
review. Restore the standard layout: mkdocs.yml at root, docs_dir: docs,
site_dir: site. Revert serve-docs.sh and AGENTS.md to the root-config form.
The Agentspan rebrand content in mkdocs.yml (site_name/site_description) is kept.
This also means the CI workflow needs no change (root mkdocs.yml unchanged).
- docs/index.md: remove duplicate opening tagline (copy-paste artifact)
- sdk/python/docs/README.md: add PyPI disambiguation line ("Installed as
conductor-agent-sdk — you're in the right place")
- sdk/java/README.md + sdk/java/docs/index.md: unify to canonical "a durable
runtime for AI agents, built for Conductor" (was "agent orchestration platform"
/ "backed by Conductor workflows" — inconsistent positionings)
- mkdocs.yml: site_description "the durable agent runtime" → "a durable agent
runtime" (match homepage register; "the" was an unsupported category claim)
- docs/why-agentspan.md: add orienting sentence after hero bridging to content
- sdk/python/README.md, sdk/typescript/README.md, server/README.md,
sdk/java/README.md: standardize docs URL to agentspan.ai/docs
(was docs.agentspan.dev / agentspan.dev)
Foreground the four concrete patterns Agentspan enables — long-running,
background, scheduled, and event-driven agents — across all hero surfaces.
The previous messaging led with crash recovery; scheduling (a fully shipped
feature) was never mentioned in any hero.
- README.md: replace one-liner body with four-pattern table (long-running /
background / scheduled / event-driven) + opening positioning sentence
- docs/index.md: rewrite body paragraph to lead with the four patterns
- docs/why-agentspan.md: add two failure modes ("no scheduling without
external infra", "background jobs block or disappear") + two capability
bullets (scheduled agents, background execution with runtime.deploy())
- mkdocs.yml site_description: updated to reflect the patterns
- sdk/{python,typescript,java,csharp}/docs README: taglines updated to
"long-running, background, scheduled, and event-driven AI agents"
No code changed. No declarative event triggers promised (those aren't
shipped; messaging says "trigger from webhooks/queues/events" which works
today via runtime.run() from any event handler).
Two fixes in one pass:
1. Evidence behind every production pattern claim — the README hero table
now shows the actual API for each pattern so readers know exactly how
it works, not just that it exists:
- Long-running: timeout_seconds=0 by default (no limit)
- Background: runtime.start() returns AgentHandle immediately
- Scheduled: deploy(agent, schedules=[Schedule(cron=…)])
- Event-driven: runtime.send_message(execution_id, event)
- Plan-Execute: Strategy.PLAN_EXECUTE — newly added
2. Plan-Execute (PAC/PAE) added to all hero surfaces — it was absent from
every hero despite being a major shipped feature (482-line doc, 13 Python
examples, full cross-SDK parity, e2e tests):
- README: 5th row in pattern table with "the Conductor superpower" framing
- README body: "with Plan-Execute, the LLM decides what to do while
Conductor handles the rest"
- docs/index.md: body paragraph references Plan-Execute; concept list
adds "LLM plans, Conductor executes — the deterministic superpower"
- docs/why-agentspan.md: "What this enables" gains Plan-Execute bullet
with the deterministic boundary explained; background execution bullet
updated to reference runtime.start() + runtime.send_message()
- Per-SDK docs: all four taglines add "plan-execute" to the pattern list
Restructure all hero surfaces around three clear pillars: 1. Long-running agents — runs as long as needed, no timeout by default, crash recovery, HITL. Durability is infrastructure, not the pitch. 2. Dynamic agents (Plan-Execute) — LLM adapts the plan to the task at runtime; Conductor compiles it into an immutable sub-workflow and executes deterministically. Can call existing Conductor workflows as plan steps. 3. Event-driven agents — triggered by cron schedules + Conductor's native event handler integrations (Kafka, SQS, AMQP, webhooks, database events). Every event source Conductor supports is available to agents. Changes: - README.md: replace 5-row table with three prose pillar blocks - docs/index.md: rewrite body paragraph around three pillars - docs/why-agentspan.md: reorganize "What this enables" into three named subsections (Long-running agents / Dynamic agents / Event-driven agents); remove the now-redundant "background execution" bullet - mkdocs.yml site_description: updated to three-pillar framing - Per-SDK doc taglines: "long-running, dynamic plan-execute, and event-driven"
…t-4-6
Two changes:
1. Env var setup standardized in all 4 SDK getting-started docs:
export AGENTSPAN_SERVER_URL=http://localhost:6767/api
export OPENAI_API_KEY=<YOUR-KEY>
export AGENTSPAN_LLM_MODEL=openai/gpt-4o-mini
Previously: Python missing AGENTSPAN_LLM_MODEL; TypeScript/C# missing
OPENAI_API_KEY and AGENTSPAN_LLM_MODEL; Java missing OPENAI_API_KEY and
had wrong URL (6767 instead of 6767/api).
2. Default model in examples and docs changed from openai/gpt-4o-mini
to anthropic/claude-sonnet-4-6 (~572 occurrences across 218 files).
Intentionally preserved:
- AGENTSPAN_LLM_MODEL=openai/gpt-4o-mini in env var setup blocks (per spec)
- ChatOpenAI(model="gpt-4o-mini") in LangGraph/LangChain examples — these
are OpenAI-specific class instantiations that cannot be swapped to anthropic
without changing the class from ChatOpenAI to ChatAnthropic
- Server source code defaults (ModelContextWindows, normalizer defaults)
- E2e and unit test files
…tions New docs/sdk.md covers: - Quick reference table: all 4 SDK coordinates, import paths, links - Environment setup (the canonical 3 env vars) - Agent 101: tabbed Python/TypeScript/Java/C# hello-world with a tool - AgentResult field reference - Framework agents section: LangGraph, LangChain, OpenAI Agents SDK, Google ADK, Vercel AI SDK — each with language-specific code tabs - Next steps links Added to mkdocs.yml nav under Getting Started.
Empty/unknown model objects now default to anthropic/claude-sonnet-4-6 instead of openai/gpt-4o-mini. Tests that passed explicit OpenAI models (gpt-4o-mini with openai.chat provider, ChatOpenAI class) were asserting the wrong expected value — fixed to expect openai/gpt-4o-mini.
… skip "Look up the marker data." was vague enough that gpt-4o-mini sometimes asked for clarification instead of calling get_marker_data, causing #9 aout_custom_fix (and potentially #8 aout_custom_raise) to flake. Adding "for item 'test'" gives the model a concrete query and removes the ambiguity. Same failure observed on main (2026-06-25).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.