SDK Reference

Lantern ships a TypeScript SDK (@lantern/sdk) and a Python SDK (lantern). Both cover the full management surface — agents, runs, sessions, connectors, budgets, evals, experiments, marketplace, MCP, receipts, feedback, and rehearsals.

TypeScript SDK

Installation

npm install @lantern/sdk

Client setup

import { LanternClient } from "@lantern/sdk";

const client = new LanternClient({
  apiKey: process.env.LANTERN_API_KEY,   // hlx_live_...
  baseUrl: process.env.LANTERN_API_URL,  // http://localhost:8080 for self-hosted
});

Creating and streaming a run

// Create a run
const run = await client.runs.create({
  agentName: "research-agent",
  input: { topic: "quantum computing" },
});

console.log(run.id, run.status); // queued

// Stream events for the run
for await (const event of client.runs.stream(run.id)) {
  console.log(event.kind, event.stepId, event.payload);
  // kinds: step_started, step_completed, step_failed, step_retrying, step_waiting
}

// Fetch final result
const finished = await client.runs.get(run.id);
console.log(finished.status, finished.output);

Interactive sessions

// Create a session
const session = await client.sessions.create({ agent: "my-agent" });

// Stream a message turn
for await (const chunk of client.sessions.streamMessage(session.id, {
  content: "What is the capital of France?",
})) {
  // chunk has: kind ("message_delta" | "message_completed" | "message_error")
  if (chunk.kind === "message_delta") process.stdout.write(chunk.delta);
  if (chunk.kind === "message_completed") console.log("
Done:", chunk.usage);
}

// Non-streaming send
const reply = await client.sessions.sendMessage(session.id, {
  content: "Follow-up question",
});

// Cleanup
await client.sessions.delete(session.id);

All namespaces

client.agents          // create, get, list, delete, generateSpec, generateCode
client.runs            // create, get, list, stream, forecast
client.sessions        // create, get, list, sendMessage, streamMessage, stop, delete
client.connectors      // install, list, execute, test, uninstall
client.budgets         // upsert, get, list, delete
client.experiments     // create, get, list, record, conclude
client.evals           // createSuite, getSuite, listSuites, createRun, listRuns, setBaseline
client.marketplace     // list, get, publish, fork, star, unstar
client.mcp             // listServers, getServer, attach, listAttachments, detach
client.receipts        // issue, verify
client.feedback        // submit, list, summary
client.rehearsals      // create

Error handling

import { LanternError, MessageStreamError } from "@lantern/sdk";

try {
  const run = await client.runs.create({ agentName: "my-agent", input: {} });
} catch (err) {
  if (err instanceof LanternError) {
    console.error(err.status, err.message);
  }
}

// Errors during a session stream
try {
  for await (const chunk of client.sessions.streamMessage(id, { content: "hi" })) {
    // ...
  }
} catch (err) {
  if (err instanceof MessageStreamError) {
    console.error("stream error:", err.message);
  }
}

Python SDK

Installation

pip install ./packages/sdk-python

Client setup

from lantern import LanternClient

client = LanternClient(
    api_key="hlx_live_your_key",   # or LANTERN_API_KEY env var
    base_url="http://localhost:8080",  # or LANTERN_API_URL env var
)

Creating a run

run = client.runs.create(agent_name="research-agent", input={"topic": "AI safety"})
print(run.id, run.status)  # queued

All namespaces

client.agents          # create, get, list, delete
client.runs            # create, get, list, forecast
client.sessions        # create, get, list, send_message, stop, delete
client.connectors      # install, list, execute, test, uninstall
client.budgets         # upsert, get, list, delete
client.evals           # create_suite, list_suites, create_run, set_baseline
client.experiments     # create, record, conclude
client.marketplace     # list, get, publish, fork, star
client.mcp             # list_servers, attach, list_attachments, detach
client.receipts        # issue, verify
client.feedback        # submit, list, summary
client.rehearsals      # create

Example: list agents

agents = client.agents.list()
for agent in agents:
    print(agent.name, agent.current_version_id)

Agent runtime (TypeScript)

Inside an agent bundle, the runtime context gives you durable steps, LLM calls, connector access, and more:

import { agent, step } from "@lantern/sdk";

export default agent({
  name: "my-agent",
  model: "auto",

  async run({ input, ctx }) {
    // Durable step — journaled, idempotent, resumable on crash
    const data = await step("fetch-data", async () => {
      return ctx.tools.web.search(input.query);
    });

    // LLM call — routed by capability, never hardcoded to a vendor
    const summary = await step("summarize", async () => {
      return ctx.llm.complete({
        messages: [{ role: "user", content: `Summarize: ${data}` }],
        capability: "reasoning-small",
      });
    });

    return { summary };
  },
});

Parallel fan-out

const results = await step.map("search", queries, async (query) => {
  return ctx.tools.web.search(query);
});

Human approval

const approved = await ctx.human.requestApproval({
  message: "Send this email to 500 users?",
  timeout: "30m",  // goroutine is released while waiting — no compute cost
});

if (!approved) return { status: "cancelled" };