Quickstart

Conceptual

Authenticate, submit your first objective, and stream the execution trace.

This walkthrough submits a research objective and streams the resulting run. The interfaces below reflect the proposed v1 API surface.

1. Install the SDK#

bash

npm install @pimsy/sdk

2. Configure credentials#

API keys are scoped to a workspace and carry an explicit capability set. A key that cannot spend cannot be made to spend by a prompt.

.env

PIMSY_API_KEY=pk_live_...
PIMSY_WORKSPACE=ws_engineering

3. Submit an objective#

import { Pimsy } from class="tok-str">"@pimsy/sdk";

const pimsy = new Pimsy({ apiKey: process.env.PIMSY_API_KEY });

const task = await pimsy.tasks.create({
  objective:
    class="tok-str">"Compare the three largest open-source vector databases on ingest throughput, filtering support and license, then produce a recommendation memo.",
  capabilities: [class="tok-str">"research.web", class="tok-str">"files.write"],
  budget: { steps: class="tok-num">40, wallClockSeconds: class="tok-num">900 },
  completion: {
    criteria: [
      class="tok-str">"At least class="tok-num">6 independent sources cited",
      class="tok-str">"Explicit trade-off table",
      class="tok-str">"Stated confidence per claim"
    ]
  }
});

console.log(task.id, task.status);

4. Stream the run#

Runs emit typed events. Subscribe to watch planning, tool calls and verification as they happen; see Streaming for the full event catalogue.

stream.ts

for await (const event of pimsy.runs.stream(task.id)) {
  switch (event.type) {
    case class="tok-str">"plan.created":
      console.log(class="tok-str">"plan", event.plan.steps.length, class="tok-str">"steps");
      break;
    case class="tok-str">"step.started":
      console.log(class="tok-str">"→", event.step.title);
      break;
    case class="tok-str">"tool.called":
      console.log(class="tok-str">"  tool", event.tool.name, event.tool.durationMs + class="tok-str">"ms");
      break;
    case class="tok-str">"verification.completed":
      console.log(class="tok-str">"  verified:", event.result.passed);
      break;
    case class="tok-str">"task.completed":
      console.log(class="tok-str">"done", event.artifacts.map(a => a.path));
      break;
  }
}

5. Read the result#

task.completed

{
  class="tok-str">"id": class="tok-str">"task_8fq2m1",
  class="tok-str">"status": class="tok-str">"completed",
  class="tok-str">"steps_executed": class="tok-num">27,
  class="tok-str">"artifacts": [
    { class="tok-str">"path": class="tok-str">"memo.md", class="tok-str">"bytes": class="tok-num">18420, class="tok-str">"type": class="tok-str">"document" },
    { class="tok-str">"path": class="tok-str">"sources.json", class="tok-str">"bytes": class="tok-num">5310, class="tok-str">"type": class="tok-str">"dataset" }
  ],
  class="tok-str">"verification": {
    class="tok-str">"passed": true,
    class="tok-str">"checks": [class="tok-str">"citations_resolvable", class="tok-str">"table_completeness", class="tok-str">"no_contradictions"]
  },
  class="tok-str">"confidence": class="tok-str">"medium-high",
  class="tok-str">"usage": { class="tok-str">"steps": class="tok-num">27, class="tok-str">"tool_calls": class="tok-num">41, class="tok-str">"wall_clock_seconds": class="tok-num">412 }
}

Next steps#

First Agent RunA fully annotated end-to-end run with trace output.Core ConceptsThe vocabulary used throughout the rest of the documentation.

Last updated 2026-09-15