Typescript SDK by spichen · Pull Request #100 · oracle/agent-spec

spichen · 2026-02-13T09:25:35Z

Resolves #97

oracle-contributor-agreement · 2026-02-13T09:25:40Z

Thank you for your pull request and welcome to our community! To contribute, please sign the Oracle Contributor Agreement (OCA).
The following contributors of this PR have not signed the OCA:

PR author: nh.salah@gmail.com (@spichen)

To sign the OCA, please create an Oracle account and sign the OCA in Oracle's Contributor Agreement Application.

When signing the OCA, please provide your GitHub username. After signing the OCA and getting an OCA approval from Oracle, this PR will be automatically updated.

If you are an Oracle employee, please make sure that you are a member of the main Oracle GitHub organization, and your membership in this organization is public.

dhilloulinoracle · 2026-02-13T10:00:27Z

Thanks a lot @spichen for this big contribution!
We will start reviewing it.

To be able to merge it, we would need you to sign the CLA. Would it be possible for you to have a look at that?

Copilot

Pull request overview

This pull request introduces a comprehensive TypeScript SDK for the Oracle Open Agent Specification. The SDK provides a strongly-typed, developer-friendly API for defining AI agents, multi-agent systems, workflows, tools, and related components with full serialization/deserialization support.

Changes:

Complete TypeScript SDK implementation with Zod schemas for validation
Comprehensive test suite with 30+ test files covering all major features
Full serialization/deserialization system supporting JSON/YAML with version gating
8 detailed examples demonstrating SDK usage patterns

Reviewed changes

Copilot reviewed 135 out of 136 changed files in this pull request and generated 22 comments.

Show a summary per file

File	Description
package.json	Package configuration with dependencies (zod, yaml) and dev tooling
tsconfig.json	Strict TypeScript configuration with modern ES2022 target
tsup.config.ts	Build configuration for dual CJS/ESM output with type definitions
vitest.config.ts	Test configuration with v8 coverage
src/component.ts	Base component schemas and type system
src/agents/*.ts	Agent types: Agent, Swarm, ManagerWorkers, RemoteAgent, A2AAgent, SpecializedAgent
src/tools/*.ts	Tool types: ServerTool, ClientTool, RemoteTool, BuiltinTool, MCPTool, ToolBox
src/llms/*.ts	LLM configs: OpenAI, vLLM, Ollama, OCI GenAI
src/flows/*.ts	Flow system with nodes, edges, and FlowBuilder
src/mcp/*.ts	MCP tool and transport support
src/serialization/*.ts	Complete serialization system with plugins, version gating, and sensitive field exclusion
src/versioning.ts	Version tracking and comparison utilities
src/templating.ts	Template placeholder extraction from strings/objects
src/sensitive-field.ts	Security: marks fields for exclusion from serialization
tests/*/.test.ts	Comprehensive test coverage for all components
examples/*.ts	8 working examples demonstrating SDK usage

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

oracle-contributor-agreement · 2026-02-13T14:57:09Z

Thank you for signing the OCA.

sonleoracle

This is in mergeable shape for me if we keep the support contract narrow.

I do not want to make this package a broad compatibility gate for every historical fixture in the repo, but I do want one curated repository-fixture round-trip test so we have a stable CI contract for common Agent Spec shapes.

I locally validated a curated set of 61 configs that round-trip successfully with the current SDK when tested in the right mode:

standalone current-format configs are tested as ordinary one-file round trips
howto_disaggregated_* is tested with the intended two-step API (importOnlyReferencedComponents + componentsRegistry)
the weather/ancestry adapter fixtures are tested from placeholder-resolved copies derived from the repo paths below

Please add a tests/repo-fixtures.test.ts-style test that round-trips these repo configs:

docs/pyagentspec/source/agentspec_config_examples/agentspec_oracle_it_assistant.json
docs/pyagentspec/source/agentspec_config_examples/agentspec_oracle_it_assistant.yaml
pyagentspec/tests/adapters/langgraph/configs/ancestry_agent_with_client_tool.yaml
docs/pyagentspec/source/agentspec_config_examples/autogen_to_agentspec.json
docs/pyagentspec/source/agentspec_config_examples/autogen_to_agentspec.yaml
docs/pyagentspec/source/agentspec_config_examples/ext_christmas_greetings_tutorial.json
docs/pyagentspec/source/agentspec_config_examples/ext_christmas_greetings_tutorial.yaml
docs/pyagentspec/source/agentspec_config_examples/ext_code_assistant_tutorial.json
docs/pyagentspec/source/agentspec_config_examples/ext_code_assistant_tutorial.yaml
docs/pyagentspec/source/agentspec_config_examples/ext_ops_assistant_tutorial_agent.json
docs/pyagentspec/source/agentspec_config_examples/ext_ops_assistant_tutorial_agent.yaml
docs/pyagentspec/source/agentspec_config_examples/ext_ops_assistant_tutorial_flow.json
docs/pyagentspec/source/agentspec_config_examples/ext_ops_assistant_tutorial_flow.yaml
docs/pyagentspec/source/agentspec_config_examples/ext_tutorial_cybersecurity_flow.json
docs/pyagentspec/source/agentspec_config_examples/ext_tutorial_cybersecurity_flow.yaml
pyagentspec/tests/adapters/langgraph/configs/haiku_without_a_flow.json
docs/pyagentspec/source/agentspec_config_examples/howto_ag_ui.json
docs/pyagentspec/source/agentspec_config_examples/howto_ag_ui.yaml
docs/pyagentspec/source/agentspec_config_examples/howto_agent_with_remote_tools.json
docs/pyagentspec/source/agentspec_config_examples/howto_agent_with_remote_tools.yaml
docs/pyagentspec/source/agentspec_config_examples/howto_agents.json
docs/pyagentspec/source/agentspec_config_examples/howto_agents.yaml
docs/pyagentspec/source/agentspec_config_examples/howto_catchexception.json
docs/pyagentspec/source/agentspec_config_examples/howto_catchexception.yaml
docs/pyagentspec/source/agentspec_config_examples/howto_disaggregated_component_config.json
docs/pyagentspec/source/agentspec_config_examples/howto_disaggregated_component_config.yaml
docs/pyagentspec/source/agentspec_config_examples/howto_disaggregated_main_config.json
docs/pyagentspec/source/agentspec_config_examples/howto_disaggregated_main_config.yaml
docs/pyagentspec/source/agentspec_config_examples/howto_flow_with_conditional_branches.json
docs/pyagentspec/source/agentspec_config_examples/howto_flow_with_conditional_branches.yaml
docs/pyagentspec/source/agentspec_config_examples/howto_flowbuilder.json
docs/pyagentspec/source/agentspec_config_examples/howto_flowbuilder.yaml
docs/pyagentspec/source/agentspec_config_examples/howto_managerworkers.json
docs/pyagentspec/source/agentspec_config_examples/howto_managerworkers.yaml
docs/pyagentspec/source/agentspec_config_examples/howto_mapnode.json
docs/pyagentspec/source/agentspec_config_examples/howto_mapnode.yaml
docs/pyagentspec/source/agentspec_config_examples/howto_mcp_agent.json
docs/pyagentspec/source/agentspec_config_examples/howto_mcp_agent.yaml
docs/pyagentspec/source/agentspec_config_examples/howto_mcp_flow.json
docs/pyagentspec/source/agentspec_config_examples/howto_mcp_flow.yaml
docs/pyagentspec/source/agentspec_config_examples/howto_parallelflownode.json
docs/pyagentspec/source/agentspec_config_examples/howto_parallelflownode.yaml
docs/pyagentspec/source/agentspec_config_examples/howto_structured_generation1.json
docs/pyagentspec/source/agentspec_config_examples/howto_structured_generation1.yaml
docs/pyagentspec/source/agentspec_config_examples/howto_structured_generation2.json
docs/pyagentspec/source/agentspec_config_examples/howto_structured_generation2.yaml
docs/pyagentspec/source/agentspec_config_examples/howto_structured_generation3.json
docs/pyagentspec/source/agentspec_config_examples/howto_structured_generation3.yaml
docs/pyagentspec/source/agentspec_config_examples/howto_summarization_transforms.json
docs/pyagentspec/source/agentspec_config_examples/howto_summary_flow.json
docs/pyagentspec/source/agentspec_config_examples/howto_summary_flow.yaml
docs/pyagentspec/source/agentspec_config_examples/math_homework_agent.json
docs/pyagentspec/source/agentspec_config_examples/math_homework_agent.yaml
docs/pyagentspec/source/agentspec_config_examples/simple_agent_with_rag_tool.json
docs/pyagentspec/source/agentspec_config_examples/simple_agent_with_rag_tool.yaml
pyagentspec/tests/adapters/langgraph/configs/swarm_calculator.yaml
pyagentspec/tests/adapters/langgraph/configs/weather_agent_client_tool.yaml
pyagentspec/tests/adapters/langgraph/configs/weather_agent_remote_tool.yaml
pyagentspec/tests/adapters/langgraph/configs/weather_agent_server_tool.yaml
pyagentspec/tests/adapters/langgraph/configs/weather_agent_with_outputs.yaml
pyagentspec/tests/adapters/langgraph/configs/weather_ollama_agent.yaml

Notes on that list:

the howto_disaggregated_* files should be exercised with the intended two-step API, not as naive single-file fixtures
the weather/ancestry adapter fixtures should be tested from placeholder-resolved copies derived from those repo paths, not from the raw YAML files with [[...]] placeholders

The broader public-example compatibility follow-ups I would still like to see, but not as merge blockers, are:

docs/pyagentspec/source/agentspec_config_examples/howto_a2aagent.json
docs/pyagentspec/source/agentspec_config_examples/howto_a2aagent.yaml
docs/pyagentspec/source/agentspec_config_examples/howto_swarm.json
docs/pyagentspec/source/agentspec_config_examples/howto_swarm.yaml

One more thing I would like cleaned up before merge:

npm ci and npm run build both succeed locally, but npm run build emits a packaging warning because package.json declares exports.types after import and require, so that types condition is never used
npm audit --omit=dev --json currently reports a direct runtime vulnerability because package-lock.json resolves yaml to 2.8.2; there is a fix available in >= 2.8.3

Please:

bump yaml to a non-vulnerable version and refresh the lockfile
fix the exports ordering in tsagentspec/package.json so the types condition is actually effective

These are not functional runtime failures in the current branch, but they are package-quality issues that are better fixed before merge.

Also please briefly document the intended supported surface so we do not imply that every historical/example fixture in this repo is guaranteed to round-trip in TS.

…ation Implements a complete TypeScript SDK providing the same core capabilities as the Python SDK (pyagentspec) for authoring, validating, and serializing/deserializing Agent Spec configurations. Core features: - All component types: Agent, Swarm, ManagerWorkers, Flow, 14 node types, 4 tool types, 6 LLM config types, edges, datastores, transforms - Property system with JSON Schema mapping (9 typed property factories) - Full serialization/deserialization with JSON and YAML support - $component_ref referencing for shared components - Template variable extraction from {{placeholder}} syntax - Plugin architecture for custom component types - Version-gated field serialization (agentspec_version 25.4.1+) - camelCase/snake_case field name conversion for Python SDK interop - FlowBuilder with ergonomic builder pattern API Technical details: - Zod schemas + factory functions (no class hierarchies) - Discriminated unions on componentType for type-safe polymorphism - Strict TypeScript with zero `any` types in public API - ESM + CJS dual build via tsup - 384 tests across 29 test files (vitest) Signed-off-by: Salah <nh.salah@gmail.com>

dhilloulinoracle · 2026-04-02T10:18:05Z

Internal regression failed: Build ID #405

spichen · 2026-04-02T11:11:30Z

@sonleoracle

Should this PR also add a CI step to run the new SDK's tests, or handle that separately?

Should this PR include documentation for the new SDK, or save that for a follow-up?

Should we move the config files used in repo fixture tests out of the pyagentspec docs into a common shared area?

Hi @spichen

This PR is mergeable, and we can handle those in follow-up PRs.

Since we do not currently have plans to publish the TypeScript SDK, I think the installation instructions in the README should be updated to describe source installation instead, for example:
git clone https://github.com/oracle/agent-spec.git
cd agent-spec/tsagentspec
npm ci
npm run build
and, if useful, how to consume it from another local project, e.g. via a local path install.

Related small doc nit: tsagentspec/examples/README.md tells users to run examples with npx tsx / npx ts-node, but those tools do not appear to be declared in devDependencies, so that guidance may also need to be adjusted or clarified.

Alright, I've updated the README.
What's the plan for publishing this as an npm package in the future?

dhilloulinoracle · 2026-04-02T11:44:30Z

Internal regression succeeded 🍏: Build ID #406

dhilloulinoracle · 2026-04-02T12:05:41Z

What's the plan for publishing this as an npm package in the future?

We will publish in a more official manner once we have put in place all the required automated checks to ensure that it has the same functionalities as the python one (no divergence in functionalities) as well as passes our internal requirements for security :) .

dhilloulinoracle · 2026-04-02T13:59:50Z

Internal regression succeeded 🍏: Build ID #407

Shape-based detection (isComponent, isSerializedComponent) and recursive $component_ref resolution were applied to all nested objects, including user-controlled payload fields like metadata, data, headers, queryParams, and configuration. Any plain object in those fields that happened to carry id/name/componentType keys was incorrectly treated as a component child during serialization or deserialized as a component. Fix: derive the set of "opaque" fields per component type by introspecting the Zod schema (ZodRecord, ZodUnknown, ZodAny, unwrapping Optional/Default wrappers). During serialization the builtin plugin now sanitizes opaque fields (strip DANGEROUS_KEYS, enforce depth limit) without invoking isComponent or dumpField; the referencing traversal skips opaque fields entirely. During deserialization the builtin plugin preserves opaque field values verbatim (null/undefined omitted so Zod defaults apply). Results are cached per component type so schema introspection runs at most once per type. Adds regression tests covering metadata, ApiNode payload fields (data/headers/queryParams), and BuiltinTool configuration.

datastore on both summarization transforms was typed as z.record(z.unknown()), which accepted arbitrary JSON and caused component-shaped nested values to be traversed (or deserialized as components) instead of being treated as a real component field. Match pyagentspec's SupportedDatastores = InMemoryCollectionDatastore | OracleDatabaseDatastore | PostgresDatabaseDatastore discriminated union so the field is validated and deserialized correctly. Update the "should accept a custom datastore" tests to pass actual datastore instances instead of plain dicts.

sonleoracle · 2026-04-13T15:43:33Z

Hi @spichen
Could you please rebase on top of latest main? We just pushed a few fixes.

spichen · 2026-04-13T15:48:06Z

Hi @spichen Could you please rebase on top of latest main? We just pushed a few fixes.

I merged main branch into this branch.

dhilloulinoracle · 2026-04-14T10:09:47Z

Internal regression succeeded 🍏: Build ID #419

dhilloulinoracle · 2026-04-14T11:47:04Z

Merge Gate failed: Build ID #643

dhilloulinoracle · 2026-04-14T11:50:02Z

Merge Gate INPROGRESS

dhilloulinoracle · 2026-04-14T12:24:33Z

Internal regression succeeded 🍏: Build ID #446

dhilloulinoracle · 2026-04-14T12:24:52Z

Merge Gate failed: Build ID #644

oracle-contributor-agreement bot added the OCA Required At least one contributor does not have an approved Oracle Contributor Agreement. label Feb 13, 2026

dhilloulinoracle requested review from cesarebernardis and sonleoracle February 13, 2026 10:00

youssef62 requested a review from Copilot February 13, 2026 10:04

Copilot started reviewing on behalf of youssef62 February 13, 2026 10:04 View session

youssef62 requested review from Copilot and removed request for Copilot February 13, 2026 10:05

Copilot AI reviewed Feb 13, 2026

View reviewed changes

Copilot started reviewing on behalf of youssef62 February 13, 2026 10:06 View session

youssef62 requested review from Copilot and removed request for Copilot February 13, 2026 10:14

Copilot started reviewing on behalf of youssef62 February 13, 2026 10:14 View session

spichen marked this pull request as ready for review February 13, 2026 13:51

spichen requested a review from a team February 13, 2026 13:51

oracle-contributor-agreement bot added OCA Verified All contributors have signed the Oracle Contributor Agreement. and removed OCA Required At least one contributor does not have an approved Oracle Contributor Agreement. labels Feb 13, 2026

sonleoracle reviewed Feb 18, 2026

View reviewed changes

Comment thread tsagentspec/src/flows/edges/data-flow-edge.ts

sonleoracle reviewed Feb 18, 2026

View reviewed changes

Comment thread tsagentspec/tests/property.test.ts

sonleoracle reviewed Feb 18, 2026

View reviewed changes

Comment thread tsagentspec/src/flows/nodes/llm-node.ts

spichen force-pushed the typescript-sdk branch from 9865d00 to 24ce2ca Compare February 18, 2026 17:23

sonleoracle reviewed Feb 19, 2026

View reviewed changes

sonleoracle requested changes Mar 16, 2026

View reviewed changes

spichen requested a review from sonleoracle March 19, 2026 15:24

sonleoracle requested changes Apr 1, 2026

View reviewed changes

spichen force-pushed the typescript-sdk branch 2 times, most recently from 1543f93 to 762b3a1 Compare April 1, 2026 19:23

docs: replace npm install with source install, add tsx to devDeps

da48f11

spichen changed the title ~~Typescript sdk~~ Typescript SDK Apr 2, 2026

sonleoracle requested a review from dhilloulinoracle April 2, 2026 12:01

dhilloulinoracle approved these changes Apr 2, 2026

View reviewed changes

sonleoracle approved these changes Apr 2, 2026

View reviewed changes

sonleoracle requested review from jschweiz and paul-cayet and removed request for cesarebernardis and jschweiz April 7, 2026 12:01

paul-cayet approved these changes Apr 7, 2026

View reviewed changes

sonleoracle requested changes Apr 7, 2026

View reviewed changes

Comment thread tsagentspec/src/component.ts

spichen force-pushed the typescript-sdk branch from 4a61eae to 4b0c564 Compare April 7, 2026 22:03

sonleoracle requested changes Apr 8, 2026

View reviewed changes

Comment thread tsagentspec/src/transforms/message-transform.ts Outdated

Merge branch 'main' into typescript-sdk

66446bf

sonleoracle approved these changes Apr 14, 2026

View reviewed changes

dhilloulinoracle merged commit f8b5b03 into oracle:main Apr 14, 2026
7 of 8 checks passed

Conversation

spichen commented Feb 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

oracle-contributor-agreement bot commented Feb 13, 2026

Uh oh!

dhilloulinoracle commented Feb 13, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

oracle-contributor-agreement bot commented Feb 13, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sonleoracle left a comment

Choose a reason for hiding this comment

Uh oh!

dhilloulinoracle commented Apr 2, 2026

Uh oh!

spichen commented Apr 2, 2026

Uh oh!

dhilloulinoracle commented Apr 2, 2026

Uh oh!

dhilloulinoracle commented Apr 2, 2026

Uh oh!

dhilloulinoracle commented Apr 2, 2026

Uh oh!

Uh oh!

Uh oh!

sonleoracle commented Apr 13, 2026

Uh oh!

spichen commented Apr 13, 2026

Uh oh!

dhilloulinoracle commented Apr 14, 2026

Uh oh!

dhilloulinoracle commented Apr 14, 2026

Uh oh!

dhilloulinoracle commented Apr 14, 2026

Uh oh!

dhilloulinoracle commented Apr 14, 2026

Uh oh!

Uh oh!

dhilloulinoracle commented Apr 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

spichen commented Feb 13, 2026 •

edited

Loading