@zuora/agent-toolkit 0.0.1-alpha.0

package/dist/openai-agents/index.d.ts

@@ -0,0 +1,94 @@
+import { tool } from '@openai/agents';
+import { ToolkitCore } from '../shared/toolkit-core.js';
+import { Z as ZuoraToolDefinition, a as ZuoraAgentToolkitConfigInput, T as ToolSelection } from '../async-jobs-Dd8Jafv0.js';
+import { Z as ZuoraOpenAIAgentToolkit } from '../toolkit-CafRZuAV.js';
+import 'openai/resources/chat/completions';
+
+/** Native tool type returned by `tool()` from `@openai/agents`. */
+type AgentsFunctionTool = ReturnType<typeof tool>;
+/**
+ * OpenAI Agents SDK adapter for the Zuora Agent Kit.
+ *
+ * Extends `ToolkitCore` so all shared capabilities (auth, approval policy,
+ * observability, async job handling, native file tools) are inherited.
+ * `convertTools()` is the only override — it wraps each `ZuoraToolDefinition`
+ * in an `@openai/agents` `tool()` object whose `execute()` function:
+ *
+ *   1. Calls `this.callTool()` (MCP execution + approval policy enforcement)
+ *   2. Blocks on `this.waitForJob()` if the tool started an async job
+ *   3. Embeds `recommendedNextTool` hints for the download chain
+ *
+ * Schema strictification for the OpenAI Responses API is applied
+ * automatically inside `convertTools()` — callers do not need to know about it.
+ */
+declare class ZuoraOpenAIAgentsToolkit extends ToolkitCore<AgentsFunctionTool> {
+    /**
+     * Serialises the agent tool response, emits an `agent.tool.response`
+     * observability event (with the response in `metadata` when
+     * `includePayloads` is enabled), and returns the JSON string to execute().
+     *
+     * This surfaces what the LLM actually receives — which may differ from the
+     * raw `callTool` output when execute() adds directives or download hints.
+     */
+    private emitAgentToolResponse;
+    protected convertTools(tools: ZuoraToolDefinition[]): AgentsFunctionTool[];
+}
+/**
+ * Creates and initialises a `ZuoraOpenAIAgentsToolkit`.
+ *
+ * @example
+ * ```ts
+ * import { Agent, run } from "@openai/agents";
+ * import { createZuoraOpenAIAgentsToolkit } from "@zuora/agent-toolkit/openai-agents";
+ *
+ * const toolkit = await createZuoraOpenAIAgentsToolkit({ env: true });
+ * const tools  = await toolkit.getTools({ bundles: ["query"], mode: "readOnly" });
+ * const agent  = new Agent({ name: "Cli Agent", tools });
+ * const result = await run(agent, "How many active accounts?");
+ * ```
+ */
+declare const createZuoraOpenAIAgentsToolkit: (config: ZuoraAgentToolkitConfigInput) => Promise<ZuoraOpenAIAgentsToolkit>;
+
+/**
+ * Bridge: Zuora toolkit → OpenAI Agents SDK tool() objects.
+ *
+ * Each Zuora tool becomes a native `tool()` with:
+ *   - Its full `inputSchema` strictified for the Responses API (invisible to callers)
+ *   - `strict: false` as an API-level safeguard against residual schema 400 errors
+ *   - `needsApproval: true` for write tools (SDK-native HITL)
+ *   - An `execute()` that calls `toolkit.callTool()`, inline `waitForJob()` for
+ *     async results, and embeds `recommendedNextTool` hints for the download chain
+ *
+ * @module openai-agents
+ */
+
+type AgentsTool = any;
+/**
+ * The minimal interface of `tool()` from `@openai/agents` that we need.
+ * Typed as `unknown` so this module compiles without `@openai/agents` installed.
+ */
+type AgentsToolFactory = (options: any) => AgentsTool;
+/**
+ * Converts a single `ZuoraToolDefinition` into an `@openai/agents` `tool()`
+ * object with the `execute()` function fully wired to the Zuora toolkit.
+ *
+ * Schema strictification and async-job handling are applied internally —
+ * callers receive a ready-to-use tool without needing to know about them.
+ *
+ * @param toolFactory - The `tool` function imported from `@openai/agents`
+ * @param def - The Zuora tool definition
+ * @param toolkit - The Zuora toolkit instance (provides callTool / waitForJob)
+ */
+declare const buildAgentsTool: (toolFactory: AgentsToolFactory, sanitizedName: string, def: ZuoraToolDefinition, toolkit: ZuoraOpenAIAgentToolkit) => AgentsTool;
+/**
+ * Converts the Zuora toolkit's tool catalog into `@openai/agents` `tool()`
+ * objects ready to pass to `new Agent({ tools })`.
+ *
+ * @param toolFactory - The `tool` function imported from `@openai/agents`
+ * @param toolkit - An initialised `ZuoraOpenAIAgentToolkit` instance
+ * @param selection - Bundle and mode filter (same as `toolkit.getTools()`)
+ * @param maxTools - Optional cap on returned tool count
+ */
+declare const buildAgentsTools: (toolFactory: AgentsToolFactory, toolkit: ZuoraOpenAIAgentToolkit, selection?: ToolSelection, maxTools?: number) => Promise<AgentsTool[]>;
+
+export { ZuoraOpenAIAgentsToolkit, buildAgentsTool, buildAgentsTools, createZuoraOpenAIAgentsToolkit };