Agent SDK Overview

The Agent SDK lets you build agents directly on CloudPeek's agentic runtime — the same state-machine loop that powers investigations, with retry, context compaction, plan mode, human-in-the-loop (HITL) gates, and durable session state — without running the CloudPeek API, frontend, or any supporting services.

It ships as a dedicated entry point of the core package:

import CloudPeek from "@cloudpeek/core/agent";

await CloudPeek.init({
  database: ":memory:",
  principal: { tenantId: "local", userId: "operator" },
});

const result = await CloudPeek.agent.run({
  input: "Summarise the failed logins from 10.0.0.0/8",
});

That's a complete agent: an in-memory database is created with the full schema, the loop runs against your configured LLM, and the result carries the conversation output plus run metadata.

What the SDK gives you

• The full agent loop — run() to completion or stream() for live events, with iteration caps, retry and error classification, context compaction, plan mode, and failure recovery built in.
• Human-in-the-loop — approval gates on tool calls, driven by the same modes as the CloudPeek app (external_write_only, external_only, approval_only), surfaced through a simple pending / approve / deny API. See Building Agents.
• Custom tools — thread your own tools in with one callback, declare them read-only for precise approval gating, or run them client-side with the suspend/resume handoff.
• Playbook ingestion — hand the runtime a playbook source and the agent discovers and follows your operational playbooks through its built-in playbook_list / playbook_execute tools.
• Durable sessions — every run persists to SQLite or Postgres; inspect and manage runs through the sessions namespace.
• Direct LLM access — text / json / embed helpers on the same configured provider, no agent loop required.

Runtime and requirements

• Bun ≥ 1.1. The package targets the Bun runtime (bun:sqlite powers standalone persistence). Node.js is not currently supported.
• A database. ":memory:" or a sqlite:///path.db file for standalone agents — the SDK creates the schema itself. A Postgres URL for shared infrastructure — the SDK verifies the schema and fails closed unless you opt in with migrate: true, so an embedded agent never migrates a shared database silently.
• An LLM provider. Configure explicitly via llm, or let the SDK build a default from the environment (AWS_BEARER_TOKEN_BEDROCK for Bedrock, or LLM__OPENAI_BASE_URL / LLM__OPENAI_API_KEY for any OpenAI-compatible endpoint).

One runtime, two entry styles

CloudPeek.init(options) configures a module-wide default instance; after that, every capability is reachable directly on the import — CloudPeek.agent.run(...), CloudPeek.hitl.pending(), CloudPeek.llm.text(...). Using a namespace before init() throws a structured CloudPeekNotInitializedError.

For processes that need more than one runtime — test suites, multi-tenant servers — CloudPeek.create(options) returns an isolated instance with the identical surface, and .as(principal) gives you a cheap view of the same runtime bound to a different tenant:

const peek = await CloudPeek.create({ database: "sqlite:///agents.db" });
const tenantA = peek.as({ tenantId: "tenant-a" });
const tenantB = peek.as({ tenantId: "tenant-b" });

Identity: you are the operator

The SDK never authenticates. A PrincipalContext — tenantId, optional userId, roles, and an opaque token — is threaded through every call, and your application decides what those values mean. On Postgres, row-level security enforces the tenant boundary; on SQLite the SDK enforces tenant ownership on session access, and broader isolation is your application's responsibility. This is the same trust model the platform documents for embedded harnesses: the embedding application is the operator.

Relationship to the Responses API

If you are calling a running CloudPeek deployment over HTTP, use the AI Responses API — same loop, same HITL, platform-managed authentication. The SDK is for the embedded case: your own process, your own tools, your own identity model, no server required.