Use ABot as a library

Use the bundled Web UI if you want to work with an agent today. Use the library when your application needs to own its interface, transport, persistence adapters, or integration lifecycle while reusing ABot’s execution engine.

Installing the package does not supply a language model or an automatically configured service. An embedded host still needs valid model configuration, reachable provider/model-gateway services as appropriate to its deployment, available tools, and explicit startup and shutdown ownership.

Import the public composition surface

Install @abot-ai/runtime in your TypeScript host project and create valid Runtime configuration using the installation guide. A minimal composition is:

import {
  createDefaultRuntimeDependencies,
  loadRuntimeConfig,
} from "@abot-ai/runtime/runtime";

const config = loadRuntimeConfig({ rootDir: process.cwd() });
const runtime = createDefaultRuntimeDependencies(config);

loadRuntimeConfig loads configuration from the chosen project root and supported environment overrides. Composition gives you the default host, sessions, attachments, tools, model client, and event factory. These lines compose dependencies; they do not open the Web UI or submit a conversation request.

Do not import internal implementation paths such as src/runtime/request or src/runtime/context. Public package exports define the integration boundary; internal loop and role modules may change independently.

Start and stop a host deliberately

The documented host composition passes the same dependency graph into the host:

const handle = runtime.host.start({
  runtimeConfig: config,
  runtimeId: config.runtimeId,
  agentBridgeUrl: config.agentBridgeUrl,
  agentBridgeToken: config.agentBridgeToken,
  eventSinkFactory: runtime.events,
  modelGatewayClient: runtime.models,
  sessionStore: runtime.sessions,
  attachmentStore: runtime.attachments,
  toolRegistry: runtime.tools,
});

await handle.ready;

process.on("SIGINT", async () => {
  await handle.stop();
  process.exit(0);
});

This is a host-lifecycle example, not a standalone HTTP chat endpoint. Follow the full library and bridge references for your transport and service arrangement. Do not assume this snippet also starts the model gateway, serves the bundled Web UI, or exposes a fictional runtime.chat() method.

The default host starts the scheduler, including persisted Jobs. Starting an embedded host can therefore resume its scheduling responsibilities; point a test integration at isolated state, not your everyday installation’s runtime directory. Await readiness so asynchronous startup errors are visible, and stop the host when your application shuts down. start() returns synchronously; the default host’s optional ready promise reports asynchronous startup. Custom injected hosts may retain a handle with only stop. Production hosts should integrate shutdown with their own process manager and signal handling.

Choose the boundary you need

Public entry point	Use it for
@abot-ai/runtime/runtime	Configuration loading and default runtime composition.
@abot-ai/runtime/runtime/ports	Types for implementing host-side interfaces.
@abot-ai/runtime/runtime/adapters	Built-in file-backed and in-memory adapters.
@abot-ai/runtime/plugin-sdk	Adding tools through the public plugin contract.
@abot-ai/runtime/model-gateway	Provider adapter integration.
@abot-ai/runtime/runtime.config.schema.json	The published runtime configuration schema.

Adapter overrides belong before host startup. Keep requests, session storage, tools, and scheduler work on the same effective dependency graph. Do not run the original and replacement graphs simultaneously against the same scheduler state directory.

Use the in-memory session adapter for intentionally short-lived integrations where durable session persistence is not required. Switching a session adapter does not make every other configured runtime service ephemeral; inspect the rest of the host’s storage configuration too.

Treat events as evidence with a lifecycle

The session store owns durable messages, request lifecycle, and persisted events. Event sequence matters: an early success event can be followed by a later failure.

A tool.completed event with ok: true means that tool step succeeded; it does not mean the user’s whole request is finished. Key integration logic off raw event names and fields, not translated display labels. When available, correlate tool activity with (requestId, executionId) rather than matching tool names or timing.

The public-contracts reference covers attachment ownership, event delivery, session persistence, and tool semantics in more detail. This guide intentionally introduces the integration surface rather than duplicating an exhaustive API reference or promising that a few lines of composition are a production-ready host.