Merge pull request #1082 from objectstack-ai/copilot/fix-agent-chat-message-format

hotlong · web-flow · commit 6df22a59e0cb · 2026-04-07T18:12:13.000+08:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -8,6 +8,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Fixed
+- **Agent Chat: Vercel AI SDK v6 `parts` format support** — The agent chat endpoint
+  (`/api/v1/ai/agents/:agentName/chat`) now accepts Vercel AI SDK v6 `parts`-based message
+  format in addition to the legacy `content` string format. Previously, sending messages
+  with `parts` (as `useChat` v6 does by default) resulted in a 400 error:
+  `"message.content must be a string"`. Shared validation and normalization utilities
+  (`validateMessageContent`, `normalizeMessage`) are extracted into `message-utils.ts`
+  for reuse across both the general chat and agent chat routes.
 - **Studio: Code tab now shows CodeExporter** — The Code tab in Studio metadata detail pages
   now correctly renders the `CodeExporter` component (TypeScript/JSON export with copy-to-clipboard)
   instead of always showing the JSON Inspector preview. The default plugin now registers two separate
diff --git a/packages/services/service-ai/src/__tests__/chatbot-features.test.ts b/packages/services/service-ai/src/__tests__/chatbot-features.test.ts
@@ -874,6 +874,78 @@ describe('Agent Routes', () => {
     // temperature is a safe key, should be passed through
     // tools/toolChoice/model should NOT be passed through
   });
+
+  // ── Vercel AI SDK v6 `parts` format support ──
+
+  it('should accept Vercel AI SDK v6 parts format messages', async () => {
+    const chatRoute = routes.find(r => r.method === 'POST')!;
+    const resp = await chatRoute.handler({
+      params: { agentName: 'data_chat' },
+      body: {
+        messages: [
+          {
+            role: 'user',
+            parts: [{ type: 'text', text: 'List all tables' }],
+          },
+        ],
+      },
+    });
+    expect(resp.status).toBe(200);
+    expect((resp.body as any).content).toBe('Agent response');
+  });
+
+  it('should accept mixed parts and content messages', async () => {
+    const chatRoute = routes.find(r => r.method === 'POST')!;
+    const resp = await chatRoute.handler({
+      params: { agentName: 'data_chat' },
+      body: {
+        messages: [
+          { role: 'user', content: 'Hello' },
+          {
+            role: 'assistant',
+            parts: [{ type: 'text', text: 'Hi there' }],
+          },
+          {
+            role: 'user',
+            parts: [{ type: 'text', text: 'List objects' }],
+          },
+        ],
+      },
+    });
+    expect(resp.status).toBe(200);
+  });
+
+  it('should accept assistant message with parts and no content', async () => {
+    const chatRoute = routes.find(r => r.method === 'POST')!;
+    const resp = await chatRoute.handler({
+      params: { agentName: 'data_chat' },
+      body: {
+        messages: [
+          {
+            role: 'assistant',
+            parts: [{ type: 'text', text: 'previous response' }],
+          },
+          {
+            role: 'user',
+            parts: [{ type: 'text', text: 'follow up' }],
+          },
+        ],
+      },
+    });
+    expect(resp.status).toBe(200);
+  });
+
+  it('should reject user message with neither content nor parts', async () => {
+    const chatRoute = routes.find(r => r.method === 'POST')!;
+    const resp = await chatRoute.handler({
+      params: { agentName: 'data_chat' },
+      body: {
+        messages: [{ role: 'user' }],
+      },
+    });
+    expect(resp.status).toBe(400);
+    expect((resp.body as any).error).toContain('content');
+  });
 });
 
 // ═══════════════════════════════════════════════════════════════════
diff --git a/packages/services/service-ai/src/routes/agent-routes.ts b/packages/services/service-ai/src/routes/agent-routes.ts
@@ -5,6 +5,7 @@ import type { Logger } from '@objectstack/spec/contracts';
 import type { AIService } from '../ai-service.js';
 import type { AgentRuntime, AgentChatContext } from '../agent-runtime.js';
 import type { RouteDefinition } from './ai-routes.js';
+import { normalizeMessage, validateMessageContent } from './message-utils.js';
 
 /**
  * Allowed message roles for the agent chat endpoint.
@@ -25,10 +26,10 @@ function validateAgentMessage(raw: unknown): string | null {
   if (typeof msg.role !== 'string' || !ALLOWED_AGENT_ROLES.has(msg.role)) {
     return `message.role must be one of ${[...ALLOWED_AGENT_ROLES].map(r => `"${r}"`).join(', ')} for agent chat`;
   }
-  if (typeof msg.content !== 'string') {
-    return 'message.content must be a string';
-  }
-  return null;
+
+  // Assistant messages may legitimately have empty content (e.g. tool-call-only)
+  const allowEmpty = msg.role === 'assistant';
+  return validateMessageContent(msg, { allowEmptyContent: allowEmpty });
 }
 
 /**
@@ -134,7 +135,7 @@ export function buildAgentRoutes(
           // Prepend system messages then user conversation
           const fullMessages: ModelMessage[] = [
             ...systemMessages,
-            ...(rawMessages as ModelMessage[]),
+            ...rawMessages.map(m => normalizeMessage(m as Record<string, unknown>)),
           ];
 
           // Use chatWithTools for automatic tool resolution
diff --git a/packages/services/service-ai/src/routes/ai-routes.ts b/packages/services/service-ai/src/routes/ai-routes.ts
@@ -3,6 +3,7 @@
 import type { IAIService, IAIConversationService, ModelMessage } from '@objectstack/spec/contracts';
 import type { Logger } from '@objectstack/spec/contracts';
 import { encodeVercelDataStream } from '../stream/vercel-stream-encoder.js';
+import { normalizeMessage, validateMessageContent } from './message-utils.js';
 
 /**
  * Minimal HTTP handler abstraction so routes stay framework-agnostic.
@@ -77,37 +78,6 @@ export interface RouteResponse {
 /** Valid message roles accepted by the AI routes. */
 const VALID_ROLES = new Set<string>(['system', 'user', 'assistant', 'tool']);
 
-/**
- * Normalize a Vercel AI SDK v6 message (which may use `parts` instead of
- * `content`) into a plain `{ role, content }` ModelMessage.
- */
-function normalizeMessage(raw: Record<string, unknown>): ModelMessage {
-  const role = raw.role as string;
-
-  // If content is already a string, use it directly
-  if (typeof raw.content === 'string') {
-    return { role, content: raw.content } as unknown as ModelMessage;
-  }
-
-  // If content is an array (multi-part), pass through
-  if (Array.isArray(raw.content)) {
-    return { role, content: raw.content } as unknown as ModelMessage;
-  }
-
-  // Vercel AI SDK v6: extract text from `parts` array
-  if (Array.isArray(raw.parts)) {
-    const textParts = (raw.parts as Array<Record<string, unknown>>)
-      .filter(p => p.type === 'text' && typeof p.text === 'string')
-      .map(p => p.text as string);
-    if (textParts.length > 0) {
-      return { role, content: textParts.join('') } as unknown as ModelMessage;
-    }
-  }
-
-  // Fallback: empty content (e.g. tool-only assistant messages)
-  return { role, content: '' } as unknown as ModelMessage;
-}
-
 /**
  * Validate that `raw` is a well-formed message.
  * Returns null on success, or an error string on failure.
@@ -125,44 +95,10 @@ function validateMessage(raw: unknown): string | null {
   if (typeof msg.role !== 'string' || !VALID_ROLES.has(msg.role)) {
     return `message.role must be one of ${[...VALID_ROLES].map(r => `"${r}"`).join(', ')}`;
   }
-  const content = msg.content;
-
-  // Vercel AI SDK v6 sends `parts` instead of (or alongside) `content`.
-  // Accept any message that carries a `parts` array, even when `content` is absent.
-  if (Array.isArray(msg.parts)) {
-    return null;
-  }
-
-  // content is a plain string — OK
-  if (typeof content === 'string') {
-    return null;
-  }
-
-  // content is an array of typed parts (legacy multi-part format)
-  if (Array.isArray(content)) {
-    for (const part of content as unknown[]) {
-      if (typeof part !== 'object' || part === null) {
-        return 'message.content array elements must be non-null objects';
-      }
-      const partObj = part as Record<string, unknown>;
-      if (typeof partObj.type !== 'string') {
-        return 'each message.content array element must have a string "type" property';
-      }
-      if (partObj.type === 'text' && typeof partObj.text !== 'string') {
-        return 'message.content elements with type "text" must have a string "text" property';
-      }
-    }
-    return null;
-  }
 
   // Assistant / tool messages may legitimately have null or missing content
-  if (content === null || content === undefined) {
-    if (msg.role === 'assistant' || msg.role === 'tool') {
-      return null;
-    }
-  }
-
-  return 'message.content must be a string, an array, or include parts';
+  const allowEmpty = msg.role === 'assistant' || msg.role === 'tool';
+  return validateMessageContent(msg, { allowEmptyContent: allowEmpty });
 }
 
 /**
diff --git a/packages/services/service-ai/src/routes/index.ts b/packages/services/service-ai/src/routes/index.ts
@@ -2,3 +2,4 @@
 
 export { buildAIRoutes } from './ai-routes.js';
 export type { RouteDefinition, RouteRequest, RouteResponse, RouteUserContext } from './ai-routes.js';
+export { normalizeMessage, validateMessageContent } from './message-utils.js';
diff --git a/packages/services/service-ai/src/routes/message-utils.ts b/packages/services/service-ai/src/routes/message-utils.ts
@@ -0,0 +1,90 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { ModelMessage } from '@objectstack/spec/contracts';
+
+/**
+ * Normalize a Vercel AI SDK v6 message (which may use `parts` instead of
+ * `content`) into a plain `{ role, content }` ModelMessage.
+ *
+ * Shared between the general chat routes and agent chat routes.
+ */
+export function normalizeMessage(raw: Record<string, unknown>): ModelMessage {
+  const role = raw.role as string;
+
+  // If content is already a string, use it directly
+  if (typeof raw.content === 'string') {
+    return { role, content: raw.content } as unknown as ModelMessage;
+  }
+
+  // If content is an array (multi-part), pass through
+  if (Array.isArray(raw.content)) {
+    return { role, content: raw.content } as unknown as ModelMessage;
+  }
+
+  // Vercel AI SDK v6: extract text from `parts` array
+  if (Array.isArray(raw.parts)) {
+    const textParts = (raw.parts as Array<Record<string, unknown>>)
+      .filter(p => p.type === 'text' && typeof p.text === 'string')
+      .map(p => p.text as string);
+    if (textParts.length > 0) {
+      return { role, content: textParts.join('') } as unknown as ModelMessage;
+    }
+  }
+
+  // Fallback: empty content (e.g. tool-only assistant messages)
+  return { role, content: '' } as unknown as ModelMessage;
+}
+
+/**
+ * Validate message content/parts format (role-agnostic).
+ *
+ * Returns `null` when the content shape is valid, or an error string
+ * describing the first violation found.
+ *
+ * Accepts:
+ *  - Simple string `content` (legacy)
+ *  - Array `content` (e.g. `[{ type: 'text', text: '...' }]`)
+ *  - Vercel AI SDK v6 `parts` format (content may be absent/null)
+ *  - Null/undefined `content` for assistant messages (when `allowEmpty` is true)
+ */
+export function validateMessageContent(
+  msg: Record<string, unknown>,
+  opts?: { allowEmptyContent?: boolean },
+): string | null {
+  const content = msg.content;
+
+  // Vercel AI SDK v6 sends `parts` instead of (or alongside) `content`.
+  // Accept any message that carries a `parts` array, even when `content` is absent.
+  if (Array.isArray(msg.parts)) {
+    return null;
+  }
+
+  // content is a plain string — OK
+  if (typeof content === 'string') {
+    return null;
+  }
+
+  // content is an array of typed parts (legacy multi-part format)
+  if (Array.isArray(content)) {
+    for (const part of content as unknown[]) {
+      if (typeof part !== 'object' || part === null) {
+        return 'message.content array elements must be non-null objects';
+      }
+      const partObj = part as Record<string, unknown>;
+      if (typeof partObj.type !== 'string') {
+        return 'each message.content array element must have a string "type" property';
+      }
+      if (partObj.type === 'text' && typeof partObj.text !== 'string') {
+        return 'message.content elements with type "text" must have a string "text" property';
+      }
+    }
+    return null;
+  }
+
+  // Allow empty content for certain roles (e.g. assistant tool-call messages)
+  if ((content === null || content === undefined) && opts?.allowEmptyContent) {
+    return null;
+  }
+
+  return 'message.content must be a string, an array, or include parts';
+}

Original file line number	Diff line number	Diff line change
`@@ -2,3 +2,4 @@`
`2`	`2`
`3`	`3`	`export { buildAIRoutes } from './ai-routes.js';`
`4`	`4`	`export type { RouteDefinition, RouteRequest, RouteResponse, RouteUserContext } from './ai-routes.js';`
	`5`	`+export { normalizeMessage, validateMessageContent } from './message-utils.js';`