feat(agent): add per-agent citation output toggle

Move citation protocol injection to the system layer so custom prompts no
longer own citation syntax. Agents can disable inline citations while source
aliases still encode and decode tool arguments correctly.
This commit is contained in:
wizardchen
2026-07-16 21:46:52 +08:00
committed by lyingbug
parent 014164ae44
commit b862c2e45d
26 changed files with 292 additions and 78 deletions
@@ -11,18 +11,20 @@ import (
// prepareMessagesWithReferences replaces the pipeline's positional context IDs
// with request-local chunk references in the copy sent to the model. Persisted
// rendered_content and the public citation contract remain unchanged.
// rendered_content remains unchanged; public citations are expanded only when
// the request's agent setting enables them.
func prepareMessagesWithReferences(
ctx context.Context,
chatManage *types.ChatManage,
) ([]chat.Message, *llmreference.Registry) {
refs := llmreference.NewRegistry()
citationsEnabled := chatManage == nil || chatManage.CitationsEnabled()
refs := llmreference.NewRegistry(citationsEnabled)
if chatManage == nil {
return nil, refs
}
messages := prepareMessagesWithHistory(chatManage)
if len(messages) > 0 {
messages[0].Content = strings.TrimRight(messages[0].Content, " \t\r\n") + llmreference.ProtocolPrompt
messages[0].Content = strings.TrimRight(messages[0].Content, " \t\r\n") + llmreference.ProtocolPrompt(citationsEnabled)
}
if len(chatManage.MergeResult) == 0 || len(messages) == 0 {
return messages, refs
@@ -30,7 +30,7 @@ func TestPrepareMessagesWithReferencesUsesChunkCentricContext(t *testing.T) {
messages, refs := prepareMessagesWithReferences(context.Background(), manage)
require.Len(t, messages, 2)
require.Contains(t, messages[0].Content, "Source reference protocol")
require.Contains(t, messages[0].Content, "Source handling protocol")
require.Contains(t, messages[1].Content, `<document id="d1" kb="b1" title="Doc">`)
require.Contains(t, messages[1].Content, `<chunk id="c1" index="1" view="full">`)
require.Contains(t, messages[1].Content, `<chunk id="c2" index="2" view="full">`)
@@ -110,7 +110,30 @@ func TestPrepareMessagesWithReferencesCompactsHistoryWithoutCurrentRetrieval(t *
messages, refs := prepareMessagesWithReferences(context.Background(), manage)
messages = refs.EncodeMessages(messages)
require.Contains(t, messages[0].Content, "Source reference protocol")
require.Contains(t, messages[0].Content, "Source handling protocol")
require.Contains(t, messages[2].Content, `<ref id="w1"/>`)
require.NotContains(t, messages[2].Content, "https://example.com/old")
}
func TestPrepareMessagesWithReferencesSuppressesCitationsWhenDisabled(t *testing.T) {
disabled := false
manage := &types.ChatManage{
PipelineRequest: types.PipelineRequest{
Query: "question",
CitationEnabled: &disabled,
SummaryConfig: types.SummaryConfig{Prompt: "custom system prompt"},
},
PipelineState: types.PipelineState{
UserContent: "question",
MergeResult: []*types.SearchResult{{
ID: "chunk-1", KnowledgeID: "doc-1", KnowledgeBaseID: "kb-1", KnowledgeTitle: "Doc", Content: "evidence",
}},
},
}
messages, refs := prepareMessagesWithReferences(context.Background(), manage)
require.Contains(t, messages[0].Content, "Source citations are disabled")
require.Contains(t, messages[1].Content, `<chunk id="c1"`)
require.NotContains(t, messages[1].Content, "chunk-1")
require.Equal(t, "answer ", refs.ExpandText(`answer <ref id="c1"/>`))
}
@@ -89,10 +89,25 @@ func TestPrepareFallbackMessagesMigratesHistoricalCitations(t *testing.T) {
}}
messages, refs := prepareFallbackMessages(cm, "legacy fallback prompt")
require.Contains(t, messages[0].Content, "Source reference protocol")
require.Contains(t, messages[0].Content, "Source handling protocol")
require.Equal(t, `Previous <ref id="c1"/>`, messages[2].Content)
require.Equal(t,
`<kb doc="Legacy" chunk_id="legacy-chunk" kb_id="legacy-kb" />`,
refs.ExpandText(`<ref id="c1"/>`),
)
}
func TestPrepareFallbackMessagesSuppressesCitationsWhenDisabled(t *testing.T) {
disabled := false
cm := &types.ChatManage{PipelineRequest: types.PipelineRequest{CitationEnabled: &disabled}}
cm.Query = "follow-up"
cm.History = []*types.History{{
Query: "previous",
Answer: `Previous <kb doc="Legacy" chunk_id="legacy-chunk" />`,
}}
messages, refs := prepareFallbackMessages(cm, "legacy fallback prompt")
require.Contains(t, messages[0].Content, "Source citations are disabled")
require.Equal(t, `Previous <ref id="c1"/>`, messages[2].Content)
require.Equal(t, "answer ", refs.ExpandText(`answer <ref id="c1"/>`))
}
@@ -229,6 +229,7 @@ func (s *sessionService) buildAgentConfig(
MCPServices: customAgent.Config.MCPServices,
MCPAuthWaitTimeout: customAgent.Config.MCPAuthWaitTimeout,
Thinking: customAgent.Config.Thinking,
CitationEnabled: customAgent.Config.CitationEnabled,
RetrieveKBOnlyWhenMentioned: customAgent.Config.RetrieveKBOnlyWhenMentioned,
LLMCallTimeout: customAgent.Config.LLMCallTimeout,
RetainRetrievalHistory: customAgent.Config.RetainRetrievalHistory,
@@ -995,11 +995,12 @@ func prepareFallbackMessages(
promptContent string,
) ([]chat.Message, *llmreference.Registry) {
messages := buildFallbackMessages(chatManage, promptContent)
refs := llmreference.NewRegistry()
citationsEnabled := chatManage == nil || chatManage.CitationsEnabled()
refs := llmreference.NewRegistry(citationsEnabled)
if len(messages) > 0 && messages[0].Role == "system" {
messages[0].Content = strings.TrimRight(messages[0].Content, " \t\r\n") + llmreference.ProtocolPrompt
messages[0].Content = strings.TrimRight(messages[0].Content, " \t\r\n") + llmreference.ProtocolPrompt(citationsEnabled)
} else {
messages = append([]chat.Message{{Role: "system", Content: strings.TrimSpace(llmreference.ProtocolPrompt)}}, messages...)
messages = append([]chat.Message{{Role: "system", Content: strings.TrimSpace(llmreference.ProtocolPrompt(citationsEnabled))}}, messages...)
}
return refs.EncodeMessages(messages), refs
}
@@ -1184,7 +1185,7 @@ func (s *sessionService) consumeFallbackStream(
// `references` SSE event. Must run before CHAT_COMPLETION_STREAM so citations
// arrive while the connection is still open (complete closes the stream).
func emitKnowledgeReferencesEvent(ctx context.Context, chatManage *types.ChatManage) {
if chatManage == nil || chatManage.EventBus == nil || len(chatManage.MergeResult) == 0 {
if chatManage == nil || !chatManage.CitationsEnabled() || chatManage.EventBus == nil || len(chatManage.MergeResult) == 0 {
return
}
logger.Infof(ctx, "Emitting references event with %d results (pre-answer)", len(chatManage.MergeResult))
@@ -1205,6 +1206,9 @@ func (s *sessionService) emitFallbackAnswer(ctx context.Context, chatManage *typ
if chatManage.EventBus == nil {
return
}
if !chatManage.CitationsEnabled() {
content = llmreference.NewRegistry(false).ExpandText(content)
}
fallbackID := generateEventID("fallback")
if err := chatManage.EventBus.Emit(ctx, types.Event{
@@ -52,6 +52,31 @@ type stubModelService struct {
modelsByID map[string]*types.Model
}
func TestEmitKnowledgeReferencesEventHonorsCitationSetting(t *testing.T) {
bus := event.NewEventBus()
emitted := 0
bus.On(event.EventAgentReferences, func(context.Context, event.Event) error {
emitted++
return nil
})
disabled := false
cm := &types.ChatManage{
PipelineRequest: types.PipelineRequest{CitationEnabled: &disabled},
PipelineState: types.PipelineState{
MergeResult: []*types.SearchResult{{ID: "chunk-1"}},
},
PipelineContext: types.PipelineContext{EventBus: bus.AsEventBusInterface()},
}
emitKnowledgeReferencesEvent(context.Background(), cm)
require.Zero(t, emitted)
enabled := true
cm.CitationEnabled = &enabled
emitKnowledgeReferencesEvent(context.Background(), cm)
require.Equal(t, 1, emitted)
}
func (s *stubModelService) CreateModel(context.Context, *types.Model) error {
return nil
}
@@ -154,7 +154,8 @@ func (s *sessionService) resolveRetrievalTenantID(
// applyAgentOverridesToChatManage applies custom agent configuration overrides
// to a ChatManage object that was initialized with system defaults.
// This covers: system prompt, context template, temperature, max tokens, thinking,
// retrieval thresholds, rewrite settings, fallback settings, FAQ strategy, and history turns.
// citation output, retrieval thresholds, rewrite settings, fallback settings, FAQ strategy,
// and history turns.
func (s *sessionService) applyAgentOverridesToChatManage(
ctx context.Context,
customAgent *types.CustomAgent,
@@ -188,6 +189,7 @@ func (s *sessionService) applyAgentOverridesToChatManage(
// EnsureDefaults pins nil to explicit false so thinking_control wire formats
// always receive a value.
cm.SummaryConfig.Thinking = customAgent.Config.Thinking
cm.CitationEnabled = customAgent.Config.CitationEnabled
if customAgent.Config.Thinking != nil {
logger.Infof(ctx, "Using custom agent's thinking: %v", *customAgent.Config.Thinking)
} else {