Skip to content

RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.

fix(agent): resolve structured outputs in Message components (#21311)

Sbaaoui Idrissadaf6b1d39fb
diff --git a/internal/agent/component/agent.go b/internal/agent/component/agent.go
index 21ab299143..82ffbe3002 100644
--- a/internal/agent/component/agent.go
+++ b/internal/agent/component/agent.go
@@ -83,6 +83,7 @@ type AgentParam struct {
Description string
SystemPrompt string
UserPrompt string
+ OutputStructure map[string]any
Thinking string
MaxTokens *int
TopP *float64
@@ -1020,6 +1021,14 @@ func (c *AgentComponent) invokeNow(ctx context.Context, db *gorm.DB, inputs map[
p.UserPrompt = query
}
}
+ if len(p.OutputStructure) > 0 {
+ keys := make([]string, 0, len(p.OutputStructure))
+ for key := range p.OutputStructure {
+ keys = append(keys, key)
+ }
+ sort.Strings(keys)
+ p.SystemPrompt = appendPromptText(p.SystemPrompt, "Return your final answer as a single valid JSON object containing these keys: "+strings.Join(keys, ", ")+". Do not include markdown fences or prose outside the JSON object.")
+ }
if p.ModelID == "" {
return nil, &ParamError{Field: "model_id", Reason: "required"}
@@ -1118,6 +1127,11 @@ func (c *AgentComponent) invokeNow(ctx context.Context, db *gorm.DB, inputs map[
"tool_calls": extractToolCalls(msg),
"artifacts": artifacts,
}
+ if len(p.OutputStructure) > 0 {
+ if parsed, ok := matchOutputStructure(cleanFormattedAnswer(content), p.OutputStructure); ok {
+ out["structured"] = parsed
+ }
+ }
if groundingStatus != "" {
out["grounding_status"] = groundingStatus
}
@@ -1176,6 +1190,7 @@ func (c *AgentComponent) Inputs() map[string]string {
func (c *AgentComponent) Outputs() map[string]string {
return map[string]string{
"content": "Final assistant content (after the ReAct loop terminates)",
+ "structured": "Parsed structured output when configured.",
"thinking": "Model reasoning content, when the provider returns it separately.",
"tool_calls": "One entry per tool call observed during the run",
"artifacts": "Artifacts collected from tool responses (empty in P0)",
@@ -1573,6 +1588,11 @@ func mergeAgentParam(base AgentParam, inputs map[string]any) AgentParam {
if v, ok := stringFrom(inputs, "description"); ok {
p.Description = v
}
+ if outputs, ok := inputs["outputs"].(map[string]any); ok {
+ if structured, ok := outputs["structured"].(map[string]any); ok {
+ p.OutputStructure, _ = structured["properties"].(map[string]any)
+ }
+ }
if v, ok := stringFrom(inputs, "system_prompt"); ok {
p.SystemPrompt = v
} else if v, ok := stringFrom(inputs, "sys_prompt"); ok {
diff --git a/internal/agent/component/message.go b/internal/agent/component/message.go
index fbc0b5f9e5..951d6f0396 100644
--- a/internal/agent/component/message.go
+++ b/internal/agent/component/message.go
@@ -388,11 +388,6 @@ func (m *MessageComponent) resolveDeferredTemplate(ctx context.Context, text str
if len(matches) == 0 {
return text, false, nil
}
- if _, err := runtime.ResolveTemplate(text, state); err != nil {
- if !optionalMissingAttachmentRefs(text, state) {
- return "", false, err
- }
- }
// Ordinary Message templates are rendered and emitted once by Invoke.
// Only templates that actually reference a DeferredStream belong to the
// incremental presentation path below. Emitting literals/normal variable
@@ -402,12 +397,20 @@ func (m *MessageComponent) resolveDeferredTemplate(ctx context.Context, text str
for _, match := range matches {
ref := text[match[2]:match[3]]
value, _ := state.GetVar(ref)
+ if value == nil {
+ if nodeID, _, ok := strings.Cut(ref, "@"); ok {
+ value, _ = state.GetVar(nodeID + "@content")
+ }
+ }
if runtime.IsDeferredStream(value) {
hasDeferred = true
break
}
}
if !hasDeferred {
+ if _, err := runtime.ResolveTemplate(text, state); err != nil && !optionalMissingAttachmentRefs(text, state) {
+ return "", false, err
+ }
return runtime.ResolveTemplateForDisplay(text, state), false, nil
}
var out strings.Builder
@@ -422,7 +425,14 @@ func (m *MessageComponent) resolveDeferredTemplate(ctx context.Context, text str
out.WriteString(literal)
}
ref := text[refStart:refEnd]
+ deferredNodeID := ""
value, _ := state.GetVar(ref)
+ if value == nil {
+ if nodeID, _, ok := strings.Cut(ref, "@"); ok {
+ deferredNodeID = nodeID
+ value, _ = state.GetVar(deferredNodeID + "@content")
+ }
+ }
deferred, ok := value.(*runtime.DeferredStream)
if !ok || deferred == nil || deferred.Open == nil {
resolved := runtime.ResolveTemplateForDisplay(text[start:end], state)
@@ -433,9 +443,14 @@ func (m *MessageComponent) resolveDeferredTemplate(ctx context.Context, text str
}
streamed = true
+ streamContent := deferredNodeID == ""
inThinking := false
visible := strings.Builder{}
result, err := deferred.Open(ctx, func(contentDelta, reasoningDelta string) {
+ // Other outputs are available only after the Agent completes.
+ if !streamContent {
+ return
+ }
if reasoningDelta != "" {
if !inThinking {
runtime.EmitCanvasMessageEvent(ctx, "", true, false)
@@ -473,11 +488,22 @@ func (m *MessageComponent) resolveDeferredTemplate(ctx context.Context, text str
}
}
if strings.Contains(ref, "@") {
- parts := strings.SplitN(ref, "@", 2)
- state.SetVar(parts[0], parts[1], finalText)
- runtime.CompleteDeferredNode(ctx, parts[0])
+ nodeID, _, _ := strings.Cut(ref, "@")
+ if result != nil {
+ for key, output := range result {
+ state.SetVar(nodeID, key, output)
+ }
+ }
+ runtime.CompleteDeferredNode(ctx, nodeID)
}
- out.WriteString(finalText)
+ resolved := runtime.ResolveTemplateForDisplay(text[start:end], state)
+ if strings.HasSuffix(ref, "@content") {
+ resolved = finalText
+ }
+ if !streamContent {
+ runtime.EmitCanvasMessageEvent(ctx, resolved, false, false)
+ }
+ out.WriteString(resolved)
last = end
}
if last < len(text) {
@@ -485,6 +511,9 @@ func (m *MessageComponent) resolveDeferredTemplate(ctx context.Context, text str
runtime.EmitCanvasMessageEvent(ctx, tail, false, false)
out.WriteString(tail)
}
+ if _, err := runtime.ResolveTemplate(text, state); err != nil && !optionalMissingAttachmentRefs(text, state) {
+ return "", streamed, err
+ }
return out.String(), streamed, nil
}