@agenttool/sdk 0.1.0 → 0.2.2

package/README.md

@@ -1,32 +1,220 @@
-# agenttool
+# @agenttool/sdk · TypeScript
 
-TypeScript SDK for [agenttool.dev](https://agenttool.dev) — memory and tools for AI agents.
+> Persistent memory, verified actions, and tool access for AI agents — one API key.
 
+[![npm](https://img.shields.io/npm/v/@agenttool/sdk)](https://www.npmjs.com/package/@agenttool/sdk)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+```bash
+npm install @agenttool/sdk
+# or
+bun add @agenttool/sdk
+```
+
+## What is this?
+
+AgentTool gives AI agents the infrastructure they need to operate reliably:
+
+| Service | What it does |
+|---------|-------------|
+| **agent-memory** | Persistent semantic memory — store facts, retrieve by similarity |
+| **agent-tools** | Web search, page scraping, code execution |
+| **agent-verify** | SHA-256 proof-of-work attestations with timestamps |
+| **agent-economy** | Wallets, credits, agent-to-agent billing |
+
+All four services, one API key, one SDK.
+
+## Quick start (60 seconds)
+
+**1. Get your API key** — create a free project at [app.agenttool.dev](https://app.agenttool.dev)
+
+**2. Set your key:**
 ```bash
-npm install agenttool
+export AT_API_KEY=at_your_key_here
 ```
 
+**3. Store and retrieve a memory:**
 ```typescript
-import { AgentTool } from "agenttool";
+import { AgentTool } from "@agenttool/sdk";
 
 const at = new AgentTool(); // reads AT_API_KEY from env
 
-// Memory
-await at.memory.store("learned something new");
-const results = await at.memory.search("what did I learn?");
-const mem = await at.memory.get("mem-id");
-const usage = await at.memory.usage();
+// Store a memory
+const memory = await at.memory.store({
+  content: "The user prefers dark mode and concise responses",
+  agentId: "my-assistant",
+  tags: ["preference", "ui"],
+});
+
+// Retrieve it later (semantic search)
+const results = await at.memory.search({
+  query: "what does the user prefer?",
+  limit: 5,
+});
+
+for (const result of results) {
+  console.log(`${result.score.toFixed(2)}  ${result.content}`);
+}
+```
+
+## Usage
+
+### Memory
+
+```typescript
+import { AgentTool } from "@agenttool/sdk";
+
+const at = new AgentTool({ apiKey: "at_..." }); // or use AT_API_KEY env var
+
+// Store
+const mem = await at.memory.store({
+  content: "User is based in London, timezone Europe/London",
+});
+
+// Search (semantic)
+const results = await at.memory.search({ query: "where is the user?" });
+
+// Retrieve by ID
+const mem2 = await at.memory.get("mem_...");
+
+// Delete
+await at.memory.delete("mem_...");
+```
+
+### Tools
+
+```typescript
+// Web search
+const results = await at.tools.search({ query: "latest papers on RAG", numResults: 5 });
+for (const r of results) {
+  console.log(r.title, r.url);
+}
+
+// Scrape a page
+const page = await at.tools.scrape({ url: "https://example.com" });
+console.log(page.text);
+
+// Execute code
+const output = await at.tools.execute({ code: "console.log(Math.PI)" });
+console.log(output.stdout);
+```
+
+### Verify
+
+```typescript
+// Create an attestation
+const proof = await at.verify.create({
+  action: "task_completed",
+  agentId: "my-agent",
+  payload: { task: "data_analysis", rowsProcessed: 1500 },
+});
+console.log(proof.attestationId, proof.hash);
+
+// Verify an attestation
+const result = await at.verify.check("att_...");
+console.log(result.valid); // true
+```
+
+### Economy
+
+```typescript
+// Create a wallet
+const wallet = await at.economy.createWallet({ name: "agent-wallet" });
+
+// Check balance
+const { balance } = await at.economy.getBalance(wallet.id);
+
+// Transfer credits
+await at.economy.transfer({
+  fromWallet: wallet.id,
+  toWallet: "wlt_...",
+  amount: 10,
+  memo: "payment for search service",
+});
+```
+
+## Integration example — Vercel AI SDK
 
-// Tools
-const hits = await at.tools.search("latest AI news");
-const page = await at.tools.scrape("https://example.com");
-const out = await at.tools.execute("print(1 + 1)");
+```typescript
+import { AgentTool } from "@agenttool/sdk";
+import { tool } from "ai";
+import { z } from "zod";
 
-// Verify
-const v = await at.verify.check("The Earth is round");
+const at = new AgentTool();
 
-// Economy
-const wallet = await at.economy.createWallet({ name: "my-wallet" });
+export const memoryTools = {
+  remember: tool({
+    description: "Store a memory for later retrieval",
+    parameters: z.object({ content: z.string() }),
+    execute: async ({ content }) => {
+      const mem = await at.memory.store({ content, agentId: "vercel-ai-agent" });
+      return { id: mem.id, stored: true };
+    },
+  }),
+  recall: tool({
+    description: "Search past memories by semantic similarity",
+    parameters: z.object({ query: z.string() }),
+    execute: async ({ query }) => {
+      const results = await at.memory.search({ query, limit: 5 });
+      return results.map((r) => ({ content: r.content, score: r.score }));
+    },
+  }),
+};
 ```
 
-Set your key: `export AT_API_KEY=your-key-here`
+## Integration example — any agent loop
+
+```typescript
+import { AgentTool } from "@agenttool/sdk";
+
+const at = new AgentTool();
+
+async function agentLoop(userMessage: string): Promise<string> {
+  // Recall relevant memories
+  const memories = await at.memory.search({ query: userMessage, limit: 5 });
+  const context = memories.map((m) => m.content).join("\n");
+
+  // Call your LLM with context
+  const response = await yourLLM(`Context:\n${context}\n\nUser: ${userMessage}`);
+
+  // Store the exchange
+  await at.memory.store({ content: `User: ${userMessage}\nAgent: ${response}` });
+
+  return response;
+}
+```
+
+## Free tier
+
+| Resource | Free | Seed ($29/mo) | Grow ($99/mo) |
+|----------|------|----------------|----------------|
+| Memory ops/day | 100 | 10,000 | 100,000 |
+| Tool calls/day | 10 | 500 | 5,000 |
+| Verifications/day | 5 | 100 | 1,000 |
+
+[Upgrade at app.agenttool.dev/billing](https://app.agenttool.dev/billing)
+
+## Configuration
+
+```typescript
+import { AgentTool } from "@agenttool/sdk";
+
+const at = new AgentTool({
+  apiKey: "at_...",                          // default: AT_API_KEY env var
+  baseUrl: "https://api.agenttool.dev",      // default
+  timeout: 30_000,                           // ms, default 30s
+});
+```
+
+## Links
+
+- 🏠 [agenttool.dev](https://agenttool.dev)
+- 📖 [docs.agenttool.dev](https://docs.agenttool.dev)
+- 🎛️ [app.agenttool.dev](https://app.agenttool.dev) — dashboard + API key
+- 📦 [npm](https://www.npmjs.com/package/@agenttool/sdk)
+- 🐍 [Python SDK](https://github.com/cambridgetcg/agenttool-sdk-py)
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -4,6 +4,7 @@
 import { EconomyClient } from "./economy.js";
 import { MemoryClient } from "./memory.js";
 import { ToolsClient } from "./tools.js";
+import { TracesClient } from "./traces.js";
 import { VerifyClient } from "./verify.js";
 /**
  * Unified client for the agenttool.dev platform.
@@ -20,6 +21,7 @@ import { VerifyClient } from "./verify.js";
  * const out = await at.tools.execute("print(42)");      // sandbox
  * const v = await at.verify.check("claim");             // verify
  * const w = await at.economy.createWallet({ name: "w" }); // wallet
+ * const t = await at.traces.store({ observations: ["saw X"], conclusion: "do Y" }); // trace
  * ```
  */
 export declare class AgentTool {
@@ -28,6 +30,7 @@ export declare class AgentTool {
     private _tools;
     private _verify;
     private _economy;
+    private _traces;
     /**
      * Create a new AgentTool client.
      *
@@ -46,5 +49,7 @@ export declare class AgentTool {
     get verify(): VerifyClient;
     /** Access the Economy/Wallet API. */
     get economy(): EconomyClient;
+    /** Access the Traces (reasoning provenance) API. */
+    get traces(): TracesClient;
     toString(): string;
 }

package/dist/client.js

@@ -5,6 +5,7 @@ import { AgentToolError } from "./errors.js";
 import { EconomyClient } from "./economy.js";
 import { MemoryClient } from "./memory.js";
 import { ToolsClient } from "./tools.js";
+import { TracesClient } from "./traces.js";
 import { VerifyClient } from "./verify.js";
 /**
  * Unified client for the agenttool.dev platform.
@@ -21,6 +22,7 @@ import { VerifyClient } from "./verify.js";
  * const out = await at.tools.execute("print(42)");      // sandbox
  * const v = await at.verify.check("claim");             // verify
  * const w = await at.economy.createWallet({ name: "w" }); // wallet
+ * const t = await at.traces.store({ observations: ["saw X"], conclusion: "do Y" }); // trace
  * ```
  */
 export class AgentTool {
@@ -29,6 +31,7 @@ export class AgentTool {
     _tools;
     _verify;
     _economy;
+    _traces;
     /**
      * Create a new AgentTool client.
      *
@@ -70,6 +73,11 @@ export class AgentTool {
         this._economy ??= new EconomyClient(this.http);
         return this._economy;
     }
+    /** Access the Traces (reasoning provenance) API. */
+    get traces() {
+        this._traces ??= new TracesClient(this.http);
+        return this._traces;
+    }
     toString() {
         return `AgentTool(baseUrl=${JSON.stringify(this.http.baseUrl)})`;
     }

package/dist/index.d.ts

@@ -11,4 +11,5 @@
  */
 export { AgentTool } from "./client.js";
 export { AgentToolError } from "./errors.js";
+export type { Trace, StoreTraceOptions, SearchTracesOptions, TraceSearchResult, TraceChain } from "./traces.js";
 export type { CreateWalletOptions, ExecuteResult, Memory, ScrapeResult, SearchMemoryOptions, SearchResponse, SearchResult, StoreOptions, UsageStats, VerifyResult, Wallet, } from "./types.js";

package/dist/tools.js

@@ -31,7 +31,7 @@ export class ToolsClient {
             query,
             num_results: options?.num_results ?? 5,
         };
-        const data = (await this.post("/v1/search", body));
+        const data = (await this.post("/v1/search/search", body));
         // Normalize: API may return results at top level or nested
         const results = Array.isArray(data)
             ? data
@@ -49,7 +49,7 @@ export class ToolsClient {
      * @returns ScrapeResult with the page content.
      */
     async scrape(url) {
-        const data = await this.post("/v1/scrape", { url });
+        const data = await this.post("/v1/scrape/scrape", { url });
         return data;
     }
     /**

package/dist/traces.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Traces client for the agent-trace reasoning provenance API.
+ */
+import type { HttpConfig } from "./memory.js";
+/** A stored reasoning trace. */
+export interface Trace {
+    id: string;
+    trace_id: string;
+    agent_id?: string;
+    project_id: string;
+    session_id?: string;
+    created_at: string;
+    decision_type: string;
+    decision_summary: string;
+    output_ref?: string;
+    observations: string[];
+    hypothesis?: string;
+    conclusion: string;
+    confidence?: number;
+    alternatives?: string[];
+    signals?: Record<string, unknown>;
+    files_read?: string[];
+    key_facts?: string[];
+    external_signals?: Record<string, unknown>;
+    tags?: string[];
+    parent_trace_id?: string;
+}
+/** Options for storing a trace. */
+export interface StoreTraceOptions {
+    /** Free-form observation strings that led to the decision. */
+    observations: string[];
+    /** What was concluded / decided. */
+    conclusion: string;
+    /** One of: tool_call | memory_write | plan | decision | verification | other */
+    decision_type?: string;
+    /** Short human-readable summary of the decision. */
+    decision_summary?: string;
+    agent_id?: string;
+    session_id?: string;
+    output_ref?: string;
+    hypothesis?: string;
+    confidence?: number;
+    alternatives?: string[];
+    tags?: string[];
+    parent_trace_id?: string;
+    files_read?: string[];
+    key_facts?: string[];
+}
+/** A search result entry. */
+export interface TraceSearchResult {
+    trace: Trace;
+    score: number;
+}
+/** Options for searching traces. */
+export interface SearchTracesOptions {
+    /** Maximum number of results (default 10). */
+    limit?: number;
+    /** Filter by agent_id. */
+    agent_id?: string;
+    /** Filter by session_id. */
+    session_id?: string;
+    /** Filter by tag. */
+    tag?: string;
+}
+/** A reasoning chain (parent + children). */
+export interface TraceChain {
+    parent: Trace;
+    children: Trace[];
+    depth: number;
+}
+/**
+ * Client for the agent-trace reasoning provenance API.
+ *
+ * @example
+ * ```ts
+ * const at = new AgentTool();
+ *
+ * // Store a reasoning trace
+ * const trace = await at.traces.store({
+ *   observations: ["User asked about pricing", "Checked tier table"],
+ *   conclusion: "User is on Free tier, eligible to upgrade",
+ *   decision_type: "decision",
+ *   tags: ["billing", "upgrade"],
+ * });
+ *
+ * // Search traces semantically
+ * const results = await at.traces.search("billing decisions", { limit: 5 });
+ *
+ * // Retrieve a specific trace
+ * const t = await at.traces.get(trace.trace_id);
+ * ```
+ */
+export declare class TracesClient {
+    private readonly http;
+    /** @internal */
+    constructor(http: HttpConfig);
+    /**
+     * Store a reasoning trace.
+     *
+     * @param options - Trace content (observations + conclusion required).
+     * @returns The created Trace object with its trace_id.
+     */
+    store(options: StoreTraceOptions): Promise<Trace>;
+    /**
+     * Retrieve a trace by its trace_id.
+     *
+     * @param traceId - The trace_id returned by store().
+     */
+    get(traceId: string): Promise<Trace>;
+    /**
+     * Search traces by semantic similarity.
+     *
+     * @param query - Natural language query.
+     * @param options - Filters: limit, agent_id, session_id, tag.
+     * @returns Ranked list of matching traces with similarity scores.
+     */
+    search(query: string, options?: SearchTracesOptions): Promise<TraceSearchResult[]>;
+    /**
+     * Retrieve the reasoning chain for a trace (parent + all children).
+     *
+     * @param traceId - The parent trace_id.
+     */
+    chain(traceId: string): Promise<TraceChain>;
+    /**
+     * Delete a trace.
+     *
+     * @param traceId - The trace_id to delete.
+     */
+    delete(traceId: string): Promise<void>;
+    private _errorDetail;
+}

package/dist/traces.js

@@ -0,0 +1,167 @@
+/**
+ * Traces client for the agent-trace reasoning provenance API.
+ */
+import { AgentToolError } from "./errors.js";
+/**
+ * Client for the agent-trace reasoning provenance API.
+ *
+ * @example
+ * ```ts
+ * const at = new AgentTool();
+ *
+ * // Store a reasoning trace
+ * const trace = await at.traces.store({
+ *   observations: ["User asked about pricing", "Checked tier table"],
+ *   conclusion: "User is on Free tier, eligible to upgrade",
+ *   decision_type: "decision",
+ *   tags: ["billing", "upgrade"],
+ * });
+ *
+ * // Search traces semantically
+ * const results = await at.traces.search("billing decisions", { limit: 5 });
+ *
+ * // Retrieve a specific trace
+ * const t = await at.traces.get(trace.trace_id);
+ * ```
+ */
+export class TracesClient {
+    http;
+    /** @internal */
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * Store a reasoning trace.
+     *
+     * @param options - Trace content (observations + conclusion required).
+     * @returns The created Trace object with its trace_id.
+     */
+    async store(options) {
+        const body = {
+            observations: options.observations,
+            conclusion: options.conclusion,
+            decision_type: options.decision_type ?? "decision",
+            decision_summary: options.decision_summary ?? options.conclusion.slice(0, 120),
+        };
+        if (options.agent_id !== undefined)
+            body.agent_id = options.agent_id;
+        if (options.session_id !== undefined)
+            body.session_id = options.session_id;
+        if (options.output_ref !== undefined)
+            body.output_ref = options.output_ref;
+        if (options.hypothesis !== undefined)
+            body.hypothesis = options.hypothesis;
+        if (options.confidence !== undefined)
+            body.confidence = options.confidence;
+        if (options.alternatives !== undefined)
+            body.alternatives = options.alternatives;
+        if (options.tags !== undefined)
+            body.tags = options.tags;
+        if (options.parent_trace_id !== undefined)
+            body.parent_trace_id = options.parent_trace_id;
+        if (options.files_read !== undefined)
+            body.files_read = options.files_read;
+        if (options.key_facts !== undefined)
+            body.key_facts = options.key_facts;
+        const resp = await globalThis.fetch(`${this.http.baseUrl}/v1/traces`, {
+            method: "POST",
+            headers: this.http.headers,
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(this.http.timeout),
+        });
+        if (resp.status >= 400) {
+            const detail = await this._errorDetail(resp);
+            throw new AgentToolError(`Traces API error (${resp.status}): ${detail}`);
+        }
+        const created = (await resp.json());
+        // Return the full trace by fetching it
+        return this.get(created.trace_id);
+    }
+    /**
+     * Retrieve a trace by its trace_id.
+     *
+     * @param traceId - The trace_id returned by store().
+     */
+    async get(traceId) {
+        const resp = await globalThis.fetch(`${this.http.baseUrl}/v1/traces/${traceId}`, {
+            headers: this.http.headers,
+            signal: AbortSignal.timeout(this.http.timeout),
+        });
+        if (resp.status >= 400) {
+            const detail = await this._errorDetail(resp);
+            throw new AgentToolError(`Traces API error (${resp.status}): ${detail}`);
+        }
+        return (await resp.json());
+    }
+    /**
+     * Search traces by semantic similarity.
+     *
+     * @param query - Natural language query.
+     * @param options - Filters: limit, agent_id, session_id, tag.
+     * @returns Ranked list of matching traces with similarity scores.
+     */
+    async search(query, options) {
+        const body = {
+            query,
+            limit: options?.limit ?? 10,
+        };
+        if (options?.agent_id !== undefined)
+            body.agent_id = options.agent_id;
+        if (options?.session_id !== undefined)
+            body.session_id = options.session_id;
+        if (options?.tag !== undefined)
+            body.tag = options.tag;
+        const resp = await globalThis.fetch(`${this.http.baseUrl}/v1/traces/search`, {
+            method: "POST",
+            headers: this.http.headers,
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(this.http.timeout),
+        });
+        if (resp.status >= 400) {
+            const detail = await this._errorDetail(resp);
+            throw new AgentToolError(`Traces API error (${resp.status}): ${detail}`);
+        }
+        return (await resp.json());
+    }
+    /**
+     * Retrieve the reasoning chain for a trace (parent + all children).
+     *
+     * @param traceId - The parent trace_id.
+     */
+    async chain(traceId) {
+        const resp = await globalThis.fetch(`${this.http.baseUrl}/v1/traces/chain/${traceId}`, {
+            headers: this.http.headers,
+            signal: AbortSignal.timeout(this.http.timeout),
+        });
+        if (resp.status >= 400) {
+            const detail = await this._errorDetail(resp);
+            throw new AgentToolError(`Traces API error (${resp.status}): ${detail}`);
+        }
+        return (await resp.json());
+    }
+    /**
+     * Delete a trace.
+     *
+     * @param traceId - The trace_id to delete.
+     */
+    async delete(traceId) {
+        const resp = await globalThis.fetch(`${this.http.baseUrl}/v1/traces/${traceId}`, {
+            method: "DELETE",
+            headers: this.http.headers,
+            signal: AbortSignal.timeout(this.http.timeout),
+        });
+        if (resp.status >= 400) {
+            const detail = await this._errorDetail(resp);
+            throw new AgentToolError(`Traces API error (${resp.status}): ${detail}`);
+        }
+    }
+    async _errorDetail(resp) {
+        try {
+            const json = (await resp.json());
+            return json.detail ?? resp.statusText;
+        }
+        catch {
+            return resp.statusText;
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agenttool/sdk",
-  "version": "0.1.0",
+  "version": "0.2.2",
   "description": "TypeScript SDK for agenttool.dev — memory and tools for AI agents",
   "type": "module",
   "main": "dist/index.js",