Designing Portable Agents

Provider-Neutral Agent Systems in TypeScript with Open Standards

Author

Gino Tesei

Published

October 23, 2026

About this book

Designing Portable Agents

Designing Portable Agents: Provider-Neutral Agent Systems in TypeScript with Open Standards is an executable guide to separating application intent from model providers, tool transports, agent protocols, and deployment infrastructure.

See the system first

A research agent, from mixed inputs to a verified deck

Before reading the architecture, watch the working system. The approved demonstration follows the companion reference through ordered image/PDF/XLSX admission, bounded computation, generated image observations, public web discovery, source reading, an evidence-separated brief, progressive skill loading, and digest-verified PowerPoint construction.

Read the transcript · Extended alt description · Evidence and limitations

Northstar Field Console is fictional. This is dated live-provider and public-network evidence—not deterministic output, provider equivalence, production certification, or full Open Responses conformance.

A second path: inspect a document without a model

The second approved demonstration shows /inspect-document opening, navigating, and explicitly saving a bounded local extraction without invoking the configured model. The input is Gino Tesei and coauthors’ public 2023 Journal of Biomedical Informatics paper on self-supervised covariate balancing, supplied by its author. The PDF is not included in the book or reference repository.

Read the interaction transcript · Extended alt description · Evidence and limitations

The 90-second run reports 16 pages, 44 chunks, zero extraction warnings, and a digest before requiring confirmation to replace the Markdown output. It demonstrates that exact local run—not universal PDF fidelity, scientific verification, or a model capability. Article text and publisher formatting retain their respective rights and are not relicensed by inclusion.

The five-part path is:

Chapter 16 intentionally remains evidence-gated until tested OpenTelemetry instrumentation exists. Chapter 19 retains the current not conformant Open Responses classification rather than converting compatibility into a release claim.

The same Quarto Markdown sources produce the navigable HTML edition and KOMA-Script/LaTeX PDF. Small book examples are independently tested where executable; the companion reference implementation is maintained in a separate repository and remains private until its release gates pass.

Publication status: nineteen-chapter technical preview; implementation and production-readiness claims remain evidence-scoped
Standards checked: foundational review 2026-10-07–09; later claims carry their own dates and pins
Current reviewed snapshot: portable-agents-reference commit 45a903c84c30ac1bcc9636c91e4166c5009f2f00, package version 0.4.0
Latest immutable release: v0.4.0, commit 5ecc4f01e61858f16e42e5c2c34edac234855d6d
Historical baseline retained where cited: v0.3.0, commit 1c7a18a8434e5143cbe9d050b8252a6ead1f9b51
Canonical book source: book/

Runnable book-owned examples

Download the independently authored reader examples and retain its content manifest. With Bun 1.3.9, extract the archive, enter portable-agents-examples, then run bun run test and bun run northstar. No dependency installation, repository credential, provider key, or live endpoint is needed. The manifest identifies the exact distributed source/test snapshot by file hashes; it is not a signature. PDF readers can obtain the same downloads from the book website, under Runnable book-owned examples.

These examples implement the deployment binder, scoped capability admission, recovery decision, SQLite transcript experiment, locator/card boundary, and deterministic two-measurement Northstar composition. They are book designs, not APIs claimed to exist in the reference release. Successful local composition is not live-provider equivalence, general claim support, production authorization, or conformance.

Implementation and evidence map

The map separates four evidence classes that must not be collapsed:

Immutable release evidence refers to the exact v0.4.0 or historical v0.3.0 tag.
Current snapshot evidence refers to exact post-release commit 45a903c, which includes the approved demonstrations and later skill/configuration work.
Book-owned deterministic evidence refers only to source and tests distributed with this book.
Planned or blocked work has no implementation claim, even when the architecture is specified.

Ch.	Boundary	Primary implementation/evidence	Status and limitation
1	End-to-end Northstar workflow	Current snapshot `README.md` and approved demo metadata	Dated live-provider/public-network sample; not deterministic or equivalent across providers
2	Pi client	Current launcher and five extensions under `scripts/` and `extensions/pi/`	Pi 1.0.4 client path; not Open Responses conformance
3	Strict agent configuration	Current `agent.yaml`, parser, and configuration tests	Static reviewed catalog; no principal authentication or dynamic plugins
4	Document/image ingestion	Current `src/input/`, `src/ingestion/`, and inspection evidence	Implemented local profile; invocation-local identity, not durable citations
5	Provider adapters	Immutable `v0.4.0` model/provider adapters; historical `v0.3.0` live reports where explicitly cited	Shared application boundary; no broad semantic equivalence
6	Open Responses lifecycle	Current `src/open-responses/` and pinned protocol/suite records	Compatible HTTP/SSE subset; not conformant
7	Streaming and termination	Immutable bounded consumer plus current termination/diagnostic tests	Local bounds and cancellation; no universal end-to-end network-backpressure proof
8	Typed authorized tools	Immutable tool runtime plus current server progress implementation	Validation and policy hooks are implemented; application authentication remains external
9	Skills and presentations	Current `src/skills/`, presentation tool, worker, and tests	Post-`v0.4.0` snapshot; skill grants no executable authority
10	`web_search`	Current search tool/backends, budgets, and invariant tests	Bounded discovery; candidates are not read-source evidence
11	`read_source`	Current source reader, screened retrieval, ingestion integration, and tests	Public HTTPS profile; retrieved content remains untrusted
12	`code_interpreter`	Current fresh Pyodide worker, scheduler, mounts, and tests	Bounded local computation; not an OS sandbox
13	Grounding and completion	Current evidence modules plus book-owned Northstar support computation	Provenance/locator mechanisms; no general entailment verifier
14	Capability and fallback policy	Current portability modules plus book-owned capability-admission example	Scoped policy and limited evidence; not provider parity
15	Recovery and durable state	Current recovery/transcript modules plus book-owned SQLite experiment	Local history and reconciliation rules; not a production effect ledger
16	OpenTelemetry	No OpenTelemetry implementation in the reviewed snapshot	Blocked pending spans, propagation, redaction, concurrency, and sanitized trace evidence
17	Security and evaluation gates	Distributed controls and deterministic adversarial tests	Partial controls only; no production certification
18	MCP and A2A	Architecture and pinned public specifications	Not implemented; no interoperability claim
19	Integrated case and conformance	Approved demos plus pinned official-suite wrapper/results	Current classification: compatible subset; not conformant

The v0.3.0 tag remains the immutable source for dated 2026-10-08 adapter reports and the teaching baseline used in several substantive runtime chapters. Those records are not rewritten as v0.4.0 runs. Conversely, ingestion, Pi inspection, skills, presentations, and the published hero are tied to the current post-release snapshot rather than backdated into either release tag.

Claims and evidence

The book uses seven evidence labels:

specified — stated by a pinned external specification;
designed — proposed by the book’s architecture;
implemented — present in a named immutable release, fixed source snapshot, or tested book source; a snapshot is not a reviewed release;
deterministically tested — covered by a named network-free fixture;
live-tested — exercised against a named provider, model, configuration, and date;
conformant — passed a pinned official conformance runner; and
evaluated — measured for semantic quality or safety under a published method.

A schema resemblance is not conformance. A common provider interface is not semantic equivalence. Every portability claim should name both its dimension and evidence label. Formal Open Responses conformance is intentionally reserved for the concluding validation rather than imposed as an initial implementation constraint.

Working glossary

Response: one model operation and its authoritative terminal outcome.
Item: an identifiable message, tool call, or other unit in a response trajectory.
Event: an ordered state transition or incremental update.
Step: one model generation phase within a bounded tool loop.
Turn: an application-level conversational exchange; it may contain several model steps.
Run: the request-scoped orchestration that owns policy, budgets, and cancellation.
Task: delegated work with its own lifecycle, especially at an agent-to-agent boundary.
Call: one correlated proposal to invoke a named tool.
Result: the single terminal application outcome associated with a call.

License

Book prose, original diagrams, and cover artwork are licensed under CC BY-NC-ND 4.0. Executable code and build scripts are licensed under Apache-2.0. Third-party material remains under its respective terms.