ShelfAI · Context IDE for AI agents

See what your agent saw—and where it came from.

Capture the actual instructions, messages, tool calls, handoffs, and outputs behind every run. Try context changes safely in Workbench, compare the result, and promote only after human approval.

PUBLIC BETA · VERSION 0.3.0 · RELEASED 2026-10-16

model request→tool call→tool result→model output

Install

The public beta is distributed as versioned, checksum-pinned packages. Python can record an agent with no code changes; in Node, wrap the provider client your application already uses.

Python

Install 0.3.0

python -m pip install \
  https://orthogonai.ai/shelfai/releases/0.3.0/shelfai_sdk-0.3.0-py3-none-any.whl

Run with no code changes

python -m shelfai_sdk.auto your_agent.py

Or add one line to the entry point

import shelfai_sdk.auto

Node.js / TypeScript

Install 0.3.0

npm install \
  https://orthogonai.ai/shelfai/releases/0.3.0/shelfai-sdk-0.3.0.tgz

Integrate

import { ShelfAI } from "@shelfai/sdk";

const integration = ShelfAI.integrate({
  client: existingModelClient,
});
const modelClient = integration.client;

Python records every Anthropic and OpenAI client the agent creates, sync and async. In Node, environment variables alone do not instrument a client: wrap it once with ShelfAI.integrate. ShelfAI instruments the client in place, so calls through the original reference are recorded too.

Configure

Use the workspace URL and API key supplied by ShelfAI. Start with metadata-only capture, then deliberately enable Full Capture for replayable content.

SHELFAI_API_URL=<your-shelfai-url>
SHELFAI_API_KEY=<your-workspace-api-key>
SHELFAI_AGENT_ID=<stable-agent-name>
SHELFAI_CAPTURE_MODE=metadata_only

Capture tools without rewriting them

Provider-native and supported framework tools are captured automatically. For ordinary functions used as tools, wrap the existing registry once.

Python

integration = shelfai_sdk.shared_integration()
tools = integration.tools(existing_tools)
result = integration.run(run_workflow, tools)

Node.js

const tools = integration.tools(existingTools);
const result = await integration.runAsync(
  () => runWorkflow(tools)
);

ShelfAI records definition → call → result or error, including nested tool calls and the context that consumes each result. It does not require annotations inside individual tools.

What happens in a real workflow

The wrapped model client records the instructions and messages the provider actually receives.

When the agent chooses a tool, ShelfAI records the real function invocation—not a guess based on text.

The original tool runs normally. Its result is linked to the next model call that consumes it.

Workbench shows the observed path and lets a human propose an experiment against the responsible context.

Replay compares baseline and experimental output. Production source changes require explicit approval.

Enable one-click replay

Give ShelfAI one signed endpoint that runs your existing workflow. Workbench can then apply an approved experiment to one isolated run and return its trace automatically—without experiment IDs or prompt patches in your business logic.

Python · FastAPI

import shelfai_sdk

shelfai_sdk.install(
  app,
  replay=run_existing_workflow,
)

Or name a script to rerun with SHELFAI_REPLAY="scripts/run_agent.py --args" and call shelfai_sdk.install(app).

Node.js · Express

const integration = ShelfAI.integrate({
  client: existingModelClient,
  replay: runExistingWorkflow,
});
const modelClient = integration.client;
app.post(
  "/shelfai/replay",
  express.raw({ type: "application/json" }),
  integration.replayNodeHandler(),
);

Set SHELFAI_REPLAY_SECRET to the workspace signing secret and register the endpoint once. Normal capture remains fail-open; authenticated replay is fail-closed.

Verify the installation

The Python package includes two non-destructive checks. Run the first before a model call and the second after one observed run, using that run’s trace ID from shelfai_sdk.last_trace_id() or Workbench.

shelfai doctor
shelfai verify-integration --trace-id <trace-id>

Privacy and failure behavior

Metadata only

Records structure, types, timing, and relationships while withholding prompt, argument, result, and output text.

Full Capture

Makes selected context replayable while still applying secret scrubbing. Enable it only under the workspace’s approved data policy.

Normal telemetry is fail-open: if ShelfAI is disabled, misconfigured, or unreachable, the original client, tool return values, and application exceptions remain unchanged.

Release files

These are the exact public-beta artifacts for 0.3.0. Verify downloads with the published SHA-256 manifest.

Python wheel · shelfai_sdk-0.3.0-py3-none-any.whl Python source · shelfai_sdk-0.3.0.tar.gz Node package · shelfai-sdk-0.3.0.tgz SHA256SUMS

Earlier release: 0.2.0 (2026-09-04).