feat: add AnalyzeConversation tool and related graph for analyzing conversation risks and summaries
This commit is contained in:
mlogclub
@@ -0,0 +1,236 @@
|
||||
package graphs
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"strings"
|
||||
|
||||
"cs-agent/internal/models"
|
||||
"cs-agent/internal/services"
|
||||
)
|
||||
|
||||
type AnalyzeConversationInput struct {
|
||||
Goal string `json:"goal"`
|
||||
ObservedIssue string `json:"observedIssue"`
|
||||
NeedTicket bool `json:"needTicket"`
|
||||
NeedHumanHandoff bool `json:"needHumanHandoff"`
|
||||
NeedQualityCheck bool `json:"needQualityCheck"`
|
||||
AdditionalContext string `json:"additionalContext"`
|
||||
}
|
||||
|
||||
type AnalyzeConversationResult struct {
|
||||
Summary string `json:"summary"`
|
||||
UserIntent string `json:"userIntent"`
|
||||
RiskLevel string `json:"riskLevel"`
|
||||
RiskSignals []string `json:"riskSignals,omitempty"`
|
||||
RecommendedNextAction string `json:"recommendedNextAction"`
|
||||
RecommendedQuestions []string `json:"recommendedQuestions,omitempty"`
|
||||
ConversationFacts []string `json:"conversationFacts,omitempty"`
|
||||
}
|
||||
|
||||
type AnalyzeConversationGraph struct {
|
||||
conversation *models.Conversation
|
||||
}
|
||||
|
||||
func NewAnalyzeConversationGraph(conversation *models.Conversation) *AnalyzeConversationGraph {
|
||||
return &AnalyzeConversationGraph{conversation: conversation}
|
||||
}
|
||||
|
||||
func (g *AnalyzeConversationGraph) Run(_ context.Context, argumentsInJSON string) (string, error) {
|
||||
if g == nil || g.conversation == nil {
|
||||
return "", fmt.Errorf("analyze conversation graph not initialized")
|
||||
}
|
||||
input, err := g.parseInput(argumentsInJSON)
|
||||
if err != nil {
|
||||
return "", err
|
||||
}
|
||||
messages, _, _ := services.MessageService.FindByConversationIDCursor(g.conversation.ID, 0, 8, "", "")
|
||||
result := buildAnalyzeConversationResult(g.conversation, messages, input)
|
||||
buf, err := json.Marshal(result)
|
||||
if err != nil {
|
||||
return "", err
|
||||
}
|
||||
return string(buf), nil
|
||||
}
|
||||
|
||||
func (g *AnalyzeConversationGraph) parseInput(argumentsInJSON string) (AnalyzeConversationInput, error) {
|
||||
var input AnalyzeConversationInput
|
||||
if strings.TrimSpace(argumentsInJSON) == "" {
|
||||
return input, nil
|
||||
}
|
||||
if err := json.Unmarshal([]byte(argumentsInJSON), &input); err != nil {
|
||||
return input, fmt.Errorf("invalid analyze conversation arguments: %w", err)
|
||||
}
|
||||
input.Goal = strings.TrimSpace(input.Goal)
|
||||
input.ObservedIssue = strings.TrimSpace(input.ObservedIssue)
|
||||
input.AdditionalContext = strings.TrimSpace(input.AdditionalContext)
|
||||
return input, nil
|
||||
}
|
||||
|
||||
func buildAnalyzeConversationResult(conversation *models.Conversation, messages []models.Message, input AnalyzeConversationInput) AnalyzeConversationResult {
|
||||
joined := strings.ToLower(buildConversationCorpus(conversation, messages, input))
|
||||
signals := collectRiskSignals(joined, input)
|
||||
intent := detectUserIntent(joined, input)
|
||||
recommendedAction := recommendNextAction(intent, signals, input)
|
||||
result := AnalyzeConversationResult{
|
||||
Summary: buildConversationSummary(conversation, messages, input),
|
||||
UserIntent: intent,
|
||||
RiskLevel: deriveRiskLevel(signals),
|
||||
RiskSignals: signals,
|
||||
RecommendedNextAction: recommendedAction,
|
||||
RecommendedQuestions: recommendQuestions(intent, signals, input),
|
||||
ConversationFacts: buildConversationAnalysisFacts(conversation, messages),
|
||||
}
|
||||
return result
|
||||
}
|
||||
|
||||
func buildConversationSummary(conversation *models.Conversation, messages []models.Message, input AnalyzeConversationInput) string {
|
||||
parts := make([]string, 0, 4)
|
||||
if conversation != nil && strings.TrimSpace(conversation.Subject) != "" {
|
||||
parts = append(parts, "会话主题："+strings.TrimSpace(conversation.Subject))
|
||||
}
|
||||
if input.ObservedIssue != "" {
|
||||
parts = append(parts, "当前问题："+input.ObservedIssue)
|
||||
} else if conversation != nil && strings.TrimSpace(conversation.LastMessageSummary) != "" {
|
||||
parts = append(parts, "当前问题："+strings.TrimSpace(conversation.LastMessageSummary))
|
||||
}
|
||||
if digest := buildRecentMessageDigest(messages); digest != "" {
|
||||
parts = append(parts, "最近对话："+digest)
|
||||
}
|
||||
if input.AdditionalContext != "" {
|
||||
parts = append(parts, "补充信息："+input.AdditionalContext)
|
||||
}
|
||||
return strings.TrimSpace(strings.Join(parts, "\n"))
|
||||
}
|
||||
|
||||
func buildConversationCorpus(conversation *models.Conversation, messages []models.Message, input AnalyzeConversationInput) string {
|
||||
parts := make([]string, 0, len(messages)+4)
|
||||
if conversation != nil {
|
||||
parts = append(parts, strings.TrimSpace(conversation.Subject))
|
||||
parts = append(parts, strings.TrimSpace(conversation.LastMessageSummary))
|
||||
}
|
||||
parts = append(parts, input.Goal, input.ObservedIssue, input.AdditionalContext)
|
||||
for i := range messages {
|
||||
parts = append(parts, strings.TrimSpace(messages[i].Content))
|
||||
}
|
||||
return strings.Join(parts, "\n")
|
||||
}
|
||||
|
||||
func collectRiskSignals(joined string, input AnalyzeConversationInput) []string {
|
||||
signals := make([]string, 0, 6)
|
||||
add := func(signal string) {
|
||||
for _, item := range signals {
|
||||
if item == signal {
|
||||
return
|
||||
}
|
||||
}
|
||||
signals = append(signals, signal)
|
||||
}
|
||||
if containsAny(joined, "投诉", "举报", "差评", "曝光", "媒体", "起诉", "律师", "12315") {
|
||||
add("complaint_escalation")
|
||||
}
|
||||
if containsAny(joined, "退款", "赔偿", "损失", "扣款", "重复扣费", "金额") {
|
||||
add("financial_risk")
|
||||
}
|
||||
if containsAny(joined, "生气", "愤怒", "垃圾", "太差", "一直没人", "再不处理") {
|
||||
add("negative_sentiment")
|
||||
}
|
||||
if containsAny(joined, "人工", "转人工", "真人", "客服") || input.NeedHumanHandoff {
|
||||
add("handoff_requested")
|
||||
}
|
||||
if containsAny(joined, "工单", "报障", "售后", "登记", "记录问题") || input.NeedTicket {
|
||||
add("ticket_expected")
|
||||
}
|
||||
if input.NeedQualityCheck {
|
||||
add("quality_review_requested")
|
||||
}
|
||||
return signals
|
||||
}
|
||||
|
||||
func detectUserIntent(joined string, input AnalyzeConversationInput) string {
|
||||
switch {
|
||||
case input.NeedHumanHandoff || containsAny(joined, "人工", "转人工", "真人"):
|
||||
return "handoff_request"
|
||||
case input.NeedTicket || containsAny(joined, "工单", "报障", "售后", "登记问题"):
|
||||
return "ticket_request"
|
||||
case containsAny(joined, "投诉", "举报", "差评", "赔偿"):
|
||||
return "complaint"
|
||||
default:
|
||||
return "general_support"
|
||||
}
|
||||
}
|
||||
|
||||
func deriveRiskLevel(signals []string) string {
|
||||
if len(signals) == 0 {
|
||||
return "low"
|
||||
}
|
||||
if containsSignal(signals, "complaint_escalation") || containsSignal(signals, "financial_risk") {
|
||||
return "high"
|
||||
}
|
||||
if containsSignal(signals, "handoff_requested") || containsSignal(signals, "negative_sentiment") {
|
||||
return "medium"
|
||||
}
|
||||
return "low"
|
||||
}
|
||||
|
||||
func recommendNextAction(intent string, signals []string, input AnalyzeConversationInput) string {
|
||||
switch {
|
||||
case input.NeedQualityCheck:
|
||||
return "quality_review"
|
||||
case containsSignal(signals, "handoff_requested") || intent == "handoff_request":
|
||||
return "handoff_to_human"
|
||||
case containsSignal(signals, "ticket_expected") || intent == "ticket_request":
|
||||
return "prepare_ticket"
|
||||
case containsSignal(signals, "complaint_escalation"):
|
||||
return "handoff_to_human"
|
||||
default:
|
||||
return "continue_answering"
|
||||
}
|
||||
}
|
||||
|
||||
func recommendQuestions(intent string, signals []string, input AnalyzeConversationInput) []string {
|
||||
questions := make([]string, 0, 3)
|
||||
if containsSignal(signals, "ticket_expected") && strings.TrimSpace(input.ObservedIssue) == "" {
|
||||
questions = append(questions, "请进一步确认用户遇到的具体问题现象、报错信息和期望处理结果。")
|
||||
}
|
||||
if containsSignal(signals, "handoff_requested") {
|
||||
questions = append(questions, "请确认用户是否明确要求人工客服，以及当前问题为何需要人工继续处理。")
|
||||
}
|
||||
if intent == "complaint" {
|
||||
questions = append(questions, "请确认投诉点、影响范围和用户当前最希望解决的事项。")
|
||||
}
|
||||
return questions
|
||||
}
|
||||
|
||||
func buildConversationAnalysisFacts(conversation *models.Conversation, messages []models.Message) []string {
|
||||
facts := make([]string, 0, 4)
|
||||
if conversation != nil && strings.TrimSpace(conversation.Subject) != "" {
|
||||
facts = append(facts, "会话主题："+strings.TrimSpace(conversation.Subject))
|
||||
}
|
||||
if conversation != nil && strings.TrimSpace(conversation.LastMessageSummary) != "" {
|
||||
facts = append(facts, "最近摘要："+strings.TrimSpace(conversation.LastMessageSummary))
|
||||
}
|
||||
if digest := buildRecentMessageDigest(messages); digest != "" {
|
||||
facts = append(facts, "最近消息："+digest)
|
||||
}
|
||||
return facts
|
||||
}
|
||||
|
||||
func containsAny(value string, keywords ...string) bool {
|
||||
for _, keyword := range keywords {
|
||||
if keyword != "" && strings.Contains(value, strings.ToLower(keyword)) {
|
||||
return true
|
||||
}
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
func containsSignal(signals []string, target string) bool {
|
||||
for _, item := range signals {
|
||||
if item == target {
|
||||
return true
|
||||
}
|
||||
}
|
||||
return false
|
||||
}
|
||||
@@ -0,0 +1,53 @@
|
||||
package graphs
|
||||
|
||||
import (
|
||||
"testing"
|
||||
|
||||
"cs-agent/internal/models"
|
||||
"cs-agent/internal/pkg/enums"
|
||||
)
|
||||
|
||||
func TestBuildAnalyzeConversationResult_RecommendsHandoffForComplaint(t *testing.T) {
|
||||
conversation := &models.Conversation{
|
||||
Subject: "用户投诉扣费异常",
|
||||
LastMessageSummary: "用户反馈被重复扣费，并要求人工处理",
|
||||
}
|
||||
messages := []models.Message{
|
||||
{SenderType: enums.IMSenderTypeCustomer, Content: "你们重复扣费了，我要投诉并转人工"},
|
||||
}
|
||||
|
||||
got := buildAnalyzeConversationResult(conversation, messages, AnalyzeConversationInput{
|
||||
NeedHumanHandoff: true,
|
||||
})
|
||||
|
||||
if got.UserIntent != "handoff_request" {
|
||||
t.Fatalf("expected handoff_request, got %q", got.UserIntent)
|
||||
}
|
||||
if got.RiskLevel != "high" {
|
||||
t.Fatalf("expected high risk, got %q", got.RiskLevel)
|
||||
}
|
||||
if got.RecommendedNextAction != "handoff_to_human" {
|
||||
t.Fatalf("expected handoff_to_human, got %q", got.RecommendedNextAction)
|
||||
}
|
||||
}
|
||||
|
||||
func TestBuildAnalyzeConversationResult_RecommendsPrepareTicket(t *testing.T) {
|
||||
conversation := &models.Conversation{
|
||||
Subject: "订单无法支付",
|
||||
LastMessageSummary: "用户要求登记问题并尽快处理",
|
||||
}
|
||||
messages := []models.Message{
|
||||
{SenderType: enums.IMSenderTypeCustomer, Content: "麻烦帮我建个工单，订单一直支付失败"},
|
||||
}
|
||||
|
||||
got := buildAnalyzeConversationResult(conversation, messages, AnalyzeConversationInput{
|
||||
NeedTicket: true,
|
||||
})
|
||||
|
||||
if got.UserIntent != "ticket_request" {
|
||||
t.Fatalf("expected ticket_request, got %q", got.UserIntent)
|
||||
}
|
||||
if got.RecommendedNextAction != "prepare_ticket" {
|
||||
t.Fatalf("expected prepare_ticket, got %q", got.RecommendedNextAction)
|
||||
}
|
||||
}
|
||||
@@ -109,16 +109,20 @@ func (f *AgentFactory) BuildCustomerServiceAgent(ctx context.Context, input Buil
|
||||
continue
|
||||
}
|
||||
serverCode, toolName := "", ""
|
||||
if toolCode == toolx.BuiltinToolSearchToolCode {
|
||||
switch toolCode {
|
||||
case toolx.BuiltinToolSearchToolCode:
|
||||
serverCode = toolx.BuiltinToolCatalogServerCode
|
||||
toolName = toolx.BuiltinToolSearchToolName
|
||||
} else if toolCode == toolx.GraphPrepareTicketDraftToolCode {
|
||||
case toolx.GraphAnalyzeConversationToolCode:
|
||||
serverCode = toolx.GraphToolCatalogServerCode
|
||||
toolName = toolx.GraphAnalyzeConversationToolName
|
||||
case toolx.GraphPrepareTicketDraftToolCode:
|
||||
serverCode = toolx.GraphToolCatalogServerCode
|
||||
toolName = toolx.GraphPrepareTicketDraftToolName
|
||||
} else if toolCode == toolx.GraphCreateTicketConfirmToolCode {
|
||||
case toolx.GraphCreateTicketConfirmToolCode:
|
||||
serverCode = toolx.GraphToolCatalogServerCode
|
||||
toolName = toolx.GraphCreateTicketConfirmToolName
|
||||
} else if toolCode == toolx.GraphHandoffConversationToolCode {
|
||||
case toolx.GraphHandoffConversationToolCode:
|
||||
serverCode = toolx.GraphToolCatalogServerCode
|
||||
toolName = toolx.GraphHandoffConversationToolName
|
||||
}
|
||||
@@ -222,6 +226,15 @@ func assembleAgentInstruction(aiAgent *models.AIAgent, selectedSkill *models.Ski
|
||||
2. 如果工具返回 ready=false，优先根据 missingFields 和 followUpQuestions 继续追问，不要直接创建工单。
|
||||
3. 如果工具返回 ready=true，再结合结果考虑调用 create_ticket_with_confirmation。
|
||||
4. 该工具用于“整理草稿”，不代表已经创建工单。
|
||||
`))
|
||||
}
|
||||
if hasToolCode(extraToolCodes, toolx.GraphAnalyzeConversationToolCode) {
|
||||
appendixParts = append(appendixParts, strings.TrimSpace(`
|
||||
当对话可能涉及投诉升级、退款赔偿、明显负面情绪、是否要建单、是否要转人工等复杂判断时，优先调用 analyze_conversation 这个 Graph Tool，并遵守以下规则：
|
||||
1. 该工具用于输出结构化摘要、风险信号和下一步建议，不代表实际已经建单或转人工。
|
||||
2. 如果工具建议为 handoff_to_human，应先确认是否满足转人工条件，再考虑调用 handoff_to_human。
|
||||
3. 如果工具建议为 prepare_ticket，应优先调用 prepare_ticket_draft 或继续补充信息，而不是直接建单。
|
||||
4. 如果工具建议为 continue_answering，优先继续澄清和解答，不要过早升级动作。
|
||||
`))
|
||||
}
|
||||
if hasToolCode(extraToolCodes, toolx.GraphCreateTicketConfirmToolCode) {
|
||||
|
||||
@@ -59,6 +59,14 @@ func isAllowedToolCode(toolCode string, allowedToolCodes map[string]struct{}) bo
|
||||
if isAlwaysAllowedToolCode(toolCode) {
|
||||
return true
|
||||
}
|
||||
if strings.TrimSpace(toolCode) == toolx.GraphAnalyzeConversationToolCode {
|
||||
if _, ok := allowedToolCodes[toolx.GraphCreateTicketConfirmToolCode]; ok {
|
||||
return true
|
||||
}
|
||||
if _, ok := allowedToolCodes[toolx.GraphHandoffConversationToolCode]; ok {
|
||||
return true
|
||||
}
|
||||
}
|
||||
if strings.TrimSpace(toolCode) == toolx.GraphPrepareTicketDraftToolCode {
|
||||
_, ok := allowedToolCodes[toolx.GraphCreateTicketConfirmToolCode]
|
||||
return ok
|
||||
|
||||
@@ -19,6 +19,7 @@ func newService() *service {
|
||||
return &service{
|
||||
runtime: engine.NewService(),
|
||||
registry: registry.NewRegistry(
|
||||
tools.NewAnalyzeConversationTool(),
|
||||
tools.NewPrepareTicketDraftTool(),
|
||||
tools.NewCreateTicketGraphTool(),
|
||||
tools.NewHandoffGraphTool(),
|
||||
|
||||
@@ -0,0 +1,114 @@
|
||||
package tools
|
||||
|
||||
import (
|
||||
"context"
|
||||
"fmt"
|
||||
|
||||
"cs-agent/internal/ai/runtime/graphs"
|
||||
"cs-agent/internal/ai/runtime/registry"
|
||||
"cs-agent/internal/models"
|
||||
"cs-agent/internal/pkg/toolx"
|
||||
|
||||
einotool "github.com/cloudwego/eino/components/tool"
|
||||
"github.com/cloudwego/eino/schema"
|
||||
einojsonschema "github.com/eino-contrib/jsonschema"
|
||||
orderedmap "github.com/wk8/go-ordered-map/v2"
|
||||
)
|
||||
|
||||
const (
|
||||
AnalyzeConversationToolCode = toolx.GraphAnalyzeConversationToolCode
|
||||
AnalyzeConversationToolName = toolx.GraphAnalyzeConversationToolName
|
||||
)
|
||||
|
||||
type AnalyzeConversationTool struct {
|
||||
conversation *models.Conversation
|
||||
}
|
||||
|
||||
func NewAnalyzeConversationTool() *AnalyzeConversationTool {
|
||||
return &AnalyzeConversationTool{}
|
||||
}
|
||||
|
||||
func (t *AnalyzeConversationTool) Name() string {
|
||||
return AnalyzeConversationToolName
|
||||
}
|
||||
|
||||
func (t *AnalyzeConversationTool) Code() string {
|
||||
return AnalyzeConversationToolCode
|
||||
}
|
||||
|
||||
func (t *AnalyzeConversationTool) Enabled(ctx registry.Context) bool {
|
||||
return ctx.Conversation != nil
|
||||
}
|
||||
|
||||
func (t *AnalyzeConversationTool) Build(ctx registry.Context) (einotool.BaseTool, error) {
|
||||
if !t.Enabled(ctx) {
|
||||
return nil, nil
|
||||
}
|
||||
return &AnalyzeConversationTool{conversation: ctx.Conversation}, nil
|
||||
}
|
||||
|
||||
func (t *AnalyzeConversationTool) Info(ctx context.Context) (*schema.ToolInfo, error) {
|
||||
return &schema.ToolInfo{
|
||||
Name: AnalyzeConversationToolName,
|
||||
Desc: "Graph Tool。用于整理当前对话摘要、识别投诉/资金/情绪等风险信号，并给出继续解答、建单或转人工的建议。",
|
||||
ParamsOneOf: schema.NewParamsOneOfByJSONSchema(&einojsonschema.Schema{
|
||||
Version: einojsonschema.Version,
|
||||
Type: "object",
|
||||
Properties: orderedmap.New[string, *einojsonschema.Schema](orderedmap.WithInitialData(
|
||||
orderedmap.Pair[string, *einojsonschema.Schema]{
|
||||
Key: "goal",
|
||||
Value: &einojsonschema.Schema{
|
||||
Type: "string",
|
||||
Description: "当前分析目标，例如判断是否需要转人工、是否需要建单、是否需要做风险质检。",
|
||||
},
|
||||
},
|
||||
orderedmap.Pair[string, *einojsonschema.Schema]{
|
||||
Key: "observedIssue",
|
||||
Value: &einojsonschema.Schema{
|
||||
Type: "string",
|
||||
Description: "当前观察到的主要问题或诉求。",
|
||||
},
|
||||
},
|
||||
orderedmap.Pair[string, *einojsonschema.Schema]{
|
||||
Key: "needTicket",
|
||||
Value: &einojsonschema.Schema{
|
||||
Type: "boolean",
|
||||
Description: "是否重点评估建单必要性。",
|
||||
},
|
||||
},
|
||||
orderedmap.Pair[string, *einojsonschema.Schema]{
|
||||
Key: "needHumanHandoff",
|
||||
Value: &einojsonschema.Schema{
|
||||
Type: "boolean",
|
||||
Description: "是否重点评估转人工必要性。",
|
||||
},
|
||||
},
|
||||
orderedmap.Pair[string, *einojsonschema.Schema]{
|
||||
Key: "needQualityCheck",
|
||||
Value: &einojsonschema.Schema{
|
||||
Type: "boolean",
|
||||
Description: "是否重点做风险/质检分析。",
|
||||
},
|
||||
},
|
||||
orderedmap.Pair[string, *einojsonschema.Schema]{
|
||||
Key: "additionalContext",
|
||||
Value: &einojsonschema.Schema{
|
||||
Type: "string",
|
||||
Description: "补充上下文，例如你已发现的争议点、投诉点或业务限制。",
|
||||
},
|
||||
},
|
||||
)),
|
||||
}),
|
||||
Extra: map[string]any{
|
||||
"toolCode": AnalyzeConversationToolCode,
|
||||
"sourceType": "graph",
|
||||
},
|
||||
}, nil
|
||||
}
|
||||
|
||||
func (t *AnalyzeConversationTool) InvokableRun(ctx context.Context, argumentsInJSON string, opts ...einotool.Option) (string, error) {
|
||||
if t == nil || t.conversation == nil {
|
||||
return "", fmt.Errorf("analyze conversation tool not initialized")
|
||||
}
|
||||
return graphs.NewAnalyzeConversationGraph(t.conversation).Run(ctx, argumentsInJSON)
|
||||
}
|
||||
@@ -11,6 +11,10 @@ const (
|
||||
BuiltinSkillToolTitle = "加载专项技能说明"
|
||||
BuiltinSkillToolDescription = "用于加载当前命中的专项技能说明文档。仅在本轮已命中 Skill 时可用，适合将专项处理规则按需注入上下文。"
|
||||
GraphToolCatalogServerCode = "graph"
|
||||
GraphAnalyzeConversationToolCode = "graph/analyze_conversation"
|
||||
GraphAnalyzeConversationToolName = "analyze_conversation"
|
||||
GraphAnalyzeConversationToolTitle = "分析对话风险与摘要"
|
||||
GraphAnalyzeConversationToolDescription = "Graph Tool。用于整理当前对话摘要、识别风险信号，并给出继续解答、建单或转人工的建议。"
|
||||
GraphPrepareTicketDraftToolCode = "graph/prepare_ticket_draft"
|
||||
GraphPrepareTicketDraftToolName = "prepare_ticket_draft"
|
||||
GraphPrepareTicketDraftToolTitle = "整理工单草稿"
|
||||
|
||||
Reference in New Issue
Block a user