@usenaive-sdk/managed-agents 0.0.0-stage → 0.12.0

package/README.md

@@ -1,3 +1,80 @@
-# Temporary Holding Version
+# @usenaive-sdk/managed-agents
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Typed TypeScript client for the Naive Managed Agents API — agents, sessions, identities, connections, vaults,
+comms, deployments, webhooks, the model proxy, and a resumable event stream. One method per route,
+parsed with the same schemas the server does.
+
+## Install
+
+```bash
+npm i @usenaive-sdk/managed-agents
+```
+
+## Usage
+
+```ts
+import { createClient } from "@usenaive-sdk/managed-agents";
+
+// `fetch` (default: the global one) and `idempotencyKey` (default: a random UUID per write) are optional.
+const client = createClient({ baseUrl: "https://api.vetta.sh", apiKey: process.env.NAIVE_API_KEY! });
+
+// `budget` is required: an agent with no spending ceiling is refused, not defaulted.
+const agent = await client.agents.create({
+  name: "Refunder",
+  model: "zai-org/GLM-5.2-FP8",
+  window: "immediate",
+  budget: { cap_micro_usd: 50_000_000, max_task_micro_usd: 5_000_000, period: "month" },
+});
+```
+
+## ESM only
+
+The package is **ESM-only** (no `require`). The examples use top-level `await`, which needs an
+ES module: set `"type": "module"` in `package.json`, or name the file `.mts` / `.mjs`. In a
+CommonJS project, load it with a dynamic import inside an async function:
+
+```ts
+async function main() {
+  const { createClient } = await import("@usenaive-sdk/managed-agents");
+  const client = createClient({ baseUrl: "https://api.vetta.sh", apiKey: process.env.NAIVE_API_KEY! });
+}
+main();
+```
+
+If `tsc` compiles your project, set `"module"` and `"moduleResolution"` to `"node16"` or `"nodenext"`
+in `tsconfig.json`. With `"module": "commonjs"`, tsc rewrites `import()` to `require()`, which fails
+with `ERR_PACKAGE_PATH_NOT_EXPORTED`. Running the file with `tsx` keeps the `import()` as written.
+
+## Configuring an agent's tools
+
+`configs` is replaced wholesale on the wire, so changing one tool by hand means resending every
+other one unchanged. `withTool` does that, and types the config the built-ins read —
+`WebToolConfig` (`web_search`, `web_fetch`) and `MediaToolConfig` (`generate_image`,
+`generate_video`). Omitted fields keep their current value and `config` merges key by key.
+
+```ts
+import { withTool } from "@usenaive-sdk/managed-agents";
+
+await client.agents.update(agent.id, {
+  tools: withTool(agent.tools, "web_fetch", {
+    permission: "ask",
+    config: { allowed_domains: ["docs.example.com"], max_content_tokens: 2000 },
+  }),
+});
+```
+
+## One model call, no session
+
+`client.proxy.messages` is the Messages-format endpoint: one org-level call with no agent, no
+tools and no state between calls. The completion window is the second argument, because the format
+has no field for one. Streaming is deliberately absent — point the Messages-format client you
+already have at `<baseUrl>/v1/proxy/anthropic`, which is what the endpoint exists for.
+
+```ts
+const reply = await client.proxy.messages(
+  { model: "openai/gpt-oss-120b", max_tokens: 1024, messages: [{ role: "user", content: "hi" }] },
+  "immediate",
+);
+```
+
+See the [TypeScript SDK reference](https://usenaive.ai/docs/sdk/typescript) for the full method index.