AgentM SDK Core

This worktree is the reduced AgentM SDK core. It keeps the substrate small: session lifecycle, trajectory persistence, extension loading, provider streams, tool execution, operations ports, and observability hooks. CLI, gateway peers, contrib scenarios, catalog machinery, and product-specific policies are outside this branch until the core abstraction is stable.

Core Abstraction

The SDK is mechanism, not policy. Policy enters through atoms.

Extension Contract

An atom is a Python module with:

from agentm.extensions import ExtensionManifest

MANIFEST = ExtensionManifest(
    name="my_atom",
    description="What this atom contributes.",
    registers=("tool:my_tool",),
    requires=(),
)

def install(api, config):
    ...

Atoms may depend on agentm.core.abi, agentm.core.lib, and the public agentm.extensions surface. The load-time validator rejects imports from agentm.core.runtime and agentm.core._internal; atoms must reach stateful runtime subsystems through AtomAPI methods and services.

Session Creation

The public path is AgentSession.create(AgentSessionConfig(...)).

from pathlib import Path

from agentm import AgentSession, AgentSessionConfig, LoopConfig, builtin_scenario_loader
from agentm.storage.trajectory import JsonlTrajectoryStore

session = await AgentSession.create(AgentSessionConfig(
    cwd=".",
    scenario="minimal",
    scenario_loader=builtin_scenario_loader,
    provider=("agentm.extensions.builtin.llm_openai", {"model": "gpt-4o"}),
    trajectory_store=JsonlTrajectoryStore(Path(".agentm/trajectory")),
    loop_config=LoopConfig(max_turns=8, max_tool_calls=32),
    tool_allowlist=["read", "bash"],
))

messages = await session.run("summarize src/agentm/core/abi")
await session.shutdown()

Use extensions=[...] to bypass scenario lookup entirely. The core runtime has no built-in scenario registry; pass builtin_scenario_loader to opt into the packaged scenario names in this reduced worktree:

Hosts that need named scenarios beyond these should pass AgentSessionConfig.scenario_loader.

pip install agentm is enough to run any atom this package ships, providers and observability included. The only extras are storage backends and the Harbor adapter, which a deployment opts into by naming one: agentm[storage-postgres], agentm[storage-clickhouse], agentm[harbor].

Persistence

TrajectoryStore owns durable session metadata, the current incomplete Turn checkpoint, committed turns, message nodes, explicit heads, and cache/compaction state. Every model/tool continuation commits a separate Turn with its own resource/effect transaction; all Turns produced by one external trigger share a run_id and increasing run_step. A committed Turn and its node/head indexes share one atomic publication boundary. Root metadata is created automatically before the session starts; child and forked sessions register their own metadata through the session graph path. SessionMeta.config persists the minimal resumable context (root_session_id, depth, scenario, and scenario_dir) so a child or fork can be loaded in a later process without losing its lineage.

AgentSessionConfig(trajectory_store=None) lets the SDK host resolver select the configured/default backend. Low-level core factories remain explicitly ephemeral when no store is supplied. Host programs that need resume or trace queries must select one store. Provider requests that fail after retries are persisted as non-replayable ProviderRequestFailed turns before the trigger receipt raises, so failed sessions do not collapse to an empty session header.

Built-in stores:

SQL-backed adapters are opened through the shared SQLAlchemy entry point in agentm.storage.sql; PostgreSQL and ClickHouse still require their optional driver extras.

The same TrajectoryStore exposes committed message-tree queries with stable node ids and portable index fields:

SQL stores implement these as normal indexed columns. JSONL stores replay the same per-session journal; they do not maintain a separately recoverable sidecar truth. ClickHouse is an optional OTLP observability backend, not a trajectory store. The SDK relies on the Protocol semantics, not on a JSONL layout.

Verification

uv sync
uv run ruff check src/ tests/
uv run mypy src/
uv run pytest --tb=short

Keep project-index.yaml synchronized with every code and test change, then validate it with:

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/validate_index.py project-index.yaml