@noetic-tools/managed-agents

Connect tools that run on your own machine to a Noetic managed agent. The SDK opens a real-time bidirectional WebSocket to the Noetic bridge, declares the tools it can run, and executes them when the agent (or any LLM driving the agent) calls them — returning the result so the run continues.

Install

npm install @noetic-tools/managed-agents zod

Usage

import { connect, defineTool } from "@noetic-tools/managed-agents";
import { z } from "zod";

const readClipboard = defineTool({
  name: "read_clipboard",
  description: "Read the user's current clipboard contents.",
  input: z.object({}),
  handler: async () => ({ text: await getClipboard() }),
});

const connection = connect({
  baseUrl: "https://platform.noetic.tools",
  agentId: "agent_123",
  apiKey: process.env.NOETIC_API_KEY, // account-wide: serves all users on the agent
  // — or — accessToken: workosToken,  // user-scoped: serves only that user
  tools: [readClipboard],
  onStatus: (s) => console.log("bridge:", s),
});

// later: connection.close();

• apiKey → an account-wide connection: receives tool calls for every user on the agent.
• accessToken (a WorkOS user token) → a user-scoped connection: receives only that user's tool calls.

Every tool call the agent dispatches carries the requesting userId and sessionId. A call routes to the most specific connected client (the matching user's machine, else an account-wide client); if none is connected within the wait window, the call fails and the workflow handles the error.

Subpath exports

• @noetic-tools/managed-agents — the client SDK (connect, defineTool).
• @noetic-tools/managed-agents/protocol — the shared wire protocol (frame schemas, parse*/serialize*, connect-token sign/verify, RPC types). Used by the server.
• @noetic-tools/managed-agents/server — server adapter: localToolFromDecl, jsonSchemaToZod (turns a declared tool into a @noetic-tools/core Tool).