Portable Agent Manifests with Host-Controlled Infrastructure

#opensource #agents #ai #typescript

AI agents often begin as application code: a prompt, a model call, a few tools, and enough control flow to make the first example run.

As the agent grows, the definition and the environment tend to collapse into each other. Model configuration lives beside credentials. Tool access is mixed with prompts. Persistence assumes a particular process. Deployment choices become part of the agent itself.

That coupling makes an agent harder to inspect, test, move, and recover.

We built Clear Ideas Agent Runtime around a different boundary: the agent definition should be portable, while the infrastructure that executes it should remain under host control.

The Agent Manifest is the portable contract

An Agent Manifest is a versioned YAML or TypeScript definition. It can describe:

prompts and structured outputs;
typed variables;
conditions and loops;
tools and MCP connections;
approvals and webhooks;
sandboxed code steps;
sub-runs;
limits and final outputs.

A separate Agent Run Manifest supplies the values and execution choices for one invocation. That keeps the reusable agent definition distinct from the inputs and operational decisions associated with a particular run.

Here is a small example:

schemaVersion: "1.0"
name: research-brief
variables:
  topic:
    type: string
  researchNotes:
    type: string
  briefDraft:
    type: string
steps:
  - id: research
    type: prompt
    prompt: |
      Research {{ topic }} and return concise notes.
    outputVariable: researchNotes

  - id: draft
    type: prompt
    prompt: |
      Draft a brief using these notes:
      {{ researchNotes }}
    outputVariable: briefDraft

The manifest describes the agent. It does not contain the credentials, infrastructure account, or persistence implementation that happens to run it.

The host controls the operational boundary

The host application supplies and controls:

models and provider credentials;
connections and tool authorization;
persistence and artifact stores;
local or remote compute;
sandbox providers;
telemetry;
concurrency and resource limits.

This is more than configuration hygiene. It prevents a portable agent definition from granting itself broader access. The host resolves credentials, exposes approved tools, narrows connection modes, and can authorize individual tool calls against application policy.

Authorization is therefore part of the runtime boundary, not a feature supplied only by a hosted service.

One run contract across execution environments

Agent Runtime supports three execution boundaries through one client contract:

In process for embedding the runtime in a TypeScript application.
Child process for execution through the portable worker protocol.
Remote compute through an execution-engine adapter.

The Agent Manifest does not change when the execution boundary changes.

The included Modal adapter implements remote submission, status, ordered events, result retrieval, resume, and cancellation. Docker and Modal Sandboxes implement the runtime's native sandbox contract for isolated code execution and generated artifacts.

Applications can supply different compute or sandbox implementations through the same adapter interfaces.

Durable execution is part of the runtime

A multi-step agent needs more than a final response.

Agent Runtime checkpoints run state, step outputs, transcripts, generated files, and continuation data. Suspended or interrupted runs can resume in a fresh process. Attempt fencing prevents an older worker from committing after another process has resumed the run.

Runs also emit ordered lifecycle, model, tool, checkpoint, artifact, and text-delta events. A CLI, embedded application, remote worker, or OpenTelemetry integration can consume the same event stream.

This gives the runtime a stable execution history around model calls that are inherently non-deterministic.

The runtime can derive the execution graph

Many orchestration frameworks ask the developer to define a sequence, write routing code, or maintain nodes and edges.

Agent Runtime can instead read the variables each eligible step produces and consumes. From those data dependencies, it derives an execution plan.

Independent prompt branches can run concurrently. Dependent steps wait for their inputs. Tool-enabled and stateful operations remain ordered. Results commit in manifest order.

The graph does not become a second definition maintained beside the agent. It is resolved from the Agent Manifest.

This can reduce elapsed time when an agent contains independent model calls, while preserving ordered checkpoints and state transitions. A mostly linear agent remains mostly sequential.

The execution-graph article includes a complete example, scheduling rules, timing model, and visualization.

Models, tools, and adapters remain composable

Models connect through the AI SDK. Tools can be supplied directly by the application or through Model Context Protocol connections.

Memory, file, and SQLite stores cover common persistence needs. Separate packages provide model, persistence, compute, sandbox, artifact, condition, and OpenTelemetry adapters, allowing an application to install the infrastructure it actually uses.