refactor(core, api, ui, sdk-ts, sdk-py, docs): remove support for the system role in the messages (#70)

GenerQAQ · web-flow · commit efaef3462f9d · 2025-12-09T23:35:54.000+08:00
* refactor(core): remove the 'system' role option

* refactor(api): remove support for 'system' role in messages and update related tests

* refactor(ui): remove 'system' role from messages and update related components

* refactor(sdk-ts): further remove 'system' role from AcontextMessage and related functions

* refactor(sdk-py): eliminate 'system' role

* refactor(docs): remove 'system' role from message examples and update best practices
diff --git a/docs/integrations/agno.mdx b/docs/integrations/agno.mdx
@@ -275,7 +275,7 @@ Agno uses OpenAI-compatible message format, which works seamlessly with Acontext
 ```python
 # Agno message format (compatible with Acontext)
 message = {
-    "role": "user",  # or "assistant", "system"
+    "role": "user",  # or "assistant"
     "content": "Your message here"
 }
 
diff --git a/docs/integrations/openai-python.mdx b/docs/integrations/openai-python.mdx
@@ -182,9 +182,7 @@ Handle tool calls in a loop until the agent provides a final response:
 ```python
 def run_agent(client: OpenAI, conversation: list[dict]) -> tuple[str, list[dict]]:
     """Run the agent with tool calling support."""
-    messages_to_send = [
-        {"role": "system", "content": "You are a helpful assistant"}
-    ] + conversation
+    messages_to_send = list(conversation)
     
     new_messages = []
     max_iterations = 10
@@ -420,7 +418,7 @@ acontext_client.sessions.send_message(session_id=session_id, blob=tool_result)
 ## Best Practices
 
 <Tip>
-**Message format**: OpenAI message format is compatible with Acontext, so you can send messages directly without conversion. This includes user, assistant, system, and tool messages.
+**Message format**: OpenAI message format is compatible with Acontext, so you can send messages directly without conversion. This includes user, assistant, and tool messages. System prompts should be handled through session-level or skill-level configuration rather than as messages.
 </Tip>
 
 <Tip>
diff --git a/docs/integrations/openai-typescript.mdx b/docs/integrations/openai-typescript.mdx
@@ -198,7 +198,6 @@ async function runAgent(
   conversation: any[]
 ): Promise<[string, any[]]> {
   const messagesToSend: any[] = [
-    { role: 'system', content: 'You are a helpful assistant' },
     ...conversation,
   ];
 
diff --git a/src/client/acontext-py/src/acontext/messages.py b/src/client/acontext-py/src/acontext/messages.py
@@ -31,22 +31,22 @@ class AcontextMessage:
     Represents an Acontext-format message payload.
     """
 
-    role: Literal["user", "assistant", "system"]
+    role: Literal["user", "assistant"]
     parts: list[MessagePart]
     meta: Mapping[str, Any] | None = None
 
 
 def build_acontext_message(
     *,
-    role: Literal["user", "assistant", "system"],
+    role: Literal["user", "assistant"],
     parts: Sequence[MessagePart | str | Mapping[str, Any]],
     meta: Mapping[str, Any] | None = None,
 ) -> AcontextMessage:
     """
     Construct an Acontext-format message blob and associated multipart files.
     """
-    if role not in {"user", "assistant", "system"}:
-        raise ValueError("role must be one of {'user', 'assistant', 'system'}")
+    if role not in {"user", "assistant"}:
+        raise ValueError("role must be one of {'user', 'assistant'}")
 
     normalized_parts = [normalize_message_part(part) for part in parts]
 
diff --git a/src/client/acontext-py/src/acontext/types/session.py b/src/client/acontext-py/src/acontext/types/session.py
@@ -65,7 +65,7 @@ class Message(BaseModel):
     id: str = Field(..., description="Message UUID")
     session_id: str = Field(..., description="Session UUID")
     parent_id: str | None = Field(None, description="Parent message UUID")
-    role: str = Field(..., description="Message role: 'user', 'assistant', or 'system'")
+    role: str = Field(..., description="Message role: 'user' or 'assistant'")
     meta: dict[str, Any] = Field(..., description="Message metadata")
     parts: list[Part] = Field(..., description="List of message parts")
     task_id: str | None = Field(None, description="Task UUID if associated with a task")
diff --git a/src/client/acontext-ts/src/messages.ts b/src/client/acontext-ts/src/messages.ts
@@ -59,15 +59,15 @@ export class MessagePart {
 }
 
 export const AcontextMessageSchema = z.object({
-  role: z.enum(['user', 'assistant', 'system']),
+  role: z.enum(['user', 'assistant']),
   parts: z.array(MessagePartSchema),
   meta: z.record(z.string(), z.unknown()).nullable().optional(),
 });
 
 export type AcontextMessageInput = z.infer<typeof AcontextMessageSchema>;
 
 export class AcontextMessage {
-  role: 'user' | 'assistant' | 'system';
+  role: 'user' | 'assistant';
   parts: MessagePart[];
   meta?: Record<string, unknown> | null;
 
@@ -89,12 +89,12 @@ export class AcontextMessage {
 }
 
 export function buildAcontextMessage(options: {
-  role: 'user' | 'assistant' | 'system';
+  role: 'user' | 'assistant';
   parts: (MessagePart | string | MessagePartInput)[];
   meta?: Record<string, unknown> | null;
 }): AcontextMessage {
-  if (!['user', 'assistant', 'system'].includes(options.role)) {
-    throw new Error("role must be one of {'user', 'assistant', 'system'}");
+  if (!['user', 'assistant'].includes(options.role)) {
+    throw new Error("role must be one of {'user', 'assistant'}");
   }
 
   const normalizedParts = options.parts.map((part) => {
diff --git a/src/server/api/go/internal/modules/handler/session_test.go b/src/server/api/go/internal/modules/handler/session_test.go
@@ -764,28 +764,6 @@ func TestSessionHandler_SendMessage(t *testing.T) {
 			},
 			expectedStatus: http.StatusCreated,
 		},
-		{
-			name:           "openai format - system message",
-			sessionIDParam: sessionID.String(),
-			requestBody: map[string]interface{}{
-				"format": "openai",
-				"blob": map[string]interface{}{
-					"role":    "system",
-					"content": "You are a helpful assistant that speaks like a pirate.",
-				},
-			},
-			setup: func(svc *MockSessionService) {
-				expectedMessage := &model.Message{
-					ID:        uuid.New(),
-					SessionID: sessionID,
-					Role:      "system",
-				}
-				svc.On("SendMessage", mock.Anything, mock.MatchedBy(func(in service.SendMessageInput) bool {
-					return in.ProjectID == projectID && in.SessionID == sessionID && in.Role == "system"
-				})).Return(expectedMessage, nil)
-			},
-			expectedStatus: http.StatusCreated,
-		},
 		{
 			name:           "openai format - assistant with multiple tool_calls",
 			sessionIDParam: sessionID.String(),
diff --git a/src/server/api/go/internal/modules/model/message.go b/src/server/api/go/internal/modules/model/message.go
@@ -23,7 +23,7 @@ type Message struct {
 	Parent    *Message   `gorm:"foreignKey:ParentID;references:ID;constraint:OnDelete:CASCADE,OnUpdate:CASCADE;" json:"-"`
 	Children  []Message  `gorm:"foreignKey:ParentID;constraint:OnDelete:CASCADE,OnUpdate:CASCADE;" json:"-"`
 
-	Role string `gorm:"type:text;not null;check:role IN ('user','assistant','system')" json:"role"`
+	Role string `gorm:"type:text;not null;check:role IN ('user','assistant')" json:"role"`
 
 	Meta datatypes.JSONType[map[string]any] `gorm:"type:jsonb;not null;default:'{}'" swaggertype:"object" json:"meta"`
 
diff --git a/src/server/api/go/internal/pkg/converter/anthropic.go b/src/server/api/go/internal/pkg/converter/anthropic.go
@@ -21,11 +21,6 @@ func (c *AnthropicConverter) Convert(messages []model.Message, publicURLs map[st
 	result := make([]anthropic.MessageParam, 0, len(messages))
 
 	for _, msg := range messages {
-		// Skip system messages - they should be handled separately via system parameter
-		if msg.Role == "system" {
-			continue
-		}
-
 		anthropicMsg := c.convertMessage(msg, publicURLs)
 		result = append(result, anthropicMsg)
 	}
@@ -48,7 +43,6 @@ func (c *AnthropicConverter) convertMessage(msg model.Message, publicURLs map[st
 
 func (c *AnthropicConverter) convertRole(role string) string {
 	// Anthropic roles: "user", "assistant"
-	// Note: "system" messages should be passed via the top-level system parameter
 	switch role {
 	case "assistant":
 		return "assistant"
diff --git a/src/server/api/go/internal/pkg/converter/openai.go b/src/server/api/go/internal/pkg/converter/openai.go
@@ -31,9 +31,6 @@ func (c *OpenAIConverter) Convert(messages []model.Message, publicURLs map[strin
 			case "assistant":
 				assistantMsg := c.convertToAssistantMessage(msg)
 				result = append(result, assistantMsg)
-			case "system":
-				systemMsg := c.convertToSystemMessage(msg)
-				result = append(result, systemMsg)
 			default:
 				// Default to user message
 				userMsg := c.convertToUserMessage(msg, publicURLs)
@@ -196,33 +193,6 @@ func (c *OpenAIConverter) convertToAssistantMessage(msg model.Message) openai.Ch
 	}
 }
 
-func (c *OpenAIConverter) convertToSystemMessage(msg model.Message) openai.ChatCompletionMessageParamUnion {
-	// Extract text from parts
-	text := ""
-	for _, part := range msg.Parts {
-		if part.Type == "text" {
-			text += part.Text
-		}
-	}
-
-	systemParam := openai.ChatCompletionSystemMessageParam{
-		Content: openai.ChatCompletionSystemMessageParamContentUnion{
-			OfString: param.NewOpt(text),
-		},
-	}
-
-	// Add name field from message meta if present
-	if metaData := msg.Meta.Data(); len(metaData) > 0 {
-		if name, ok := metaData["name"].(string); ok && name != "" {
-			systemParam.Name = param.NewOpt(name)
-		}
-	}
-
-	return openai.ChatCompletionMessageParamUnion{
-		OfSystem: &systemParam,
-	}
-}
-
 func (c *OpenAIConverter) convertToToolMessage(msg model.Message) openai.ChatCompletionMessageParamUnion {
 	// Extract tool result information
 	toolCallID := c.extractToolCallID(msg.Parts)
diff --git a/src/server/api/go/internal/pkg/normalizer/acontext.go b/src/server/api/go/internal/pkg/normalizer/acontext.go
@@ -25,9 +25,9 @@ func (n *AcontextNormalizer) NormalizeFromAcontextMessage(messageJSON json.RawMe
 	}
 
 	// Validate role
-	validRoles := map[string]bool{"user": true, "assistant": true, "system": true}
+	validRoles := map[string]bool{"user": true, "assistant": true}
 	if !validRoles[msg.Role] {
-		return "", nil, nil, fmt.Errorf("invalid role: %s (must be one of: user, assistant, system)", msg.Role)
+		return "", nil, nil, fmt.Errorf("invalid role: %s (must be one of: user, assistant)", msg.Role)
 	}
 
 	// Validate each part
diff --git a/src/server/api/go/internal/pkg/normalizer/acontext_test.go b/src/server/api/go/internal/pkg/normalizer/acontext_test.go
@@ -43,16 +43,15 @@ func TestAcontextNormalizer_NormalizeFromAcontextMessage(t *testing.T) {
 			wantErr:     false,
 		},
 		{
-			name: "valid system message",
+			name: "invalid system message (not supported)",
 			input: `{
 				"role": "system",
 				"parts": [
 					{"type": "text", "text": "You are a helpful assistant."}
 				]
 			}`,
-			wantRole:    "system",
-			wantPartCnt: 1,
-			wantErr:     false,
+			wantErr:     true,
+			errContains: "invalid role",
 		},
 		{
 			name: "message with multiple parts",
diff --git a/src/server/api/go/internal/pkg/normalizer/openai.go b/src/server/api/go/internal/pkg/normalizer/openai.go
@@ -28,13 +28,13 @@ func (n *OpenAINormalizer) NormalizeFromOpenAIMessage(messageJSON json.RawMessag
 	} else if message.OfAssistant != nil {
 		return normalizeOpenAIAssistantMessage(*message.OfAssistant)
 	} else if message.OfSystem != nil {
-		return normalizeOpenAISystemMessage(*message.OfSystem)
+		return "", nil, nil, fmt.Errorf("system messages are not supported. Use session-level or skill-level configuration for system prompts")
 	} else if message.OfTool != nil {
 		return normalizeOpenAIToolMessage(*message.OfTool)
 	} else if message.OfFunction != nil {
 		return normalizeOpenAIFunctionMessage(*message.OfFunction)
 	} else if message.OfDeveloper != nil {
-		return normalizeOpenAIDeveloperMessage(*message.OfDeveloper)
+		return "", nil, nil, fmt.Errorf("developer messages are not supported. Use session-level or skill-level configuration for system prompts")
 	}
 
 	return "", nil, nil, fmt.Errorf("unknown OpenAI message type")
@@ -135,72 +135,6 @@ func normalizeOpenAIAssistantMessage(msg openai.ChatCompletionAssistantMessagePa
 	return "assistant", parts, messageMeta, nil
 }
 
-func normalizeOpenAISystemMessage(msg openai.ChatCompletionSystemMessageParam) (string, []service.PartIn, map[string]interface{}, error) {
-	parts := []service.PartIn{}
-
-	// Handle content - can be string or array
-	if !param.IsOmitted(msg.Content.OfString) {
-		parts = append(parts, service.PartIn{
-			Type: "text",
-			Text: msg.Content.OfString.Value,
-		})
-	} else if len(msg.Content.OfArrayOfContentParts) > 0 {
-		for _, textPart := range msg.Content.OfArrayOfContentParts {
-			parts = append(parts, service.PartIn{
-				Type: "text",
-				Text: textPart.Text,
-			})
-		}
-	} else {
-		return "", nil, nil, fmt.Errorf("OpenAI system message must have content")
-	}
-
-	// Extract message-level metadata
-	messageMeta := map[string]interface{}{
-		"source_format": "openai",
-	}
-
-	// Extract name field if present
-	if !param.IsOmitted(msg.Name) {
-		messageMeta["name"] = msg.Name.Value
-	}
-
-	return "system", parts, messageMeta, nil
-}
-
-func normalizeOpenAIDeveloperMessage(msg openai.ChatCompletionDeveloperMessageParam) (string, []service.PartIn, map[string]interface{}, error) {
-	parts := []service.PartIn{}
-
-	// Developer messages are converted to system messages
-	if !param.IsOmitted(msg.Content.OfString) {
-		parts = append(parts, service.PartIn{
-			Type: "text",
-			Text: msg.Content.OfString.Value,
-		})
-	} else if len(msg.Content.OfArrayOfContentParts) > 0 {
-		for _, textPart := range msg.Content.OfArrayOfContentParts {
-			parts = append(parts, service.PartIn{
-				Type: "text",
-				Text: textPart.Text,
-			})
-		}
-	} else {
-		return "", nil, nil, fmt.Errorf("OpenAI developer message must have content")
-	}
-
-	// Extract message-level metadata
-	messageMeta := map[string]interface{}{
-		"source_format": "openai",
-	}
-
-	// Extract name field if present
-	if !param.IsOmitted(msg.Name) {
-		messageMeta["name"] = msg.Name.Value
-	}
-
-	return "system", parts, messageMeta, nil
-}
-
 func normalizeOpenAIToolMessage(msg openai.ChatCompletionToolMessageParam) (string, []service.PartIn, map[string]interface{}, error) {
 	parts := []service.PartIn{}
 
diff --git a/src/server/api/go/internal/pkg/normalizer/openai_test.go b/src/server/api/go/internal/pkg/normalizer/openai_test.go
@@ -115,36 +115,33 @@ func TestOpenAINormalizer_NormalizeFromOpenAIMessage(t *testing.T) {
 			wantErr:     false,
 		},
 		{
-			name: "system message",
+			name: "system message (not supported)",
 			input: `{
 				"role": "system",
 				"content": "You are a helpful assistant."
 			}`,
-			wantRole:    "system",
-			wantPartCnt: 1,
-			wantErr:     false,
+			wantErr:     true,
+			errContains: "system messages are not supported",
 		},
 		{
-			name: "system message with array content",
+			name: "system message with array content (not supported)",
 			input: `{
 				"role": "system",
 				"content": [
 					{"type": "text", "text": "You are a helpful assistant."}
 				]
 			}`,
-			wantRole:    "system",
-			wantPartCnt: 1,
-			wantErr:     false,
+			wantErr:     true,
+			errContains: "system messages are not supported",
 		},
 		{
-			name: "developer message (converted to system)",
+			name: "developer message (not supported)",
 			input: `{
 				"role": "developer",
 				"content": "This is a developer instruction."
 			}`,
-			wantRole:    "system",
-			wantPartCnt: 1,
-			wantErr:     false,
+			wantErr:     true,
+			errContains: "developer messages are not supported",
 		},
 		{
 			name: "tool message",
@@ -195,12 +192,12 @@ func TestOpenAINormalizer_NormalizeFromOpenAIMessage(t *testing.T) {
 			errContains: "must have content",
 		},
 		{
-			name: "system message without content",
+			name: "system message without content (not supported)",
 			input: `{
 				"role": "system"
 			}`,
 			wantErr:     true,
-			errContains: "must have content",
+			errContains: "system messages are not supported",
 		},
 	}
 
diff --git a/src/server/core/acontext_core/schema/llm.py b/src/server/core/acontext_core/schema/llm.py
@@ -25,7 +25,7 @@ class LLMToolCall(BaseModel):
 
 
 class LLMResponse(BaseModel):
-    role: Literal["user", "assistant", "system", "tool"]
+    role: Literal["user", "assistant", "tool"]
     raw_response: BaseModel
 
     content: Optional[str] = None
diff --git a/src/server/core/acontext_core/schema/orm/message.py b/src/server/core/acontext_core/schema/orm/message.py
diff --git a/src/server/ui/app/session/[sessionId]/messages/page.tsx b/src/server/ui/app/session/[sessionId]/messages/page.tsx
diff --git a/src/server/ui/lib/message-utils.ts b/src/server/ui/lib/message-utils.ts
diff --git a/src/server/ui/types/index.ts b/src/server/ui/types/index.ts

Original file line number	Diff line number	Diff line change
`@@ -275,7 +275,7 @@ Agno uses OpenAI-compatible message format, which works seamlessly with Acontext`
`275`	`275`	```python
`276`	`276`	`# Agno message format (compatible with Acontext)`
`277`	`277`	`message = {`
`278`		`- "role": "user", # or "assistant", "system"`
	`278`	`+ "role": "user", # or "assistant"`
`279`	`279`	`"content": "Your message here"`
`280`	`280`	`}`
`281`	`281`