wlw/ai-agent
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: refactor tool definitions to use structured ToolSpec and update related references

Browse Source
This commit is contained in:
mlogclub
2026-04-12 22:27:09 +08:00
parent 54f5a684c3
commit 11252d31da
16 changed files with 280 additions and 204 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs
+1 -1
Submodule docs updated: 86165abf47...18dc676a5f
internal/ai/runtime/internal/engine/service.go
+6 -6
View File
@@ -84,12 +84,12 @@ func (s *Service) Run(ctx context.Context, req Request) (*Summary, error) {
toolDefsByModelName[item.ModelName] = item.ToolCode
}
if len(filteredToolDefs) > 0 {
summary.ToolCodes = appendIfMissing(summary.ToolCodes, toolx.BuiltinToolSearchToolCode)
toolDefsByModelName[toolx.BuiltinToolSearchToolName] = toolx.BuiltinToolSearchToolCode
summary.ToolCodes = appendIfMissing(summary.ToolCodes, toolx.BuiltinToolSearch.Code)
toolDefsByModelName[toolx.BuiltinToolSearch.Name] = toolx.BuiltinToolSearch.Code
}
if req.SelectedSkill != nil {
summary.ToolCodes = appendIfMissing(summary.ToolCodes, toolx.BuiltinSkillToolCode)
toolDefsByModelName[toolx.BuiltinSkillToolName] = toolx.BuiltinSkillToolCode
summary.ToolCodes = appendIfMissing(summary.ToolCodes, toolx.BuiltinSkill.Code)
toolDefsByModelName[toolx.BuiltinSkill.Name] = toolx.BuiltinSkill.Code
}
for modelName, toolCode := range toolSetStaticToolCodes(req.ToolSet) {
toolCode = strings.TrimSpace(toolCode)
@@ -236,8 +236,8 @@ func (s *Service) Resume(ctx context.Context, req ResumeRequest) (*Summary, erro
toolDefsByModelName[item.ModelName] = item.ToolCode
}
if len(toolDefs) > 0 {
summary.ToolCodes = appendIfMissing(summary.ToolCodes, toolx.BuiltinToolSearchToolCode)
toolDefsByModelName[toolx.BuiltinToolSearchToolName] = toolx.BuiltinToolSearchToolCode
summary.ToolCodes = appendIfMissing(summary.ToolCodes, toolx.BuiltinToolSearch.Code)
toolDefsByModelName[toolx.BuiltinToolSearch.Name] = toolx.BuiltinToolSearch.Code
}
for modelName, toolCode := range toolSetStaticToolCodes(req.ToolSet) {
toolCode = strings.TrimSpace(toolCode)
internal/ai/runtime/internal/impl/callbacks/agent_trace_handler.go
+14 -14
View File
@@ -64,7 +64,7 @@ func (h *RuntimeTraceHandler) WrapInvokableToolCall(_ context.Context, endpoint
item.ErrorMessage = err.Error()
}
h.collector.AddToolItem(item)
if metadata, ok := h.resolveToolMetadata(item.ToolName); ok && strings.TrimSpace(metadata.SourceType) == toolx.GraphToolCatalogServerCode {
if metadata, ok := h.resolveToolMetadata(item.ToolName); ok && strings.TrimSpace(metadata.SourceType) == toolx.GraphCreateTicketConfirm.ServerCode {
recommendedAction, riskLevel, ticketDraftReady := parseGraphToolOutcome(item.ToolCode, result)
h.collector.AddGraphToolItem(GraphToolTraceItem{
ToolCode: item.ToolCode,
@@ -82,7 +82,7 @@ func (h *RuntimeTraceHandler) WrapInvokableToolCall(_ context.Context, endpoint
TicketDraftReady: ticketDraftReady,
})
}
if metadata, ok := h.resolveToolMetadata(item.ToolName); ok && strings.TrimSpace(metadata.ToolCode) == toolx.BuiltinToolSearchToolCode {
if metadata, ok := h.resolveToolMetadata(item.ToolName); ok && strings.TrimSpace(metadata.ToolCode) == toolx.BuiltinToolSearch.Code {
h.collector.AddToolSearchItem(h.buildToolSearchTraceItem(argumentsInJSON, result, err))
}
return result, err
@@ -99,9 +99,9 @@ func parseGraphToolOutcome(toolCode string, result string) (recommendedAction, r
return "", "", false
}
switch toolCode {
case toolx.GraphAnalyzeConversationToolCode:
case toolx.GraphAnalyzeConversation.Code:
return strings.TrimSpace(readToolSearchString(payload, "recommendedNextAction")), strings.TrimSpace(readToolSearchString(payload, "riskLevel")), false
case toolx.GraphTriageServiceRequestToolCode:
case toolx.GraphTriageServiceRequest.Code:
recommendedAction = strings.TrimSpace(readToolSearchString(payload, "recommendedAction"))
if analysis, ok := payload["analysis"].(map[string]any); ok {
riskLevel = strings.TrimSpace(readToolSearchString(analysis, "riskLevel"))
@@ -124,20 +124,20 @@ func (h *RuntimeTraceHandler) resolveToolMetadata(modelToolName string) (ToolMet
if modelToolName == "" {
return ToolMetadata{}, false
}
if modelToolName == toolx.BuiltinToolSearchToolName {
if modelToolName == toolx.BuiltinToolSearch.Name {
return ToolMetadata{
ToolCode: toolx.BuiltinToolSearchToolCode,
ServerCode: toolx.BuiltinToolCatalogServerCode,
ToolName: toolx.BuiltinToolSearchToolName,
SourceType: toolx.BuiltinToolCatalogServerCode,
ToolCode: toolx.BuiltinToolSearch.Code,
ServerCode: toolx.BuiltinToolSearch.ServerCode,
ToolName: toolx.BuiltinToolSearch.Name,
SourceType: toolx.BuiltinToolSearch.SourceType,
}, true
}
if modelToolName == toolx.BuiltinSkillToolName {
if modelToolName == toolx.BuiltinSkill.Name {
return ToolMetadata{
ToolCode: toolx.BuiltinSkillToolCode,
ServerCode: toolx.BuiltinToolCatalogServerCode,
ToolName: toolx.BuiltinSkillToolName,
SourceType: toolx.BuiltinToolCatalogServerCode,
ToolCode: toolx.BuiltinSkill.Code,
ServerCode: toolx.BuiltinSkill.ServerCode,
ToolName: toolx.BuiltinSkill.Name,
SourceType: toolx.BuiltinSkill.SourceType,
}, true
}
metadata, ok := h.toolMetadataBy[modelToolName]
internal/ai/runtime/internal/impl/factory/agent_factory.go
+15 -51
View File
@@ -108,42 +108,22 @@ func (f *AgentFactory) BuildCustomerServiceAgent(ctx context.Context, input Buil
if modelName == "" || toolCode == "" {
continue
}
serverCode, toolName := "", ""
switch toolCode {
case toolx.BuiltinToolSearchToolCode:
serverCode = toolx.BuiltinToolCatalogServerCode
toolName = toolx.BuiltinToolSearchToolName
case toolx.GraphTriageServiceRequestToolCode:
serverCode = toolx.GraphToolCatalogServerCode
toolName = toolx.GraphTriageServiceRequestToolName
case toolx.GraphAnalyzeConversationToolCode:
serverCode = toolx.GraphToolCatalogServerCode
toolName = toolx.GraphAnalyzeConversationToolName
case toolx.GraphPrepareTicketDraftToolCode:
serverCode = toolx.GraphToolCatalogServerCode
toolName = toolx.GraphPrepareTicketDraftToolName
case toolx.GraphCreateTicketConfirmToolCode:
serverCode = toolx.GraphToolCatalogServerCode
toolName = toolx.GraphCreateTicketConfirmToolName
case toolx.GraphHandoffConversationToolCode:
serverCode = toolx.GraphToolCatalogServerCode
toolName = toolx.GraphHandoffConversationToolName
}
serverCode, toolName, _ := toolx.GetRegisteredToolIdentity(toolCode)
toolMetadataBy[modelName] = einocallbacks.ToolMetadata{
ToolCode: toolCode,
ServerCode: serverCode,
ToolName: toolName,
SourceType: resolveToolSourceType(toolCode),
SourceType: toolx.ResolveToolSourceType(toolCode),
}
}
if input.SelectedSkill != nil {
toolMetadataBy[toolx.BuiltinSkillToolName] = einocallbacks.ToolMetadata{
ToolCode: toolx.BuiltinSkillToolCode,
ServerCode: toolx.BuiltinToolCatalogServerCode,
ToolName: toolx.BuiltinSkillToolName,
SourceType: toolx.BuiltinToolCatalogServerCode,
toolMetadataBy[toolx.BuiltinSkill.Name] = einocallbacks.ToolMetadata{
ToolCode: toolx.BuiltinSkill.Code,
ServerCode: toolx.BuiltinSkill.ServerCode,
ToolName: toolx.BuiltinSkill.Name,
SourceType: toolx.BuiltinSkill.SourceType,
}
input.Collector.SetSkillMiddleware(true, toolx.BuiltinSkillToolName)
input.Collector.SetSkillMiddleware(true, toolx.BuiltinSkill.Name)
}
handlers = append(handlers, einocallbacks.NewRuntimeTraceHandler(input.Collector, toolMetadataBy))
}
@@ -181,7 +161,7 @@ func (f *AgentFactory) buildSelectedSkillMiddleware(ctx context.Context, selecte
if err != nil {
return nil, err
}
toolName := toolx.BuiltinSkillToolName
toolName := toolx.BuiltinSkill.Name
return einoskill.NewMiddleware(ctx, &einoskill.Config{
Backend: backend,
SkillToolName: &toolName,
@@ -189,22 +169,6 @@ func (f *AgentFactory) buildSelectedSkillMiddleware(ctx context.Context, selecte
})
}
func resolveToolSourceType(toolCode string) string {
toolCode = strings.TrimSpace(toolCode)
switch {
case toolCode == toolx.BuiltinToolSearchToolCode:
return toolx.BuiltinToolCatalogServerCode
case toolCode == toolx.BuiltinSkillToolCode:
return toolx.BuiltinToolCatalogServerCode
case strings.HasPrefix(toolCode, toolx.GraphToolCatalogServerCode+"/"):
return toolx.GraphToolCatalogServerCode
case strings.HasPrefix(toolCode, toolx.BuiltinToolCatalogServerCode+"/"):
return toolx.BuiltinToolCatalogServerCode
default:
return "mcp"
}
}
func assembleAgentInstruction(aiAgent *models.AIAgent, selectedSkill *models.SkillDefinition, toolDefinitions []einoadapter.MCPToolDefinition, extraToolCodes map[string]string) InstructionAssemblyResult {
baseInstruction := ""
if aiAgent != nil {
@@ -222,7 +186,7 @@ func assembleAgentInstruction(aiAgent *models.AIAgent, selectedSkill *models.Ski
3. 如果当前已有固定内置工具可以完成任务，优先使用固定工具，不要滥用 tool_search。
`))
}
if hasToolCode(extraToolCodes, toolx.GraphTriageServiceRequestToolCode) {
if hasToolCode(extraToolCodes, toolx.GraphTriageServiceRequest.Code) {
appendixParts = append(appendixParts, strings.TrimSpace(`
当你需要判断“继续解答 / 建单 / 转人工”这类复杂升级路径时，优先先调用 triage_service_request 这个 Graph Tool，并遵守以下规则：
1. 该工具会综合当前对话输出 recommendedAction，并在需要建单时附带 ticketDraft。
@@ -232,7 +196,7 @@ func assembleAgentInstruction(aiAgent *models.AIAgent, selectedSkill *models.Ski
5. 当升级路径不明确时，优先使用该工具，而不是直接凭主 prompt 做复杂分流判断。
`))
}
if hasToolCode(extraToolCodes, toolx.GraphPrepareTicketDraftToolCode) {
if hasToolCode(extraToolCodes, toolx.GraphPrepareTicketDraft.Code) {
appendixParts = append(appendixParts, strings.TrimSpace(`
当用户已经表达了建单、投诉、报障、售后处理等诉求，但工单标题、描述或问题整理还比较散乱时，优先调用 prepare_ticket_draft 这个 Graph Tool，并遵守以下规则：
1. 该工具用于整理工单草稿，会返回建议标题、建议描述、缺失字段和追问建议。
@@ -241,7 +205,7 @@ func assembleAgentInstruction(aiAgent *models.AIAgent, selectedSkill *models.Ski
4. 该工具用于“整理草稿”，不代表已经创建工单。
`))
}
if hasToolCode(extraToolCodes, toolx.GraphAnalyzeConversationToolCode) {
if hasToolCode(extraToolCodes, toolx.GraphAnalyzeConversation.Code) {
appendixParts = append(appendixParts, strings.TrimSpace(`
当对话可能涉及投诉升级、退款赔偿、明显负面情绪、是否要建单、是否要转人工等复杂判断时，优先调用 analyze_conversation 这个 Graph Tool，并遵守以下规则：
1. 该工具用于输出结构化摘要、风险信号和下一步建议，不代表实际已经建单或转人工。
@@ -250,7 +214,7 @@ func assembleAgentInstruction(aiAgent *models.AIAgent, selectedSkill *models.Ski
4. 如果工具建议为 continue_answering，优先继续澄清和解答，不要过早升级动作。
`))
}
if hasToolCode(extraToolCodes, toolx.GraphCreateTicketConfirmToolCode) {
if hasToolCode(extraToolCodes, toolx.GraphCreateTicketConfirm.Code) {
appendixParts = append(appendixParts, strings.TrimSpace(`
你可以在确认信息充分后调用 create_ticket_with_confirmation 这个 Graph Tool 来创建工单，但必须遵守以下规则：
1. 只有在用户明确表达希望提交工单、投诉、报障、售后处理等诉求时，才考虑调用该工具。
@@ -260,7 +224,7 @@ func assembleAgentInstruction(aiAgent *models.AIAgent, selectedSkill *models.Ski
5. 如果用户只是咨询、抱怨或泛泛表达不满，但没有明确要求建单，优先继续澄清，不要主动创建工单。
`))
}
if hasToolCode(extraToolCodes, toolx.GraphHandoffConversationToolCode) {
if hasToolCode(extraToolCodes, toolx.GraphHandoffConversation.Code) {
appendixParts = append(appendixParts, strings.TrimSpace(`
你可以在确认需要人工介入后调用 handoff_to_human 这个 Graph Tool 来转人工，但必须遵守以下规则：
1. 只有在用户明确要求人工客服，或你已经判断该问题必须由人工继续处理时，才调用该工具。
@@ -311,7 +275,7 @@ func buildSelectedSkillActivationInstruction(skill *models.SkillDefinition) stri
if desc := strings.TrimSpace(skill.Description); desc != "" {
lines = append(lines, fmt.Sprintf("- description: %s", desc))
}
lines = append(lines, "", "执行要求：", "- 本轮优先处理该技能范围内的问题。", fmt.Sprintf("- 需要专项处理细节时，优先调用 %s 工具加载该技能说明后再继续。", toolx.BuiltinSkillToolName), "- 如果关键信息不足，先向用户追问。", "- 不得调用当前技能未授权的工具。")
lines = append(lines, "", "执行要求：", "- 本轮优先处理该技能范围内的问题。", fmt.Sprintf("- 需要专项处理细节时，优先调用 %s 工具加载该技能说明后再继续。", toolx.BuiltinSkill.Name), "- 如果关键信息不足，先向用户追问。", "- 不得调用当前技能未授权的工具。")
return strings.TrimSpace(strings.Join(lines, "\n"))
}
internal/ai/runtime/registry/registry.go
+9 -9
View File
@@ -59,24 +59,24 @@ func isAllowedToolCode(toolCode string, allowedToolCodes map[string]struct{}) bo
if isAlwaysAllowedToolCode(toolCode) {
return true
}
if strings.TrimSpace(toolCode) == toolx.GraphTriageServiceRequestToolCode {
if _, ok := allowedToolCodes[toolx.GraphCreateTicketConfirmToolCode]; ok {
if strings.TrimSpace(toolCode) == toolx.GraphTriageServiceRequest.Code {
if _, ok := allowedToolCodes[toolx.GraphCreateTicketConfirm.Code]; ok {
return true
}
if _, ok := allowedToolCodes[toolx.GraphHandoffConversationToolCode]; ok {
if _, ok := allowedToolCodes[toolx.GraphHandoffConversation.Code]; ok {
return true
}
}
if strings.TrimSpace(toolCode) == toolx.GraphAnalyzeConversationToolCode {
if _, ok := allowedToolCodes[toolx.GraphCreateTicketConfirmToolCode]; ok {
if strings.TrimSpace(toolCode) == toolx.GraphAnalyzeConversation.Code {
if _, ok := allowedToolCodes[toolx.GraphCreateTicketConfirm.Code]; ok {
return true
}
if _, ok := allowedToolCodes[toolx.GraphHandoffConversationToolCode]; ok {
if _, ok := allowedToolCodes[toolx.GraphHandoffConversation.Code]; ok {
return true
}
}
if strings.TrimSpace(toolCode) == toolx.GraphPrepareTicketDraftToolCode {
_, ok := allowedToolCodes[toolx.GraphCreateTicketConfirmToolCode]
if strings.TrimSpace(toolCode) == toolx.GraphPrepareTicketDraft.Code {
_, ok := allowedToolCodes[toolx.GraphCreateTicketConfirm.Code]
return ok
}
return false
@@ -98,5 +98,5 @@ func makeAllowedToolCodeSet(input []string) map[string]struct{} {
}
func isAlwaysAllowedToolCode(toolCode string) bool {
return strings.TrimSpace(toolCode) == toolx.GraphHandoffConversationToolCode
return strings.TrimSpace(toolCode) == toolx.GraphHandoffConversation.Code
}
internal/ai/runtime/reply_service.go
+4 -4
View File
@@ -549,7 +549,7 @@ func summaryPrimaryToolCode(summary *Summary) string {
return ""
}
toolCode := firstInvokedToolCode(summary)
if toolCode != toolx.BuiltinToolSearchToolCode {
if toolCode != toolx.BuiltinToolSearch.Code {
return toolCode
}
if targetToolCode := firstToolSearchTargetToolCode(summary); targetToolCode != "" {
@@ -611,7 +611,7 @@ func firstGraphToolCode(summary *Summary) string {
func extractHandoffReason(summary *Summary) string {
trace := parseRuntimeTraceData(summary.TraceData)
for _, item := range trace.GraphTools.Items {
if strings.TrimSpace(item.ToolCode) != toolx.GraphHandoffConversationToolCode {
if strings.TrimSpace(item.ToolCode) != toolx.GraphHandoffConversation.Code {
continue
}
if len(item.Arguments) == 0 {
@@ -628,7 +628,7 @@ func graphPlanReason(summary *Summary) string {
for _, item := range trace.GraphTools.Items {
toolCode := strings.TrimSpace(item.ToolCode)
switch toolCode {
case toolx.GraphTriageServiceRequestToolCode:
case toolx.GraphTriageServiceRequest.Code:
recommendedAction := strings.TrimSpace(item.RecommendedAction)
if recommendedAction == "" {
return "graph tool triaged service request"
@@ -637,7 +637,7 @@ func graphPlanReason(summary *Summary) string {
return "graph tool triaged service request: " + recommendedAction + " with ready ticket draft"
}
return "graph tool triaged service request: " + recommendedAction
case toolx.GraphAnalyzeConversationToolCode:
case toolx.GraphAnalyzeConversation.Code:
recommendedAction := strings.TrimSpace(item.RecommendedAction)
riskLevel := strings.TrimSpace(item.RiskLevel)
switch {
internal/ai/runtime/tools/analyze_conversation_tool.go
+3 -3
View File
@@ -15,9 +15,9 @@ import (
orderedmap "github.com/wk8/go-ordered-map/v2"
)
const (
AnalyzeConversationToolCode = toolx.GraphAnalyzeConversationToolCode
AnalyzeConversationToolName = toolx.GraphAnalyzeConversationToolName
var (
AnalyzeConversationToolCode = toolx.GraphAnalyzeConversation.Code
AnalyzeConversationToolName = toolx.GraphAnalyzeConversation.Name
)
type AnalyzeConversationTool struct {
internal/ai/runtime/tools/create_ticket_confirm_tool.go
+3 -3
View File
@@ -15,9 +15,9 @@ import (
orderedmap "github.com/wk8/go-ordered-map/v2"
)
const (
CreateTicketConfirmToolCode = toolx.GraphCreateTicketConfirmToolCode
CreateTicketConfirmToolName = toolx.GraphCreateTicketConfirmToolName
var (
CreateTicketConfirmToolCode = toolx.GraphCreateTicketConfirm.Code
CreateTicketConfirmToolName = toolx.GraphCreateTicketConfirm.Name
)
type CreateTicketGraphTool struct {
internal/ai/runtime/tools/handoff_graph_tool.go
+3 -3
View File
@@ -15,9 +15,9 @@ import (
orderedmap "github.com/wk8/go-ordered-map/v2"
)
const (
HandoffConversationToolCode = toolx.GraphHandoffConversationToolCode
HandoffConversationToolName = toolx.GraphHandoffConversationToolName
var (
HandoffConversationToolCode = toolx.GraphHandoffConversation.Code
HandoffConversationToolName = toolx.GraphHandoffConversation.Name
)
type HandoffGraphTool struct {
internal/ai/runtime/tools/prepare_ticket_draft_tool.go
+3 -3
View File
@@ -15,9 +15,9 @@ import (
orderedmap "github.com/wk8/go-ordered-map/v2"
)
const (
PrepareTicketDraftToolCode = toolx.GraphPrepareTicketDraftToolCode
PrepareTicketDraftToolName = toolx.GraphPrepareTicketDraftToolName
var (
PrepareTicketDraftToolCode = toolx.GraphPrepareTicketDraft.Code
PrepareTicketDraftToolName = toolx.GraphPrepareTicketDraft.Name
)
type PrepareTicketDraftTool struct {
internal/ai/runtime/tools/tool_search_tool.go
+3 -3
View File
@@ -18,9 +18,9 @@ import (
orderedmap "github.com/wk8/go-ordered-map/v2"
)
const (
ToolSearchToolCode = toolx.BuiltinToolSearchToolCode
ToolSearchToolName = toolx.BuiltinToolSearchToolName
var (
ToolSearchToolCode = toolx.BuiltinToolSearch.Code
ToolSearchToolName = toolx.BuiltinToolSearch.Name
)
type ToolSearchTool struct {
internal/ai/runtime/tools/triage_service_request_tool.go
+3 -3
View File
@@ -15,9 +15,9 @@ import (
orderedmap "github.com/wk8/go-ordered-map/v2"
)
const (
TriageServiceRequestToolCode = toolx.GraphTriageServiceRequestToolCode
TriageServiceRequestToolName = toolx.GraphTriageServiceRequestToolName
var (
TriageServiceRequestToolCode = toolx.GraphTriageServiceRequest.Code
TriageServiceRequestToolName = toolx.GraphTriageServiceRequest.Name
)
type TriageServiceRequestTool struct {
internal/controllers/console/ai_agent_controller.go
+7 -23
View File
@@ -177,39 +177,23 @@ func buildAIAgentResponse(item *models.AIAgent) response.AIAgentResponse {
}
serverCode := strings.TrimSpace(tool.ServerCode)
toolName := strings.TrimSpace(tool.ToolName)
if toolCode == toolx.BuiltinToolSearchToolCode {
serverCode = toolx.BuiltinToolCatalogServerCode
toolName = toolx.BuiltinToolSearchToolName
} else if toolCode == toolx.GraphCreateTicketConfirmToolCode {
serverCode = toolx.GraphToolCatalogServerCode
toolName = toolx.GraphCreateTicketConfirmToolName
} else if toolCode == toolx.GraphHandoffConversationToolCode {
serverCode = toolx.GraphToolCatalogServerCode
toolName = toolx.GraphHandoffConversationToolName
if registeredServerCode, registeredToolName, ok := toolx.GetRegisteredToolIdentity(toolCode); ok {
serverCode = registeredServerCode
toolName = registeredToolName
} else if parsedServerCode, parsedToolName := toolx.SplitMCPToolCode(toolCode); parsedServerCode != "" && parsedToolName != "" {
serverCode = parsedServerCode
toolName = parsedToolName
}
title := strings.TrimSpace(tool.Title)
if title == "" {
switch toolCode {
case toolx.BuiltinToolSearchToolCode:
title = toolx.BuiltinToolSearchToolTitle
case toolx.GraphCreateTicketConfirmToolCode:
title = toolx.GraphCreateTicketConfirmToolTitle
case toolx.GraphHandoffConversationToolCode:
title = toolx.GraphHandoffConversationToolTitle
if registeredTitle := toolx.GetRegisteredToolTitle(toolCode); registeredTitle != "" {
title = registeredTitle
}
}
description := strings.TrimSpace(tool.Description)
if description == "" {
switch toolCode {
case toolx.BuiltinToolSearchToolCode:
description = toolx.BuiltinToolSearchToolDescription
case toolx.GraphCreateTicketConfirmToolCode:
description = toolx.GraphCreateTicketConfirmToolDescription
case toolx.GraphHandoffConversationToolCode:
description = toolx.GraphHandoffConversationToolDescription
if registeredDescription := toolx.GetRegisteredToolDescription(toolCode); registeredDescription != "" {
description = registeredDescription
}
}
ret.DirectTools = append(ret.DirectTools, response.AIAgentMCPToolResponse{
internal/pkg/toolx/builtin_tools.go
+167 -41
View File
@@ -1,51 +1,177 @@
package toolx
const (
BuiltinToolCatalogServerCode = "builtin"
BuiltinToolSearchToolCode = "builtin/tool_search"
BuiltinToolSearchToolName = "tool_search"
BuiltinToolSearchToolTitle = "搜索并调用动态工具"
BuiltinToolSearchToolDescription = "用于搜索当前允许使用的 MCP 工具，并在确认目标 toolCode 后动态调用该工具。适合处理长尾工具，不应替代固定内置流程工具。"
BuiltinSkillToolCode = "builtin/skill"
BuiltinSkillToolName = "skill"
BuiltinSkillToolTitle = "加载专项技能说明"
BuiltinSkillToolDescription = "用于加载当前命中的专项技能说明文档。仅在本轮已命中 Skill 时可用，适合将专项处理规则按需注入上下文。"
GraphToolCatalogServerCode = "graph"
GraphTriageServiceRequestToolCode = "graph/triage_service_request"
GraphTriageServiceRequestToolName = "triage_service_request"
GraphTriageServiceRequestToolTitle = "升级分流判断"
GraphTriageServiceRequestToolDescription = "Graph Tool。用于综合分析当前对话，判断应继续解答、整理工单草稿还是转人工，并在需要建单时一并整理工单草稿。"
GraphAnalyzeConversationToolCode = "graph/analyze_conversation"
GraphAnalyzeConversationToolName = "analyze_conversation"
GraphAnalyzeConversationToolTitle = "分析对话风险与摘要"
GraphAnalyzeConversationToolDescription = "Graph Tool。用于整理当前对话摘要、识别风险信号，并给出继续解答、建单或转人工的建议。"
GraphPrepareTicketDraftToolCode = "graph/prepare_ticket_draft"
GraphPrepareTicketDraftToolName = "prepare_ticket_draft"
GraphPrepareTicketDraftToolTitle = "整理工单草稿"
GraphPrepareTicketDraftToolDescription = "Graph Tool。用于根据当前会话和已收集信息整理工单草稿，输出建议标题、描述、缺失字段和追问建议。"
GraphCreateTicketConfirmToolCode = "graph/create_ticket_with_confirmation"
GraphCreateTicketConfirmToolName = "create_ticket_with_confirmation"
GraphCreateTicketConfirmToolTitle = "创建工单确认流程"
GraphCreateTicketConfirmToolDescription = "Graph Tool。用于封装建单参数整理、用户确认、真正建单和结果返回的确定性流程。"
GraphHandoffConversationToolCode = "graph/handoff_to_human"
GraphHandoffConversationToolName = "handoff_to_human"
GraphHandoffConversationToolTitle = "转人工确认流程"
GraphHandoffConversationToolDescription = "Graph Tool。用于封装转人工原因整理、用户确认、真正转人工和结果返回的确定性流程。"
BuiltinCreateTicketConfirmToolCode = "builtin/create_ticket_with_confirmation"
BuiltinCreateTicketConfirmToolName = "create_ticket_with_confirmation"
BuiltinCreateTicketConfirmToolTitle = "创建工单并发起确认"
BuiltinCreateTicketConfirmToolDescription = "当用户明确要求创建工单，且标题和描述已经整理清楚后调用。工具会先向用户确认，确认后才真正创建工单。"
import "strings"
type ToolSpec struct {
Code string
ServerCode string
Name string
Title string
Description string
SourceType string
AutoInjected bool
Aliases []string
}
var (
BuiltinToolSearch = ToolSpec{
Code: "builtin/tool_search",
ServerCode: "builtin",
Name: "tool_search",
Title: "搜索并调用动态工具",
Description: "用于搜索当前允许使用的 MCP 工具，并在确认目标 toolCode 后动态调用该工具。适合处理长尾工具，不应替代固定内置流程工具。",
SourceType: "builtin",
AutoInjected: true,
}
BuiltinSkill = ToolSpec{
Code: "builtin/skill",
ServerCode: "builtin",
Name: "skill",
Title: "加载专项技能说明",
Description: "用于加载当前命中的专项技能说明文档。仅在本轮已命中 Skill 时可用，适合将专项处理规则按需注入上下文。",
SourceType: "builtin",
AutoInjected: true,
}
GraphTriageServiceRequest = ToolSpec{
Code: "graph/triage_service_request",
ServerCode: "graph",
Name: "triage_service_request",
Title: "升级分流判断",
Description: "Graph Tool。用于综合分析当前对话，判断应继续解答、整理工单草稿还是转人工，并在需要建单时一并整理工单草稿。",
SourceType: "graph",
}
GraphAnalyzeConversation = ToolSpec{
Code: "graph/analyze_conversation",
ServerCode: "graph",
Name: "analyze_conversation",
Title: "分析对话风险与摘要",
Description: "Graph Tool。用于整理当前对话摘要、识别风险信号，并给出继续解答、建单或转人工的建议。",
SourceType: "graph",
}
GraphPrepareTicketDraft = ToolSpec{
Code: "graph/prepare_ticket_draft",
ServerCode: "graph",
Name: "prepare_ticket_draft",
Title: "整理工单草稿",
Description: "Graph Tool。用于根据当前会话和已收集信息整理工单草稿，输出建议标题、描述、缺失字段和追问建议。",
SourceType: "graph",
}
GraphCreateTicketConfirm = ToolSpec{
Code: "graph/create_ticket_with_confirmation",
ServerCode: "graph",
Name: "create_ticket_with_confirmation",
Title: "创建工单确认流程",
Description: "Graph Tool。用于封装建单参数整理、用户确认、真正建单和结果返回的确定性流程。",
SourceType: "graph",
Aliases: []string{"builtin/create_ticket_with_confirmation"},
}
GraphHandoffConversation = ToolSpec{
Code: "graph/handoff_to_human",
ServerCode: "graph",
Name: "handoff_to_human",
Title: "转人工确认流程",
Description: "Graph Tool。用于封装转人工原因整理、用户确认、真正转人工和结果返回的确定性流程。",
SourceType: "graph",
}
RegisteredToolSpecs = []ToolSpec{
BuiltinToolSearch,
BuiltinSkill,
GraphTriageServiceRequest,
GraphAnalyzeConversation,
GraphPrepareTicketDraft,
GraphCreateTicketConfirm,
GraphHandoffConversation,
}
)
var (
toolSpecByCode = buildToolSpecByCode()
toolAliasToCanonical = buildToolAliasToCanonical()
)
func buildToolSpecByCode() map[string]ToolSpec {
ret := make(map[string]ToolSpec, len(RegisteredToolSpecs))
for _, spec := range RegisteredToolSpecs {
if strings.TrimSpace(spec.Code) == "" {
continue
}
ret[spec.Code] = spec
}
return ret
}
func buildToolAliasToCanonical() map[string]string {
ret := make(map[string]string)
for _, spec := range RegisteredToolSpecs {
for _, alias := range spec.Aliases {
alias = strings.TrimSpace(alias)
if alias == "" {
continue
}
ret[alias] = spec.Code
}
}
return ret
}
func ListRegisteredToolSpecs() []ToolSpec {
return append([]ToolSpec(nil), RegisteredToolSpecs...)
}
func GetRegisteredToolSpec(toolCode string) (ToolSpec, bool) {
toolCode = NormalizeToolCodeAlias(strings.TrimSpace(toolCode))
spec, ok := toolSpecByCode[toolCode]
return spec, ok
}
func GetRegisteredToolTitle(toolCode string) string {
spec, ok := GetRegisteredToolSpec(toolCode)
if !ok {
return ""
}
return spec.Title
}
func GetRegisteredToolDescription(toolCode string) string {
spec, ok := GetRegisteredToolSpec(toolCode)
if !ok {
return ""
}
return spec.Description
}
func GetRegisteredToolIdentity(toolCode string) (serverCode, toolName string, ok bool) {
spec, ok := GetRegisteredToolSpec(toolCode)
if !ok {
return "", "", false
}
return spec.ServerCode, spec.Name, true
}
func ResolveToolSourceType(toolCode string) string {
if spec, ok := GetRegisteredToolSpec(toolCode); ok {
return spec.SourceType
}
toolCode = strings.TrimSpace(toolCode)
switch {
case strings.HasPrefix(toolCode, "graph/"):
return "graph"
case strings.HasPrefix(toolCode, "builtin/"):
return "builtin"
default:
return "mcp"
}
}
func IsAutoInjectedToolCode(toolCode string) bool {
return toolCode == BuiltinToolSearchToolCode || toolCode == BuiltinSkillToolCode
spec, ok := GetRegisteredToolSpec(toolCode)
return ok && spec.AutoInjected
}
func NormalizeToolCodeAlias(toolCode string) string {
switch toolCode {
case BuiltinCreateTicketConfirmToolCode:
return GraphCreateTicketConfirmToolCode
default:
return toolCode
toolCode = strings.TrimSpace(toolCode)
if canonical, ok := toolAliasToCanonical[toolCode]; ok {
return canonical
}
return toolCode
}
internal/services/agent_run_log_service.go
+9 -9
View File
@@ -106,15 +106,15 @@ func (s *agentRunLogService) BuildGraphSummary(aiAgentID int64) *AgentRunGraphSu
return cnd
}
return &AgentRunGraphSummary{
TriageCount: s.countByGraphTool(buildBaseCnd(), toolx.GraphTriageServiceRequestToolCode),
TriagePrepareTicket: s.countByGraphToolAndPlanReason(buildBaseCnd(), toolx.GraphTriageServiceRequestToolCode, "%prepare_ticket%"),
TriagePrepareTicketReady: s.countByGraphToolAndPlanReason(buildBaseCnd(), toolx.GraphTriageServiceRequestToolCode, "%prepare_ticket with ready ticket draft%"),
TriageHandoff: s.countByGraphToolAndPlanReason(buildBaseCnd(), toolx.GraphTriageServiceRequestToolCode, "%handoff_to_human%"),
TriageContinueAnswering: s.countByGraphToolAndPlanReason(buildBaseCnd(), toolx.GraphTriageServiceRequestToolCode, "%continue_answering%"),
AnalyzeCount: s.countByGraphTool(buildBaseCnd(), toolx.GraphAnalyzeConversationToolCode),
PrepareDraftCount: s.countByGraphTool(buildBaseCnd(), toolx.GraphPrepareTicketDraftToolCode),
CreateTicketCount: s.countByGraphTool(buildBaseCnd(), toolx.GraphCreateTicketConfirmToolCode),
HandoffCount: s.countByGraphTool(buildBaseCnd(), toolx.GraphHandoffConversationToolCode),
TriageCount: s.countByGraphTool(buildBaseCnd(), toolx.GraphTriageServiceRequest.Code),
TriagePrepareTicket: s.countByGraphToolAndPlanReason(buildBaseCnd(), toolx.GraphTriageServiceRequest.Code, "%prepare_ticket%"),
TriagePrepareTicketReady: s.countByGraphToolAndPlanReason(buildBaseCnd(), toolx.GraphTriageServiceRequest.Code, "%prepare_ticket with ready ticket draft%"),
TriageHandoff: s.countByGraphToolAndPlanReason(buildBaseCnd(), toolx.GraphTriageServiceRequest.Code, "%handoff_to_human%"),
TriageContinueAnswering: s.countByGraphToolAndPlanReason(buildBaseCnd(), toolx.GraphTriageServiceRequest.Code, "%continue_answering%"),
AnalyzeCount: s.countByGraphTool(buildBaseCnd(), toolx.GraphAnalyzeConversation.Code),
PrepareDraftCount: s.countByGraphTool(buildBaseCnd(), toolx.GraphPrepareTicketDraft.Code),
CreateTicketCount: s.countByGraphTool(buildBaseCnd(), toolx.GraphCreateTicketConfirm.Code),
HandoffCount: s.countByGraphTool(buildBaseCnd(), toolx.GraphHandoffConversation.Code),
}
}
internal/services/tool_catalog_service.go
+30 -28
View File
@@ -34,36 +34,38 @@ type MCPToolCatalogItem struct {
func (s *toolCatalogService) ListMCPTools(ctx context.Context) ([]MCPToolCatalogItem, error) {
cfg := config.Current()
ret := make([]MCPToolCatalogItem, 0, 3)
ret = append(ret, MCPToolCatalogItem{
ToolCode: toolx.GraphCreateTicketConfirmToolCode,
ServerCode: toolx.GraphToolCatalogServerCode,
ToolName: toolx.GraphCreateTicketConfirmToolName,
SourceType: toolx.GraphToolCatalogServerCode,
AutoInjected: false,
Title: toolx.GraphCreateTicketConfirmToolTitle,
Description: toolx.GraphCreateTicketConfirmToolDescription,
})
ret = append(ret, MCPToolCatalogItem{
ToolCode: toolx.GraphHandoffConversationToolCode,
ServerCode: toolx.GraphToolCatalogServerCode,
ToolName: toolx.GraphHandoffConversationToolName,
SourceType: toolx.GraphToolCatalogServerCode,
AutoInjected: false,
Title: toolx.GraphHandoffConversationToolTitle,
Description: toolx.GraphHandoffConversationToolDescription,
})
for _, toolCode := range []string{
toolx.GraphCreateTicketConfirm.Code,
toolx.GraphHandoffConversation.Code,
} {
spec, ok := toolx.GetRegisteredToolSpec(toolCode)
if !ok {
continue
}
ret = append(ret, MCPToolCatalogItem{
ToolCode: spec.Code,
ServerCode: spec.ServerCode,
ToolName: spec.Name,
SourceType: spec.SourceType,
AutoInjected: spec.AutoInjected,
Title: spec.Title,
Description: spec.Description,
})
}
if !cfg.MCP.Enabled {
return ret, nil
}
ret = append(ret, MCPToolCatalogItem{
ToolCode: toolx.BuiltinToolSearchToolCode,
ServerCode: toolx.BuiltinToolCatalogServerCode,
ToolName: toolx.BuiltinToolSearchToolName,
SourceType: toolx.BuiltinToolCatalogServerCode,
AutoInjected: true,
Title: toolx.BuiltinToolSearchToolTitle,
Description: toolx.BuiltinToolSearchToolDescription,
})
if spec, ok := toolx.GetRegisteredToolSpec(toolx.BuiltinToolSearch.Code); ok {
ret = append(ret, MCPToolCatalogItem{
ToolCode: spec.Code,
ServerCode: spec.ServerCode,
ToolName: spec.Name,
SourceType: spec.SourceType,
AutoInjected: spec.AutoInjected,
Title: spec.Title,
Description: spec.Description,
})
}
serverCodes := make([]string, 0, len(cfg.MCP.Servers))
for serverCode, server := range cfg.MCP.Servers {
if !server.Enabled {
@@ -105,7 +107,7 @@ func (s *toolCatalogService) ValidateToolCode(toolCode string) error {
return errorsx.InvalidParam("toolCode不能为空")
}
switch toolCode {
case toolx.BuiltinToolSearchToolCode, toolx.BuiltinCreateTicketConfirmToolCode, toolx.GraphCreateTicketConfirmToolCode, toolx.GraphHandoffConversationToolCode:
case toolx.BuiltinToolSearch.Code, "builtin/create_ticket_with_confirmation", toolx.GraphCreateTicketConfirm.Code, toolx.GraphHandoffConversation.Code:
return nil
}
serverCode, toolName := toolx.SplitMCPToolCode(toolCode)