@mcpstack/agent-sdk 1.0.0-pr.16.7572c080abaa.13.1 → 1.0.0-pr.18.bbb0c016bc21.17.1

package/README.md

@@ -2,7 +2,9 @@
 
 Use MCP Stack agents in your app.
 
-This package now has one public model for custom product integrations: `App Agent`.
+AgentSDK is MCP Stack's first-party AG-UI client. Your app talks AG-UI to the agent; MCP Stack keeps server tools on MCP through Gateway, AuthGateway, budgets, logs, and permissions.
+
+This package has one public model for custom product integrations: `App Agent`.
 
 ## Install
 
@@ -62,21 +64,21 @@ export function App() {
   return (
     <div style={{ height: 640 }}>
       <McpStackChat
-        apiKey="mcpstack_sk_xxxx"
+        apiKey="mcpstack_pk_xxxx"
         agentId="ag_xxxxx"
         appSessionKey={session.id}
-    userIdentity={{
-      subject: session.user.id,
-      email: session.user.email,
-      organizationId: session.organizationId,
-    }}
-    auth={{
-      mode: "app-token",
-      getToken: () => session.getAccessToken(),
-    }}
-    mode="inline"
-    title="Support Agent"
-  />
+        userIdentity={{
+          subject: session.user.id,
+          email: session.user.email,
+          organizationId: session.organizationId,
+        }}
+        auth={{
+          mode: "app-token",
+          getToken: () => session.getAccessToken(),
+        }}
+        mode="inline"
+        title="Support Agent"
+      />
     </div>
   );
 }
@@ -89,7 +91,7 @@ import { useAppAgent } from "@mcpstack/agent-sdk/react";
 
 export function CustomAssistant() {
   const agent = useAppAgent({
-    apiKey: "mcpstack_sk_xxxx",
+    apiKey: "mcpstack_pk_xxxx",
     agentId: "ag_xxxxx",
     appSessionKey: session.id,
     userIdentity: {
@@ -116,7 +118,7 @@ import { useAppAgent } from "@mcpstack/agent-sdk/react-native";
 
 export function AssistantShell() {
   const agent = useAppAgent({
-    apiKey: "mcpstack_sk_xxxx",
+    apiKey: "mcpstack_pk_xxxx",
     agentId: "ag_xxxxx",
     appSessionKey: session.id,
     userIdentity: {
@@ -140,7 +142,7 @@ export function AssistantShell() {
 import { McpStackAgent } from "@mcpstack/agent-sdk";
 
 const agent = new McpStackAgent({
-  apiKey: "mcpstack_sk_xxxx",
+  apiKey: "mcpstack_pk_xxxx",
   agentId: "ag_xxxxx",
   authSessionKey: session.id,
 });
@@ -158,7 +160,7 @@ Apps can tune the behavior without implementing their own VAD:
 
 ```ts
 const agent = new McpStackAgent({
-  apiKey: "mcpstack_sk_xxxx",
+  apiKey: "mcpstack_pk_xxxx",
   agentId: "ag_xxxxx",
   audioInput: {
     turnDetection: {
@@ -175,7 +177,7 @@ const agent = new McpStackAgent({
 
 ### `apiKey`
 
-Your MCP Stack API key.
+Your MCP Stack public agent key, usually an `mcpstack_pk_*` embed key scoped to the agent and allowed browser origins.
 
 ### `agentId`
 
@@ -215,19 +217,40 @@ auth: {
 auth library refreshes tokens, read from that current session source rather than
 capturing a token from the first render.
 
-The SDK exchanges that app token at Gateway for an MCP-facing token without
-OAuth client registration. External MCP clients can still use the same
-Gateway-backed server through standard OAuth discovery, registration, and
-authorization.
+The SDK forwards that app token with the AG-UI run. When the agent needs a server MCP tool, MCP Stack exchanges the app token at Gateway for an MCP-facing token without OAuth client registration. External MCP clients can still use the same Gateway-backed server through standard OAuth discovery, registration, and authorization.
 
 ### `clientTools`
 
 App-owned functions the agent can call locally for UI work or host orchestration.
 
+AgentSDK sends these as AG-UI frontend tool schemas. They run in your app and should stay focused on route changes, current-screen reads, drafting, filtering, approvals, and other local UI work. Use server MCP tools for authoritative backend reads and writes.
+
 ### `appContext`
 
 Extra host context or policy instructions for the agent.
 
+## Protocol boundary
+
+AgentSDK uses AG-UI for agent turns:
+
+```text
+AgentSDK / custom AG-UI frontend
+        -> AG-UI
+MCP Stack Agent
+        -> MCP
+MCP Stack Server
+        -> Gateway / AuthGateway
+        -> SaaS API
+```
+
+That means:
+
+- assistant text and tool progress stream as AG-UI events
+- `clientTools` map to AG-UI frontend tools
+- server MCP tools execute server-side through Gateway/AuthGateway
+- budgets, logs, and permissions still apply to server-side work
+- existing `useAppAgent`, `createAppAgent`, and `McpStackChat` integrations do not need a major rewrite
+
 ## OAuth
 
 If an external MCP client needs user-scoped OAuth:

package/dist/app/index.d.mts

@@ -106,7 +106,7 @@ interface McpStackAgentConfig {
     oauthClientMetadataUrl?: string;
     /**
      * Callback to get the auth token for MCP Stack API requests.
-     * If provided, called before each chat API request.
+     * If provided, called before each agent run request.
      * Use this when your session token may expire and needs refresh (e.g., dashboard playground).
      * If not provided, uses the static `apiKey` value.
      */
@@ -429,8 +429,9 @@ type EventHandler<T> = (data: T) => void;
  * Framework-agnostic — works in any JavaScript environment.
  *
  * Handles:
- * - Communication with the MCP Stack chat API (SSE streaming)
- * - Tool execution via MCP server (browser-side, with user's auth token)
+ * - Communication with the MCP Stack AG-UI run endpoint (SSE streaming)
+ * - AG-UI frontend tool execution via configured clientTools
+ * - MCP server auth/session helpers for legacy and explicit auth flows
  * - Conversation state management
  * - Event emission for UI updates
  */
@@ -497,6 +498,11 @@ declare class McpStackAgent {
     submitFeedback(input: SubmitConversationFeedbackRequest): Promise<ConversationFeedback>;
     /** Convert client tools to the API schema format. */
     private clientToolsToSchemas;
+    private clientToolsToAgUiTools;
+    private buildAgUiContext;
+    private buildAgUiForwardedProps;
+    private buildAgUiUserRunInput;
+    private buildAgUiToolResultRunInput;
     private resolveExternalUserId;
     private buildExternalUserContext;
     /** Latest runtime budget snapshot for the current SDK identity. */
@@ -596,18 +602,28 @@ declare class McpStackAgent {
     private resolveToken;
     /**
      * The core orchestration loop:
-     * 1. Send message to chat API
-     * 2. Stream response
-     * 3. If tool_call → execute tool via MCP → send result → continue
-     * 4. If message_end → done
+     * 1. Send message to the AG-UI run endpoint
+     * 2. Stream assistant text, server MCP tool progress, and frontend tool requests
+     * 3. If an AG-UI frontend tool is requested, execute the matching clientTool locally
+     * 4. Send the frontend tool result back as an AG-UI tool message and continue
      */
     private runChatLoop;
-    private callChatApi;
+    private executeClientTool;
+    private callAgUiApi;
+    private processAgUiStream;
+    private recordToolResult;
+    private recordToolError;
+    private serializeToolContent;
+    private parseToolContent;
+    private parseToolArguments;
+    private getRecordField;
+    private getStringField;
+    private getNumberField;
     private fetchConversationMessages;
     private applyConversationPage;
     private mapReplayMessage;
     /**
-     * Process an SSE stream from the chat API.
+     * Process a legacy chat SSE stream.
      * Returns when the stream ends (either message_end or tool_call).
      */
     private processSseStream;

package/dist/app/index.d.ts

@@ -106,7 +106,7 @@ interface McpStackAgentConfig {
     oauthClientMetadataUrl?: string;
     /**
      * Callback to get the auth token for MCP Stack API requests.
-     * If provided, called before each chat API request.
+     * If provided, called before each agent run request.
      * Use this when your session token may expire and needs refresh (e.g., dashboard playground).
      * If not provided, uses the static `apiKey` value.
      */
@@ -429,8 +429,9 @@ type EventHandler<T> = (data: T) => void;
  * Framework-agnostic — works in any JavaScript environment.
  *
  * Handles:
- * - Communication with the MCP Stack chat API (SSE streaming)
- * - Tool execution via MCP server (browser-side, with user's auth token)
+ * - Communication with the MCP Stack AG-UI run endpoint (SSE streaming)
+ * - AG-UI frontend tool execution via configured clientTools
+ * - MCP server auth/session helpers for legacy and explicit auth flows
  * - Conversation state management
  * - Event emission for UI updates
  */
@@ -497,6 +498,11 @@ declare class McpStackAgent {
     submitFeedback(input: SubmitConversationFeedbackRequest): Promise<ConversationFeedback>;
     /** Convert client tools to the API schema format. */
     private clientToolsToSchemas;
+    private clientToolsToAgUiTools;
+    private buildAgUiContext;
+    private buildAgUiForwardedProps;
+    private buildAgUiUserRunInput;
+    private buildAgUiToolResultRunInput;
     private resolveExternalUserId;
     private buildExternalUserContext;
     /** Latest runtime budget snapshot for the current SDK identity. */
@@ -596,18 +602,28 @@ declare class McpStackAgent {
     private resolveToken;
     /**
      * The core orchestration loop:
-     * 1. Send message to chat API
-     * 2. Stream response
-     * 3. If tool_call → execute tool via MCP → send result → continue
-     * 4. If message_end → done
+     * 1. Send message to the AG-UI run endpoint
+     * 2. Stream assistant text, server MCP tool progress, and frontend tool requests
+     * 3. If an AG-UI frontend tool is requested, execute the matching clientTool locally
+     * 4. Send the frontend tool result back as an AG-UI tool message and continue
      */
     private runChatLoop;
-    private callChatApi;
+    private executeClientTool;
+    private callAgUiApi;
+    private processAgUiStream;
+    private recordToolResult;
+    private recordToolError;
+    private serializeToolContent;
+    private parseToolContent;
+    private parseToolArguments;
+    private getRecordField;
+    private getStringField;
+    private getNumberField;
     private fetchConversationMessages;
     private applyConversationPage;
     private mapReplayMessage;
     /**
-     * Process an SSE stream from the chat API.
+     * Process a legacy chat SSE stream.
      * Returns when the stream ends (either message_end or tool_call).
      */
     private processSseStream;