@promptev/client 0.1.0 → 0.2.0

package/dist/cjs/index.cjs

@@ -165,80 +165,61 @@ class PromptevClient {
             reader.releaseLock();
         }
     }
-    // ── Prompt API ──────────────────────────────────────
+    // ── Agent API ───────────────────────────────────────
     /**
-     * Compile and execute a prompt.
+     * Trigger an agent in a single blocking call — the primary way to use the SDK.
+     *
+     * Creates (or resumes) a session AND runs the agent, returning the final
+     * response as JSON. Any tools the agent has attached run server-side.
+     *
+     * @param agentId - Your agent's id (from the Deploy tab).
+     * @param message - The user message to send to the agent.
+     * @param opts.sessionId - Pass the `sessionId` from a previous call to keep
+     *   conversation memory. Omit it for a fresh, stateless run.
+     * @param opts.variables - Object filling the agent's `{{...}}` prompt variables.
+     * @returns `{ response, sessionId }` — pass `sessionId` back on the next call
+     *   to continue the same conversation.
      *
-     * If the prompt has a model configured, it compiles the template,
-     * sends it to the LLM, and returns the AI response. If no model
-     * is configured, it returns the compiled template string.
+     * @example
+     * const { response, sessionId } = await client.triggerAgent(
+     *   "your-agent-id",
+     *   "What is the refund policy?",
+     *   { variables: { company: "Acme Corp" } }
+     * );
+     * // Follow-up keeps memory:
+     * await client.triggerAgent("your-agent-id", "And for digital goods?", { sessionId });
      */
-    async runPrompt(promptKey, query, variables) {
-        const url = `${this.baseUrl}/api/sdk/v1/prompt/client/${this.projectKey}/${promptKey}`;
-        const merged = { query, ...(variables ?? {}) };
+    async triggerAgent(agentId, message, opts) {
+        const url = `${this.baseUrl}/api/sdk/v1/agent/${this.projectKey}/${agentId}/trigger`;
+        const payload = { message };
+        if (opts?.sessionId != null)
+            payload.session_id = opts.sessionId;
+        if (opts?.variables != null)
+            payload.variables = opts.variables;
+        // Optional caller/end-user id stored on the chat session; defaults server-side
+        // to a generated webhook_<id> when omitted.
+        if (opts?.visitor != null)
+            payload.visitor = opts.visitor;
         const resp = await this.fetchWithRetry(url, {
             method: "POST",
             headers: this.headers,
-            body: JSON.stringify({ variables: merged }),
+            body: JSON.stringify(payload),
         });
         const text = await resp.text();
         PromptevClient.raiseForStatus(resp.status, text);
         const data = JSON.parse(text);
-        if (typeof data.prompt !== "string") {
-            throw new PromptevError("Unexpected response: missing 'prompt' field");
-        }
-        return data.prompt;
+        return {
+            response: typeof data.response === "string" ? data.response : "",
+            sessionId: data.session_id,
+        };
     }
     /**
-     * Compile and execute a prompt with streaming.
+     * Start a new agent chat session (streaming flow).
      *
-     * Use this when the prompt has tools attached or you want real-time
-     * output. Returns the same event types as agent streaming.
-     */
-    async *streamPrompt(promptKey, query, variables) {
-        const url = `${this.baseUrl}/api/sdk/v1/prompt/client/${this.projectKey}/${promptKey}?stream=true`;
-        const merged = { query, ...(variables ?? {}) };
-        const controller = new AbortController();
-        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
-        let resp;
-        try {
-            resp = await fetch(url, {
-                method: "POST",
-                headers: this.headers,
-                body: JSON.stringify({ variables: merged }),
-                signal: controller.signal,
-            });
-        }
-        catch (err) {
-            clearTimeout(timeoutId);
-            if (err.name === "AbortError")
-                throw new NetworkError("Request timed out");
-            throw new NetworkError(`Network error: ${err.message}`);
-        }
-        clearTimeout(timeoutId);
-        if (resp.status >= 400) {
-            const text = await resp.text();
-            PromptevClient.raiseForStatus(resp.status, text);
-        }
-        const contentType = resp.headers.get("content-type") || "";
-        // Non-streaming fallback: prompt has no model, backend returns JSON
-        if (!contentType.includes("text/event-stream")) {
-            const data = await resp.json();
-            yield {
-                type: "done",
-                output: data.prompt || "",
-                raw: data,
-            };
-            return;
-        }
-        yield* this.parseSSE(resp);
-    }
-    // ── Agent API ───────────────────────────────────────
-    /**
-     * Start a new agent chat session.
+     * @param agentId - Your agent's id (from the Deploy tab).
      */
-    async startAgent(chatbotId, options) {
-        const url = `${this.baseUrl}/api/sdk/v1/agent/${this.projectKey}/${chatbotId}/start`;
+    async startAgent(agentId, options) {
+        const url = `${this.baseUrl}/api/sdk/v1/agent/${this.projectKey}/${agentId}/start`;
         const payload = {};
         if (options?.visitor != null)
             payload.visitor = options.visitor;
@@ -254,7 +235,7 @@ class PromptevClient {
         const data = JSON.parse(text);
         return {
             sessionToken: data.session_token,
-            chatbotId: data.chatbot_id,
+            agentId: data.chatbot_id,
             name: data.name,
             memoryEnabled: data.memory_enabled ?? false,
             messages: data.messages ?? [],
@@ -262,9 +243,11 @@ class PromptevClient {
     }
     /**
      * Stream an agent response as SSE events.
+     *
+     * @param agentId - Your agent's id (from the Deploy tab).
      */
-    async *streamAgent(chatbotId, options) {
-        const url = `${this.baseUrl}/api/sdk/v1/agent/${this.projectKey}/${chatbotId}/stream?session_token=${encodeURIComponent(options.sessionToken)}`;
+    async *streamAgent(agentId, options) {
+        const url = `${this.baseUrl}/api/sdk/v1/agent/${this.projectKey}/${agentId}/stream?session_token=${encodeURIComponent(options.sessionToken)}`;
         const controller = new AbortController();
         const timeoutId = setTimeout(() => controller.abort(), this.timeout);
         let resp;

package/dist/esm/index.d.ts

@@ -7,11 +7,15 @@ export interface PromptevClientConfig {
 }
 export interface AgentSession {
     sessionToken: string;
-    chatbotId: string;
+    agentId: string;
     name: string;
     memoryEnabled: boolean;
     messages: Record<string, any>[];
 }
+export interface TriggerResult {
+    response: string;
+    sessionId: string;
+}
 export interface AgentEvent {
     type: string;
     output: string;
@@ -51,31 +55,48 @@ export declare class PromptevClient {
     private fetchWithRetry;
     private parseSSE;
     /**
-     * Compile and execute a prompt.
+     * Trigger an agent in a single blocking call — the primary way to use the SDK.
      *
-     * If the prompt has a model configured, it compiles the template,
-     * sends it to the LLM, and returns the AI response. If no model
-     * is configured, it returns the compiled template string.
-     */
-    runPrompt(promptKey: string, query: string, variables?: Record<string, string>): Promise<string>;
-    /**
-     * Compile and execute a prompt with streaming.
+     * Creates (or resumes) a session AND runs the agent, returning the final
+     * response as JSON. Any tools the agent has attached run server-side.
+     *
+     * @param agentId - Your agent's id (from the Deploy tab).
+     * @param message - The user message to send to the agent.
+     * @param opts.sessionId - Pass the `sessionId` from a previous call to keep
+     *   conversation memory. Omit it for a fresh, stateless run.
+     * @param opts.variables - Object filling the agent's `{{...}}` prompt variables.
+     * @returns `{ response, sessionId }` — pass `sessionId` back on the next call
+     *   to continue the same conversation.
      *
-     * Use this when the prompt has tools attached or you want real-time
-     * output. Returns the same event types as agent streaming.
+     * @example
+     * const { response, sessionId } = await client.triggerAgent(
+     *   "your-agent-id",
+     *   "What is the refund policy?",
+     *   { variables: { company: "Acme Corp" } }
+     * );
+     * // Follow-up keeps memory:
+     * await client.triggerAgent("your-agent-id", "And for digital goods?", { sessionId });
      */
-    streamPrompt(promptKey: string, query: string, variables?: Record<string, string>): AsyncGenerator<AgentEvent>;
+    triggerAgent(agentId: string, message: string, opts?: {
+        sessionId?: string;
+        variables?: Record<string, any>;
+        visitor?: string;
+    }): Promise<TriggerResult>;
     /**
-     * Start a new agent chat session.
+     * Start a new agent chat session (streaming flow).
+     *
+     * @param agentId - Your agent's id (from the Deploy tab).
      */
-    startAgent(chatbotId: string, options?: {
+    startAgent(agentId: string, options?: {
         visitor?: string;
         platform?: string;
     }): Promise<AgentSession>;
     /**
      * Stream an agent response as SSE events.
+     *
+     * @param agentId - Your agent's id (from the Deploy tab).
      */
-    streamAgent(chatbotId: string, options: {
+    streamAgent(agentId: string, options: {
         sessionToken: string;
         query: string;
     }): AsyncGenerator<AgentEvent>;

package/dist/esm/index.js

@@ -155,80 +155,61 @@ export class PromptevClient {
             reader.releaseLock();
         }
     }
-    // ── Prompt API ──────────────────────────────────────
+    // ── Agent API ───────────────────────────────────────
     /**
-     * Compile and execute a prompt.
+     * Trigger an agent in a single blocking call — the primary way to use the SDK.
+     *
+     * Creates (or resumes) a session AND runs the agent, returning the final
+     * response as JSON. Any tools the agent has attached run server-side.
+     *
+     * @param agentId - Your agent's id (from the Deploy tab).
+     * @param message - The user message to send to the agent.
+     * @param opts.sessionId - Pass the `sessionId` from a previous call to keep
+     *   conversation memory. Omit it for a fresh, stateless run.
+     * @param opts.variables - Object filling the agent's `{{...}}` prompt variables.
+     * @returns `{ response, sessionId }` — pass `sessionId` back on the next call
+     *   to continue the same conversation.
      *
-     * If the prompt has a model configured, it compiles the template,
-     * sends it to the LLM, and returns the AI response. If no model
-     * is configured, it returns the compiled template string.
+     * @example
+     * const { response, sessionId } = await client.triggerAgent(
+     *   "your-agent-id",
+     *   "What is the refund policy?",
+     *   { variables: { company: "Acme Corp" } }
+     * );
+     * // Follow-up keeps memory:
+     * await client.triggerAgent("your-agent-id", "And for digital goods?", { sessionId });
      */
-    async runPrompt(promptKey, query, variables) {
-        const url = `${this.baseUrl}/api/sdk/v1/prompt/client/${this.projectKey}/${promptKey}`;
-        const merged = { query, ...(variables ?? {}) };
+    async triggerAgent(agentId, message, opts) {
+        const url = `${this.baseUrl}/api/sdk/v1/agent/${this.projectKey}/${agentId}/trigger`;
+        const payload = { message };
+        if (opts?.sessionId != null)
+            payload.session_id = opts.sessionId;
+        if (opts?.variables != null)
+            payload.variables = opts.variables;
+        // Optional caller/end-user id stored on the chat session; defaults server-side
+        // to a generated webhook_<id> when omitted.
+        if (opts?.visitor != null)
+            payload.visitor = opts.visitor;
         const resp = await this.fetchWithRetry(url, {
             method: "POST",
             headers: this.headers,
-            body: JSON.stringify({ variables: merged }),
+            body: JSON.stringify(payload),
         });
         const text = await resp.text();
         PromptevClient.raiseForStatus(resp.status, text);
         const data = JSON.parse(text);
-        if (typeof data.prompt !== "string") {
-            throw new PromptevError("Unexpected response: missing 'prompt' field");
-        }
-        return data.prompt;
+        return {
+            response: typeof data.response === "string" ? data.response : "",
+            sessionId: data.session_id,
+        };
     }
     /**
-     * Compile and execute a prompt with streaming.
+     * Start a new agent chat session (streaming flow).
      *
-     * Use this when the prompt has tools attached or you want real-time
-     * output. Returns the same event types as agent streaming.
-     */
-    async *streamPrompt(promptKey, query, variables) {
-        const url = `${this.baseUrl}/api/sdk/v1/prompt/client/${this.projectKey}/${promptKey}?stream=true`;
-        const merged = { query, ...(variables ?? {}) };
-        const controller = new AbortController();
-        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
-        let resp;
-        try {
-            resp = await fetch(url, {
-                method: "POST",
-                headers: this.headers,
-                body: JSON.stringify({ variables: merged }),
-                signal: controller.signal,
-            });
-        }
-        catch (err) {
-            clearTimeout(timeoutId);
-            if (err.name === "AbortError")
-                throw new NetworkError("Request timed out");
-            throw new NetworkError(`Network error: ${err.message}`);
-        }
-        clearTimeout(timeoutId);
-        if (resp.status >= 400) {
-            const text = await resp.text();
-            PromptevClient.raiseForStatus(resp.status, text);
-        }
-        const contentType = resp.headers.get("content-type") || "";
-        // Non-streaming fallback: prompt has no model, backend returns JSON
-        if (!contentType.includes("text/event-stream")) {
-            const data = await resp.json();
-            yield {
-                type: "done",
-                output: data.prompt || "",
-                raw: data,
-            };
-            return;
-        }
-        yield* this.parseSSE(resp);
-    }
-    // ── Agent API ───────────────────────────────────────
-    /**
-     * Start a new agent chat session.
+     * @param agentId - Your agent's id (from the Deploy tab).
      */
-    async startAgent(chatbotId, options) {
-        const url = `${this.baseUrl}/api/sdk/v1/agent/${this.projectKey}/${chatbotId}/start`;
+    async startAgent(agentId, options) {
+        const url = `${this.baseUrl}/api/sdk/v1/agent/${this.projectKey}/${agentId}/start`;
         const payload = {};
         if (options?.visitor != null)
             payload.visitor = options.visitor;
@@ -244,7 +225,7 @@ export class PromptevClient {
         const data = JSON.parse(text);
         return {
             sessionToken: data.session_token,
-            chatbotId: data.chatbot_id,
+            agentId: data.chatbot_id,
             name: data.name,
             memoryEnabled: data.memory_enabled ?? false,
             messages: data.messages ?? [],
@@ -252,9 +233,11 @@ export class PromptevClient {
     }
     /**
      * Stream an agent response as SSE events.
+     *
+     * @param agentId - Your agent's id (from the Deploy tab).
      */
-    async *streamAgent(chatbotId, options) {
-        const url = `${this.baseUrl}/api/sdk/v1/agent/${this.projectKey}/${chatbotId}/stream?session_token=${encodeURIComponent(options.sessionToken)}`;
+    async *streamAgent(agentId, options) {
+        const url = `${this.baseUrl}/api/sdk/v1/agent/${this.projectKey}/${agentId}/stream?session_token=${encodeURIComponent(options.sessionToken)}`;
         const controller = new AbortController();
         const timeoutId = setTimeout(() => controller.abort(), this.timeout);
         let resp;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@promptev/client",
-  "version": "0.1.0",
-  "description": "JavaScript/TypeScript SDK for Promptev — run AI prompts and agents programmatically",
+  "version": "0.2.0",
+  "description": "JavaScript/TypeScript SDK for Promptev — trigger and stream your AI agents programmatically",
   "type": "module",
   "main": "./dist/cjs/index.cjs",
   "module": "./dist/esm/index.js",
@@ -13,7 +13,7 @@
       "types": "./dist/esm/index.d.ts"
     }
   },
-  "license": "MIT",
+  "license": "SEE LICENSE IN LICENSE.txt",
   "author": "Promptev Inc. <support@promptev.ai>",
   "private": false,
   "publishConfig": {
@@ -27,13 +27,12 @@
   ],
   "keywords": [
     "promptev",
-    "prompts",
+    "agents",
+    "agent-sdk",
+    "ai",
     "api",
     "client",
     "sdk",
-    "ai",
-    "agents",
-    "agent-sdk",
     "context-engineering",
     "typescript",
     "javascript"

package/readme.md

@@ -1,6 +1,8 @@
 # Promptev JavaScript SDK
 
-The official JavaScript/TypeScript SDK for [Promptev.ai](https://promptev.ai) — run AI prompts and agents programmatically using your project API key.
+The official JavaScript/TypeScript SDK for [Promptev.ai](https://promptev.ai) — trigger and stream your AI **agents** programmatically using your project API key.
+
+> In Promptev, an **agent** is your deployed AI assistant: instructions + model + tools (Jira, Slack, GitHub, …) + context packs, all configured in the dashboard. This SDK runs those agents. Tools execute server-side, memory is built in.
 
 ## Installation
 
@@ -41,123 +43,114 @@ const { PromptevClient } = require("@promptev/client");
 
 ## Quick Start
 
+The fastest way to use an agent is `triggerAgent` — one blocking call that runs the agent and returns its final answer. Pass your agent's id (from the **Deploy** tab) and a message:
+
 ```ts
 import { PromptevClient } from "@promptev/client";
 
 const client = new PromptevClient({ projectKey: "pv_sk_your_key_here" });
 
-// Run a prompt
-const result = await client.runPrompt("support-agent",
+const { response, sessionId } = await client.triggerAgent(
+  "your-agent-id",
   "What is the refund policy?",
-  { company: "Acme Corp" }
+  { variables: { company: "Acme Corp" } }
 );
-console.log(result);
+console.log(response);
 
-// Chat with an AI agent
-const session = await client.startAgent("your-agent-id");
-
-for await (const event of client.streamAgent(session.chatbotId, {
-  sessionToken: session.sessionToken,
-  query: "Summarize our Q4 sales report",
-})) {
-  if (event.type === "done") console.log(event.output);
-}
+// Keep conversation memory by passing the same sessionId back:
+const followUp = await client.triggerAgent(
+  "your-agent-id",
+  "And for digital goods?",
+  { sessionId }
+);
+console.log(followUp.response);
 ```
 
-## Prompts
+That's it. The agent's tools, context packs, and model all run server-side — you just get the answer.
 
-Promptev prompts are versioned, server-managed templates. `runPrompt` compiles the template with your variables — and if the prompt has a model configured in Promptev, it also executes it against the LLM and returns the AI response directly.
+## `triggerAgent` — run an agent in one call
 
-### Run a prompt with variables
+`triggerAgent(agentId, message, opts?)` creates **or** resumes a session **and** runs the agent, returning the final response as JSON.
 
 ```ts
-const result = await client.runPrompt("support-agent",
-  "How do I reset my password?",
-  { company: "Acme Corp", tone: "professional" }
-);
+const result = await client.triggerAgent("your-agent-id", "Summarize our Q4 sales report");
+console.log(result.response);   // the agent's answer
+console.log(result.sessionId);  // pass this back to continue the conversation
 ```
 
-### Run a prompt without variables
+| Parameter | Type | Description |
+|---|---|---|
+| `agentId` | `string` | Your agent's id (from the Deploy tab) |
+| `message` | `string` | The user message to send to the agent |
+| `opts.sessionId` | `string?` | Pass the `sessionId` from a previous call to keep memory. Omit for a fresh, stateless run. |
+| `opts.variables` | `object?` | Fills the agent's `{{...}}` prompt variables |
+| `opts.visitor` | `string?` | Attribute the run to an end-user id (stored on the chat session for analytics/audit). Defaults to a generated `webhook_<id>`. Set it on the first call of a conversation; a resumed session keeps its original visitor. |
+
+Returns `{ response: string; sessionId: string }`.
 
 ```ts
-const result = await client.runPrompt("knowledge-base",
-  "What is the refund policy?"
+// Attribute the run to a specific end-user:
+const { response } = await client.triggerAgent(
+  "your-agent-id",
+  "How do I reset my password?",
+  { visitor: "user_12345" }
 );
 ```
 
-### With a model configured (auto-execute)
+### Stateful (with memory)
 
-If your prompt has a model and/or context packs attached in Promptev, `runPrompt` compiles the template, retrieves relevant context via RAG, sends it to the LLM, and returns the AI response:
+Pass the returned `sessionId` back on each follow-up to keep context:
 
 ```ts
-const answer = await client.runPrompt("support-agent",
-  "What is the refund policy?",
-  { company: "Acme Corp" }
-);
-console.log(answer); // "Our refund policy allows returns within 30 days..."
+let { response, sessionId } = await client.triggerAgent("your-agent-id", "Summarize Q4 sales");
+console.log(response);
+
+({ response } = await client.triggerAgent("your-agent-id", "Compare that with Q3", { sessionId }));
+console.log(response);
 ```
 
-### Without a model (use with your own LLM)
+### Stateless (no memory)
 
-If no model is configured, `runPrompt` returns the compiled template — use it with any LLM:
+Omit `sessionId` for an independent, one-shot run each time:
 
 ```ts
-import OpenAI from "openai";
-
-const client = new PromptevClient({ projectKey: "pv_sk_..." });
-const openai = new OpenAI({ apiKey: "sk-..." });
-
-const systemPrompt = await client.runPrompt("support-agent",
-  "How do I reset my password?",
-  { company: "Acme Corp", tone: "professional" }
+const { response } = await client.triggerAgent(
+  "your-agent-id",
+  "What is the refund policy?",
+  { variables: { company: "Acme Corp" } }
 );
-
-const response = await openai.chat.completions.create({
-  model: "gpt-4",
-  messages: [
-    { role: "system", content: systemPrompt },
-    { role: "user", content: "How do I reset my password?" },
-  ],
-});
-console.log(response.choices[0].message.content);
 ```
 
-### Stream a prompt (with tools or real-time output)
+### With prompt variables
 
-When a prompt has tools attached (Jira, Slack, GitHub, etc.) or you want real-time output, use `streamPrompt`. It returns SSE events — same format as agent streaming:
+If your agent's instructions contain `{{...}}` placeholders, fill them via `variables`:
 
 ```ts
-for await (const event of client.streamPrompt("research-assistant",
-  "Find all P1 bugs assigned to me",
-  { project: "ACME" }
-)) {
-  if (event.type === "thoughts") console.log(`Thinking: ${event.output}`);
-  else if (event.type === "processing") console.log(`Running: ${event.output}`);
-  else if (event.type === "done") console.log(event.output);
-}
+const { response } = await client.triggerAgent(
+  "your-agent-id",
+  "How do I reset my password?",
+  { variables: { company: "Acme Corp", tone: "professional" } }
+);
 ```
 
-> **When to use which:**
-> - `runPrompt()` — simple prompt execution, no tools, returns a string
-> - `streamPrompt()` — prompts with tools, RAG-heavy queries, or when you want real-time output
-
-## Agents
+## Streaming an agent
 
-Promptev agents are deployed AI assistants with built-in memory, tools (Jira, Slack, GitHub, etc.), and RAG context packs. The SDK lets you start sessions and stream responses in real time.
+When you want real-time output — agent reasoning, tool-execution status, and the final answer as they happen — use the streaming flow: `startAgent` to open a session, then `streamAgent` to receive [Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events).
 
 ### Start a session
 
 ```ts
 const session = await client.startAgent("your-agent-id", { visitor: "John" });
 
-console.log(session.sessionToken);  // Use this for all subsequent messages
-console.log(session.name);          // Agent display name
-console.log(session.memoryEnabled); // Whether agent retains conversation context
+console.log(session.sessionToken);  // use this for all subsequent stream calls
+console.log(session.agentId);       // the agent id, echoed back
+console.log(session.name);          // agent display name
+console.log(session.memoryEnabled); // whether the agent retains conversation context
 ```
 
 ### Stream a response
 
-The agent responds via Server-Sent Events (SSE). Each event has a `type` and `output`:
+Each event has a `type` and `output`:
 
 | Event Type | Description |
 |---|---|
@@ -168,7 +161,7 @@ The agent responds via Server-Sent Events (SSE). Each event has a `type` and `ou
 | `error` | Something went wrong |
 
 ```ts
-for await (const event of client.streamAgent(session.chatbotId, {
+for await (const event of client.streamAgent(session.agentId, {
   sessionToken: session.sessionToken,
   query: "What are the open P1 bugs in our backlog?",
 })) {
@@ -187,7 +180,7 @@ The session token maintains conversation context across messages:
 const session = await client.startAgent("your-agent-id", { visitor: "Sarah" });
 
 // First message
-for await (const event of client.streamAgent(session.chatbotId, {
+for await (const event of client.streamAgent(session.agentId, {
   sessionToken: session.sessionToken,
   query: "Summarize our Q4 sales report",
 })) {
@@ -195,7 +188,7 @@ for await (const event of client.streamAgent(session.chatbotId, {
 }
 
 // Follow-up — agent remembers the previous context
-for await (const event of client.streamAgent(session.chatbotId, {
+for await (const event of client.streamAgent(session.agentId, {
   sessionToken: session.sessionToken,
   query: "Compare that with Q3",
 })) {
@@ -207,7 +200,7 @@ for await (const event of client.streamAgent(session.chatbotId, {
 
 ```ts
 async function askAgent(client, session, query) {
-  for await (const event of client.streamAgent(session.chatbotId, {
+  for await (const event of client.streamAgent(session.agentId, {
     sessionToken: session.sessionToken,
     query,
   })) {
@@ -219,6 +212,10 @@ async function askAgent(client, session, query) {
 const answer = await askAgent(client, session, "What's our monthly churn rate?");
 ```
 
+> **When to use which:**
+> - `triggerAgent()` — the default. One call, blocking, returns the final answer. Best for APIs, jobs, and server-to-server use.
+> - `startAgent()` + `streamAgent()` — when you want to render reasoning and tool progress live (e.g., a chat UI).
+
 ## Error Handling
 
 The SDK raises typed errors for each failure scenario:
@@ -237,13 +234,14 @@ import {
 const client = new PromptevClient({ projectKey: "pv_sk_..." });
 
 try {
-  const result = await client.runPrompt("my-prompt", "Hello", { name: "Ava" });
+  const { response } = await client.triggerAgent("your-agent-id", "Hello");
+  console.log(response);
 } catch (err) {
   if (err instanceof ValidationError) {
     // 400 — missing variables, bad input
     console.log(`Invalid request: ${err.message}`);
   } else if (err instanceof NotFoundError) {
-    // 404 — prompt or project not found
+    // 404 — agent or project not found
     console.log(`Not found: ${err.message}`);
   } else if (err instanceof AuthenticationError) {
     // 401/403 — invalid API key or agent not active
@@ -265,6 +263,16 @@ All errors extend `PromptevError` and include:
 - `err.statusCode` — HTTP status code (if applicable)
 - `err.responseText` — Raw response body (for debugging)
 
+| Error | HTTP Status | When |
+|---|---|---|
+| `ValidationError` | 400 | Missing required variables, bad input |
+| `AuthenticationError` | 401, 403 | Invalid API key, agent not active |
+| `NotFoundError` | 404 | Project or agent not found |
+| `RateLimitError` | 429 | API usage quota exceeded |
+| `ServerError` | 5xx | Server error (after retries exhausted) |
+| `NetworkError` | — | Connection failed, timeout, DNS error |
+| `PromptevError` | any | Base class for all above errors |
+
 ## Configuration
 
 ```ts
@@ -279,7 +287,7 @@ const client = new PromptevClient({
 
 | Parameter | Default | Description |
 |---|---|---|
-| `projectKey` | *required* | Your Promptev project API key |
+| `projectKey` | *required* | Your Promptev project API key (`pv_sk_...`) |
 | `baseUrl` | `https://api.promptev.ai` | API base URL |
 | `timeout` | `30000` | Request timeout in milliseconds |
 | `maxRetries` | `2` | Automatic retries for transient server errors (502, 503, 504) |
@@ -291,19 +299,25 @@ const client = new PromptevClient({
 
 | Method | Description | Returns |
 |---|---|---|
-| `runPrompt(promptKey, query, variables?)` | Compile and execute a prompt | `Promise<string>` |
-| `streamPrompt(promptKey, query, variables?)` | Stream prompt execution with tools | `AsyncGenerator<AgentEvent>` |
-| `startAgent(chatbotId, options?)` | Start agent session | `Promise<AgentSession>` |
-| `streamAgent(chatbotId, options)` | Stream agent response | `AsyncGenerator<AgentEvent>` |
+| `triggerAgent(agentId, message, opts?)` | Run an agent in one blocking call | `Promise<TriggerResult>` |
+| `startAgent(agentId, options?)` | Start a streaming agent session | `Promise<AgentSession>` |
+| `streamAgent(agentId, options)` | Stream an agent response (SSE) | `AsyncGenerator<AgentEvent>` |
+
+### `TriggerResult`
+
+| Field | Type | Description |
+|---|---|---|
+| `response` | `string` | The agent's final answer |
+| `sessionId` | `string` | Pass back as `opts.sessionId` to continue the conversation |
 
 ### `AgentSession`
 
 | Field | Type | Description |
 |---|---|---|
 | `sessionToken` | `string` | Token for subsequent stream calls |
-| `chatbotId` | `string` | Agent identifier |
+| `agentId` | `string` | Agent identifier |
 | `name` | `string` | Agent display name |
-| `memoryEnabled` | `boolean` | Whether agent retains conversation context |
+| `memoryEnabled` | `boolean` | Whether the agent retains conversation context |
 | `messages` | `array` | Previous messages (populated when resuming a session) |
 
 ### `AgentEvent`
@@ -314,18 +328,6 @@ const client = new PromptevClient({
 | `output` | `string` | Event content text |
 | `raw` | `object` | Full parsed SSE event data |
 
-### Exceptions
-
-| Error | HTTP Status | When |
-|---|---|---|
-| `ValidationError` | 400 | Missing required variables, bad input |
-| `AuthenticationError` | 401, 403 | Invalid API key, agent not active |
-| `NotFoundError` | 404 | Project, prompt, or agent not found |
-| `RateLimitError` | 429 | API usage quota exceeded |
-| `ServerError` | 5xx | Server error (after retries exhausted) |
-| `NetworkError` | — | Connection failed, timeout, DNS error |
-| `PromptevError` | any | Base class for all above errors |
-
 ## Framework Examples
 
 ### React
@@ -336,15 +338,15 @@ import { PromptevClient } from "@promptev/client";
 
 const client = new PromptevClient({ projectKey: "pv_sk_..." });
 
-export function AskAI() {
+export function AskAgent() {
   const [answer, setAnswer] = useState("");
   const [loading, setLoading] = useState(false);
 
   async function handleAsk() {
     setLoading(true);
     try {
-      const result = await client.runPrompt("support-agent", "What is your refund policy?");
-      setAnswer(result);
+      const { response } = await client.triggerAgent("your-agent-id", "What is your refund policy?");
+      setAnswer(response);
     } finally {
       setLoading(false);
     }
@@ -352,7 +354,7 @@ export function AskAI() {
 
   return (
     <div>
-      <button onClick={handleAsk} disabled={loading}>Ask AI</button>
+      <button onClick={handleAsk} disabled={loading}>Ask Agent</button>
       {answer && <p>{answer}</p>}
     </div>
   );
@@ -383,7 +385,7 @@ export function AgentChat() {
     const query = input;
     setInput("");
 
-    for await (const event of client.streamAgent(sessionRef.current.chatbotId, {
+    for await (const event of client.streamAgent(sessionRef.current.agentId, {
       sessionToken: sessionRef.current.sessionToken,
       query,
     })) {
@@ -413,8 +415,12 @@ const app = express();
 const client = new PromptevClient({ projectKey: "pv_sk_..." });
 
 app.post("/api/ask", express.json(), async (req, res) => {
-  const answer = await client.runPrompt("support-agent", req.body.question);
-  res.json({ answer });
+  const { response, sessionId } = await client.triggerAgent(
+    "your-agent-id",
+    req.body.question,
+    { sessionId: req.body.sessionId }   // pass back to keep memory across turns
+  );
+  res.json({ answer: response, sessionId });
 });
 
 app.listen(3000);
@@ -429,12 +435,19 @@ app.listen(3000);
   const client = new PromptevClient({ projectKey: "pv_sk_..." });
 
   document.getElementById("ask-btn").addEventListener("click", async () => {
-    const answer = await client.runPrompt("support-agent", "What is the refund policy?");
-    document.getElementById("output").textContent = answer;
+    const { response } = await client.triggerAgent("your-agent-id", "What is the refund policy?");
+    document.getElementById("output").textContent = response;
   });
 </script>
 ```
 
+## Building from source
+
+```bash
+npm install
+npm run build   # builds both ESM (dist/esm) and CommonJS (dist/cjs)
+```
+
 ## License
 
 This SDK is commercial software by [Promptev Inc](https://promptev.ai).