@zuora/agent-toolkit 0.1.0-alpha.1 → 0.1.0-beta.1

package/README.md

@@ -1,10 +1,21 @@
 # @zuora/agent-toolkit
 
-> **Alpha release** — APIs may change before the 1.0 stable release.
+> **Beta release — not intended for production use yet.** Customers are welcome to try the kit in sandbox or other non-production environments for evaluation and feedback. APIs may change before the 1.0 stable release.
 
-Zuora billing operations as callable tools for AI agent frameworks.
+## Introduction
 
-Built on the [Zuora MCP server](https://developer.zuora.com). Tool inventory is discovered at runtime from your tenant's MCP endpoint — it is not hardcoded in this package.
+Zuora Agent Kit is an SDK that turns Zuora billing operations into tools an AI agent can call. This package, `@zuora/agent-toolkit`, provides the TypeScript SDK; the Python package, `zuora-agent-toolkit`, is planned.
+
+Instead of wiring each Zuora REST API by hand for an LLM, the kit:
+
+1. Connects to your tenant's [Zuora MCP server](https://developer.zuora.com) using OAuth.
+2. Discovers available operations at runtime — the tool inventory is not hardcoded.
+3. Normalizes them into a shared tool shape, `ZuoraToolDefinition`.
+4. Exposes them in the format your agent framework expects: OpenAI Chat Completions, OpenAI Agents SDK, LangChain, or Vercel AI SDK.
+
+Your agent can then do things like "list accounts" or "run a query" through tool calls, while the kit handles authentication, filtering (read-only vs. writes and tool bundles), approval rules, and observability.
+
+To discover the bundles and tools available for your tenant, see [Discovery and execution](#discovery-and-execution) below.
 
 ## Quick start
 
@@ -36,6 +47,11 @@ Set `ZUORA_BASE_URL`, `ZUORA_CLIENT_ID`, and `ZUORA_CLIENT_SECRET` in your envir
 
 ## Changelog
 
+### [0.1.0-beta.1]
+
+- First beta release — customers are welcome to evaluate it in sandbox or other non-production environments; it is **not intended for production use yet**.
+- Added an introduction explaining runtime tool discovery, the shared tool definition, framework adapters, and built-in safety and observability controls.
+
 ### [0.1.0-alpha.1]
 
 - Fixed HITL approval policy handling with correct `request.environment` usage
@@ -52,7 +68,7 @@ Initial alpha release.
 Requires **Node.js 18** or later.
 
 ```bash
-npm install @zuora/agent-toolkit
+npm install @zuora/agent-toolkit@beta
 ```
 
 Framework packages are peer dependencies — install only what you use:
@@ -361,7 +377,11 @@ configuration: {
 
 ### Approval policy
 
-Gate write / high-risk operations before they reach Zuora. `approvalPolicy` is a **top-level** config field (not inside `configuration`):
+Approval policies are checked before a tool executes. An `"allow"` decision lets execution proceed; `"deny"` blocks it with an `APPROVAL_REJECTED` error. If no policy is configured, no additional approval check is performed.
+
+Approval policies are an additional guardrail, not a way to enable writes: write operations must also be enabled through `configuration.mode: SafetyMode.WriteEnabled`. The read-only execution guard runs before the approval policy.
+
+`approvalPolicy` is a **top-level** config field (not inside `configuration`):
 
 ```ts
 import { ApprovalPolicyPreset, SafetyMode } from "@zuora/agent-toolkit";
@@ -378,9 +398,29 @@ const toolkit = await createZuoraOpenAIAgentToolkit({
 });
 ```
 
-Presets: `Off`, `AllWrites`, `HighRisk`, `ProductionWrites`, `ProductionHighRisk`.
+Built-in presets automatically allow or deny operations; they do **not** display an approval prompt. Operations that do not match a preset's denial condition are allowed by that policy.
+
+| Preset | Behavior |
+|---|---|
+| `Off` | No additional approval restriction |
+| `AllWrites` | Denies all write operations |
+| `HighRisk` | Denies all high-risk operations, including reads |
+| `ProductionWrites` | Denies writes when the detected environment is production |
+| `ProductionHighRisk` | Denies high-risk operations when the detected environment is production |
+
+Custom handlers can be synchronous or async and receive:
+
+| Field | Contents |
+|---|---|
+| `request.tool` | Tool definition, including access and risk metadata for the invoked operation |
+| `request.input` | Arguments supplied to the tool |
+| `request.environment` | `"production"` or `"sandbox"`, inferred from `baseUrl` |
+
+**Environment detection:** unrecognized URLs currently default to `"sandbox"`. Production-only presets therefore do not block operations on unrecognized URLs; use a custom policy if your endpoint is not recognized as production.
+
+Custom handler return values: `"allow"` (proceed) · `"deny"` (block) · `{ decision: "allow" | "deny", reason?: string }`. Only `decision` is used; `reason` is not currently included in the rejection error.
 
-Custom handler return values: `"allow"` (proceed) · `"deny"` (block) · `{ decision: "allow" | "deny", reason?: string }` (with an explanation added to the rejection error).
+A custom async `approvalPolicy` can integrate your own approval workflow. For an example combining interactive approval through the OpenAI `shouldExecute` hook with an automated toolkit policy, see [`examples/openai/hitl.ts`](examples/openai/hitl.ts). In that example, the hook prompts before writes and returns a declined result to the model if the user refuses. The toolkit policy separately denies high-risk operations in production, even if the user approved them.
 
 ### Context
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zuora/agent-toolkit",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-beta.1",
   "description": "Zuora billing operations as callable tools for AI agent frameworks.",
   "type": "module",
   "exports": {