AgentShelf developer docs

Build on the AgentShelf external-agent runtime.

External Agents SDK

@agentshelf/external-agents-sdk is the public client SDK for embedding an AgentShelf agent into an application you control. It handles the public session lifecycle, policy negotiation, conversations, streaming, files, and artifacts — over public refs only.

The SDK is a client. It never creates or signs a bootstrap assertion: your trusted backend does that, and hands the SDK a callback to fetch one. That split is what keeps your AgentShelf credentials off the client.

import { createExternalAgentClient } from '@agentshelf/external-agents-sdk';

const client = createExternalAgentClient({
  externalAgentRef: 'ext_agent_public_12345678',
  apiBase: 'https://api.agentshelf.ai',
  getBootstrapAssertion: async () => {
    const response = await fetch('/api/agentshelf/bootstrap-assertion');
    return response.text();
  },
});

await client.ensure();

Where to start

If you want to…	Read
Get a client talking to the runtime	Getting started
Persist sessions across reloads	Sessions and storage
Know what your agent is allowed to do	Policy and capabilities
Give the agent a workspace-backed seat	Workspaces
Send a turn and render the response	Conversations and streaming
Upload files or read generated artifacts	Files and artifacts
Look up an exact type or method	API reference

Public refs only

Every value the SDK returns is a public ref. The runtime projects its internal model before it reaches you, so raw AgentShelf workspace IDs, runtime IDs, storage IDs, bucket names, and tool binding IDs are never exposed to a client. Design your integration around the *Ref values you receive; they are the stable contract.