@pilotoo/agent-runtime

Introduction

@pilotoo/agent-runtime runs the agents. It holds the graph factory, the tool and skill registries, the agent and model-profile sources, and the ports a host fills for identity, knowledge, models and usage. @pilotoo/server and @pilotoo/local-server both build on it. You import it directly when you write host tools, plug in an identity resolver or choose where attachments are stored.

Installation

@pilotoo/agent-runtime is at version 0.1.0 and is not published to a registry yet. A host gets it today by packing the tarballs from the kit repository:

pnpm install
pnpm release:check

release:check builds the release packages and writes one .tgz per package to node_modules/.cache/release-check/. Copy the tarballs you need into your project (for example vendor/) and depend on them as files:

{
  "dependencies": {
    "@pilotoo/agent-runtime": "file:vendor/pilotoo-agent-runtime-0.1.0.tgz"
  }
}

The release set (chat-protocol, chat-core, chat-ui, ui, agent-runtime, server, local-server) is versioned together: install every kit package you use at the same version. See Installation for the full setup.

Basic usage

Resolve the caller from a session your app already has, by asking your own endpoint who the token belongs to:

import { createHttpIdentityResolver } from '@pilotoo/agent-runtime';

export const identityResolver = createHttpIdentityResolver({
  url: `${process.env.API_URL}/auth/me`,
  map: (me) => ({ subject: me.user.id, tenant: me.tenant.id, roles: me.roles }),
});

Pass it to PilotooModule.forRoot({ identityResolver }). The tools shipped here, createWebSearchTool and createAskHumanTool, are registered the same way as your own.

Entry points

Import	Provides
`@pilotoo/agent-runtime`	`AgentRunner`, `createToolRegistry`, `createProviderRegistry`, the directory and file sources and stores for agents, profiles and skills, `createFileAttachmentStore`, `createS3AttachmentStore`, `createHttpIdentityResolver`, `createWebSearchTool`, `createAskHumanTool`.
`@pilotoo/agent-runtime/agent-backend`	The agent-backend module on its own: `createAgentBackend`, `EXECUTION_MODES`, and the folder lookups (`findRepoRoot`, `resolveConfigDir`, `resolveSkillsDir`, `resolveProfilesDir`). The root entry re-exports the same names.

Peer dependencies

None. LangChain, LangGraph and DeepAgents are regular dependencies.