@promptev/client 1.0.0 → 1.1.0

package/dist/cjs/index.cjs

@@ -350,6 +350,10 @@ class PromptevClient {
                 obo.groups = options.onBehalfOf.groups;
             payload.on_behalf_of = obo;
         }
+        if (options?.model != null)
+            payload.model = options.model;
+        if (options?.toolInputs != null)
+            payload.tool_inputs = options.toolInputs;
         const url = `${this.baseUrl}/api/v1/agents/${encodeURIComponent(slug)}/chat`;
         // Deliberately NOT fetchWithRetry: a turn is not idempotent — a retried
         // POST could run the agent, and its tools, a second time.

package/dist/esm/index.d.ts

@@ -72,6 +72,34 @@ export interface OnBehalfOf {
     /** The end user's groups, as your system knows them. Omit for the key's full grant. */
     groups?: string[];
 }
+/** A model of a provider the workspace has connected, by the ids its model list shows. */
+export interface ModelChoice {
+    provider: string;
+    model: string;
+}
+/**
+ * What one call overrides on one of the agent's tools, by where each value
+ * goes. Only what the tool already has in that place can be overridden; any
+ * other name answers 400, and nothing is stored: the next call runs the agent
+ * as it was published.
+ *
+ * - An HTTP tool has `headers`, `query`, `body` and `path` (a `{{name}}` in
+ *   its URL). A GET or DELETE has no body: all its parameters are `query`.
+ * - An MCP server has `headers` (sent to the server) and `arguments` (of its
+ *   functions; a value reaches every function that takes that argument).
+ *
+ * A value the model would have filled is fixed for the call: the model neither
+ * sees nor changes it, and it shows wherever tool arguments show (the
+ * `tool_call` event, approvals). A header, or a value the tool was saved with,
+ * never appears in the stream. Put secrets in `headers`.
+ */
+export interface ToolInput {
+    headers?: Record<string, string>;
+    query?: Record<string, unknown>;
+    body?: Record<string, unknown>;
+    path?: Record<string, unknown>;
+    arguments?: Record<string, unknown>;
+}
 export interface ChatOptions {
     /**
      * Continue an existing thread. Read it off the first `conversation` event
@@ -89,6 +117,16 @@ export interface ChatOptions {
     conversationId?: string;
     /** Act for one of your end users — see {@link OnBehalfOf}. */
     onBehalfOf?: OnBehalfOf;
+    /**
+     * Run this one call on another model. The workspace's own provider key is
+     * used; a model it cannot call answers 400 before the turn starts.
+     */
+    model?: ModelChoice;
+    /**
+     * Override what the agent's tools are configured with, for this one call,
+     * keyed by tool id (shown on the tool's page) — see {@link ToolInput}.
+     */
+    toolInputs?: Record<string, ToolInput>;
     /** Abort the turn from your own signal (in addition to the client timeout). */
     signal?: AbortSignal;
 }

package/dist/esm/index.js

@@ -339,6 +339,10 @@ export class PromptevClient {
                 obo.groups = options.onBehalfOf.groups;
             payload.on_behalf_of = obo;
         }
+        if (options?.model != null)
+            payload.model = options.model;
+        if (options?.toolInputs != null)
+            payload.tool_inputs = options.toolInputs;
         const url = `${this.baseUrl}/api/v1/agents/${encodeURIComponent(slug)}/chat`;
         // Deliberately NOT fetchWithRetry: a turn is not idempotent — a retried
         // POST could run the agent, and its tools, a second time.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promptev/client",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "JavaScript/TypeScript client for Promptev — stream your AI agents and upload documents with a workspace API key",
   "type": "module",
   "main": "./dist/cjs/index.cjs",

package/readme.md

@@ -76,6 +76,8 @@ client.chat(agentSlug, message, options?): AsyncGenerator<AgentEvent>
 | `message` | `string` | What to say. Required, non-empty after trimming, at most 20,000 characters. |
 | `options.conversationId` | `string?` | Continue a thread. Take it from the first `conversation` event. |
 | `options.onBehalfOf` | `object?` | Act for one of your end users — see [On behalf of your users](#on-behalf-of-your-users). |
+| `options.model` | `{ provider, model }?` | Run this one call on another model. See [Changing the model or a tool's values for one call](#changing-the-model-or-a-tools-values-for-one-call). |
+| `options.toolInputs` | `Record<toolId, ToolInput>?` | Override what the agent's tools are set up with, for this one call. Same section. |
 | `options.signal` | `AbortSignal?` | Cancel the turn. |
 
 Returns an async generator of [events](#events). It ends after `done`, or after `error`.
@@ -103,6 +105,60 @@ Passing `conversationId` is worth doing for a second reason: a tool set to **Ask
 
 A thread belongs to the agent, to this API, **and** to the `onBehalfOf.subject` it was opened under. Keep the subject the same across a conversation's turns, and never reuse an id from the app, the portal or an embed — any mismatch answers `404`, not a fresh thread.
 
+## Changing the model or a tool's values for one call
+
+Both options are optional. Leave them out and the agent runs exactly as it was published. Nothing a call sends is stored: the next call runs the published agent again.
+
+### `model`
+
+```ts
+for await (const ev of client.chat("support-agent", question, {
+  model: { provider: "openai", model: "gpt-5-mini" },
+})) { /* … */ }
+```
+
+`provider` and `model` are the ids shown in your workspace's model list. The workspace's own provider key is used; a call never carries a key. The model runs on its default settings, because the agent's saved settings (temperature and the like) were tuned for its own model.
+
+The call answers `400` (a `ValidationError`, with `field` set) before the model is called when the workspace has no such provider, the provider has no key, the model is not in its list or has been retired, or the model cannot call tools and the agent has tools.
+
+### `toolInputs`
+
+Override what a tool is set up with, keyed by the tool's **id** (shown on the tool's page in promptev, with a copy button). Each value goes under the place it belongs to:
+
+```ts
+for await (const ev of client.chat("support-agent", "How many open orders does ACME have?", {
+  toolInputs: {
+    "0b6f2c1e-…": {                              // an HTTP tool
+      headers: { Authorization: `Bearer ${endUserToken}` },
+      query:   { region: "us" },
+      body:    { account_id: "acme" },
+      path:    { customer: "acme" },              // a {{customer}} in the tool's URL
+    },
+    "7d41a9c3-…": {                              // an MCP server
+      headers:   { Authorization: `Bearer ${endUserToken}` },
+      arguments: { project_id: "p_123" },
+    },
+  },
+})) { /* … */ }
+```
+
+| Tool | Place | What it is |
+|---|---|---|
+| HTTP | `headers` | A header the tool was saved with. Names match in any letter case. |
+| HTTP | `query` | A query parameter: one the tool was saved with, or one the model fills. A `GET` or `DELETE` tool has no body, so all of its parameters are `query`. |
+| HTTP | `body` | A body value (`POST`, `PUT`, `PATCH`): a key of the saved body, or a parameter the model fills. |
+| HTTP | `path` | A `{{name}}` in the tool's URL. |
+| MCP server | `headers` | A header the server was saved with (`Authorization` when it was saved with a token). |
+| MCP server | `arguments` | An argument of the server's functions. The value reaches every function that takes an argument of that name. |
+
+The rules:
+
+- **Override only.** A name the tool does not have in that place answers `400`, and the message lists what the tool does have there. Nothing extra is ever passed through.
+- **A value the model would have filled is fixed for the call.** The model neither sees that parameter nor can change it, so the answer's wording follows the question while the tool gets your value.
+- **What is visible.** A value the model would have filled shows wherever tool arguments show: the `tool_call` event and approval requests. A header, and any value the tool was saved with, never appears in the stream. **Put secrets in `headers`.**
+- **Limits.** 20 tools per call, 20 names per place, 16 KB per tool.
+- Overriding a value the tool was **saved with** (a header, a fixed query parameter, a key of the saved body) needs a server that supports it. One that does not answers `400` saying so; it never runs the call without your value.
+
 ## Events
 
 Every frame the server can send, typed. Narrow on `event.type`.