refactor(agent): replace XML api_call with native function calling

Migrate the Telegram bot agent from an XML tag hack (<api_call>) to OpenAI-native function calling via CallWithRequestFull. Key changes: - mcp/interface.go: add parseMCPResponseFull to clientHooks interface - mcp/client.go: route callWithRequestFull through hooks for overridability - mcp/claude_client.go: override parseMCPResponseFull for Claude response format (tool_use blocks instead of choices[].message.tool_calls) - telegram/agent/agent.go: rewrite Run() to use CallWithRequestFull; define api_request tool with JSON Schema; implement tool-call loop with role="tool" result messages; remove XML parsing entirely - telegram/agent/apicall.go: remove parseAPICall (dead code) - telegram/agent/prompt.go: simplify — remove XML format instructions, replace with concise api_request tool usage instructions - telegram/agent/agent_test.go: rebuild all tests using LLMResponse objects; add TestNarrationStructurallyImpossible, TestOnChunkCalledWithFinalReply, TestToolCallIDPropagated; remove XML-specific tests Architecture advantage: with native function calling, the LLM returns EITHER ToolCalls OR Content — never both. Narration is now structurally impossible at the protocol level, not just enforced by prompt rules. All 11 agent tests pass. mcp package tests pass.
2026-07-17 17:34:39 +08:00 · 2026-03-08 17:10:07 +08:00
parent 5f47dd13db
commit 9fcf44af65
8 changed files with 472 additions and 320 deletions
--- a/mcp/claude_client.go
+++ b/mcp/claude_client.go
@@ -92,6 +92,68 @@ func (c *ClaudeClient) buildMCPRequestBody(systemPrompt, userPrompt string) map[
 	return requestBody
 }

+// parseMCPResponseFull Claude response format — handles both text and tool_use blocks.
+func (c *ClaudeClient) parseMCPResponseFull(body []byte) (*LLMResponse, error) {
+	var response struct {
+		Content []struct {
+			Type  string          `json:"type"`
+			Text  string          `json:"text,omitempty"`
+			ID    string          `json:"id,omitempty"`
+			Name  string          `json:"name,omitempty"`
+			Input json.RawMessage `json:"input,omitempty"`
+		} `json:"content"`
+		Usage struct {
+			InputTokens  int `json:"input_tokens"`
+			OutputTokens int `json:"output_tokens"`
+		} `json:"usage"`
+		Error *struct {
+			Type    string `json:"type"`
+			Message string `json:"message"`
+		} `json:"error"`
+	}
+
+	if err := json.Unmarshal(body, &response); err != nil {
+		return nil, fmt.Errorf("failed to parse Claude response: %w, body: %s", err, string(body))
+	}
+	if response.Error != nil {
+		return nil, fmt.Errorf("Claude API error: %s - %s", response.Error.Type, response.Error.Message)
+	}
+
+	totalTokens := response.Usage.InputTokens + response.Usage.OutputTokens
+	if TokenUsageCallback != nil && totalTokens > 0 {
+		TokenUsageCallback(TokenUsage{
+			Provider:         c.Provider,
+			Model:            c.Model,
+			PromptTokens:     response.Usage.InputTokens,
+			CompletionTokens: response.Usage.OutputTokens,
+			TotalTokens:      totalTokens,
+		})
+	}
+
+	result := &LLMResponse{}
+	for _, block := range response.Content {
+		switch block.Type {
+		case "text":
+			result.Content = block.Text
+		case "tool_use":
+			// Claude returns arguments as a JSON object (Input field); convert to string.
+			argsJSON, err := json.Marshal(block.Input)
+			if err != nil {
+				argsJSON = []byte("{}")
+			}
+			result.ToolCalls = append(result.ToolCalls, ToolCall{
+				ID:   block.ID,
+				Type: "function",
+				Function: ToolCallFunction{
+					Name:      block.Name,
+					Arguments: string(argsJSON),
+				},
+			})
+		}
+	}
+	return result, nil
+}
+
 // parseMCPResponse Claude has different response format
 func (c *ClaudeClient) parseMCPResponse(body []byte) (string, error) {
 	var response struct {
--- a/mcp/client.go
+++ b/mcp/client.go
@@ -234,10 +234,21 @@ func (client *Client) marshalRequestBody(requestBody map[string]any) ([]byte, er
 }

 func (client *Client) parseMCPResponse(body []byte) (string, error) {
+	r, err := client.parseMCPResponseFull(body)
+	if err != nil {
+		return "", err
+	}
+	return r.Content, nil
+}
+
+// parseMCPResponseFull parses the OpenAI-format response body and returns both
+// the text content and any tool calls.
+func (client *Client) parseMCPResponseFull(body []byte) (*LLMResponse, error) {
 	var result struct {
 		Choices []struct {
 			Message struct {
-				Content string `json:"content"`
+				Content   string     `json:"content"`
+				ToolCalls []ToolCall `json:"tool_calls"`
 			} `json:"message"`
 		} `json:"choices"`
 		Usage struct {
@@ -248,11 +259,11 @@ func (client *Client) parseMCPResponse(body []byte) (string, error) {
 	}

 	if err := json.Unmarshal(body, &result); err != nil {
-		return "", fmt.Errorf("failed to parse response: %w", err)
+		return nil, fmt.Errorf("failed to parse response: %w", err)
 	}

 	if len(result.Choices) == 0 {
-		return "", fmt.Errorf("API returned empty response")
+		return nil, fmt.Errorf("API returned empty response")
 	}

 	// Report token usage if callback is set
@@ -266,7 +277,11 @@ func (client *Client) parseMCPResponse(body []byte) (string, error) {
 		})
 	}

-	return result.Choices[0].Message.Content, nil
+	msg := result.Choices[0].Message
+	return &LLMResponse{
+		Content:   msg.Content,
+		ToolCalls: msg.ToolCalls,
+	}, nil
 }

 func (client *Client) buildUrl() string {
@@ -427,6 +442,70 @@ func (client *Client) CallWithRequest(req *Request) (string, error) {
 	return "", fmt.Errorf("still failed after %d retries: %w", maxRetries, lastErr)
 }

+// CallWithRequestFull calls the AI API and returns both text content and tool calls.
+func (client *Client) CallWithRequestFull(req *Request) (*LLMResponse, error) {
+	if client.APIKey == "" {
+		return nil, fmt.Errorf("AI API key not set, please call SetAPIKey first")
+	}
+	if req.Model == "" {
+		req.Model = client.Model
+	}
+
+	var lastErr error
+	maxRetries := client.config.MaxRetries
+	for attempt := 1; attempt <= maxRetries; attempt++ {
+		if attempt > 1 {
+			client.logger.Warnf("⚠️  AI API call failed, retrying (%d/%d)...", attempt, maxRetries)
+		}
+		result, err := client.callWithRequestFull(req)
+		if err == nil {
+			return result, nil
+		}
+		lastErr = err
+		if !client.hooks.isRetryableError(err) {
+			return nil, err
+		}
+		if attempt < maxRetries {
+			waitTime := client.config.RetryWaitBase * time.Duration(attempt)
+			time.Sleep(waitTime)
+		}
+	}
+	return nil, fmt.Errorf("still failed after %d retries: %w", maxRetries, lastErr)
+}
+
+// callWithRequestFull single call that returns LLMResponse (content + tool calls).
+func (client *Client) callWithRequestFull(req *Request) (*LLMResponse, error) {
+	client.logger.Infof("📡 [%s] Request AI Server (full): BaseURL: %s", client.String(), client.BaseURL)
+
+	requestBody := client.buildRequestBodyFromRequest(req)
+	jsonData, err := client.hooks.marshalRequestBody(requestBody)
+	if err != nil {
+		return nil, err
+	}
+
+	url := client.hooks.buildUrl()
+	httpReq, err := client.hooks.buildRequest(url, jsonData)
+	if err != nil {
+		return nil, fmt.Errorf("failed to create request: %w", err)
+	}
+
+	resp, err := client.httpClient.Do(httpReq)
+	if err != nil {
+		return nil, fmt.Errorf("failed to send request: %w", err)
+	}
+	defer resp.Body.Close()
+
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, fmt.Errorf("failed to read response: %w", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("API returned error (status %d): %s", resp.StatusCode, string(body))
+	}
+
+	return client.hooks.parseMCPResponseFull(body)
+}
+
 // callWithRequest single AI API call (using Request object)
 func (client *Client) callWithRequest(req *Request) (string, error) {
 	// Print current AI configuration
@@ -481,13 +560,23 @@ func (client *Client) callWithRequest(req *Request) (string, error) {

 // buildRequestBodyFromRequest builds request body from Request object
 func (client *Client) buildRequestBodyFromRequest(req *Request) map[string]any {
-	// Convert Message to API format
-	messages := make([]map[string]string, 0, len(req.Messages))
+	// Convert Message to API format — must use map[string]any to support
+	// tool-call messages (tool_calls, tool_call_id fields).
+	messages := make([]map[string]any, 0, len(req.Messages))
 	for _, msg := range req.Messages {
-		messages = append(messages, map[string]string{
-			"role":    msg.Role,
-			"content": msg.Content,
-		})
+		m := map[string]any{"role": msg.Role}
+		if len(msg.ToolCalls) > 0 {
+			// Assistant message that contains tool invocations.
+			// content must be null/omitted for OpenAI compatibility.
+			m["tool_calls"] = msg.ToolCalls
+		} else if msg.ToolCallID != "" {
+			// Tool result message (role="tool").
+			m["tool_call_id"] = msg.ToolCallID
+			m["content"] = msg.Content
+		} else {
+			m["content"] = msg.Content
+		}
+		messages = append(messages, m)
 	}

 	// Build basic request body
--- a/mcp/interface.go
+++ b/mcp/interface.go
@@ -15,6 +15,11 @@ type AIClient interface {
 	// onChunk is called with the full accumulated text so far (not raw deltas).
 	// Returns the complete final text when done.
 	CallWithRequestStream(req *Request, onChunk func(string)) (string, error)
+	// CallWithRequestFull returns both text content and tool calls.
+	// Use this when the request includes Tools — the LLM may respond with
+	// either a plain text reply (LLMResponse.Content) or tool invocations
+	// (LLMResponse.ToolCalls), but not both.
+	CallWithRequestFull(req *Request) (*LLMResponse, error)
 }

 // clientHooks internal hook interface (for subclass to override specific steps)
@@ -30,5 +35,6 @@ type clientHooks interface {
 	setAuthHeader(reqHeaders http.Header)
 	marshalRequestBody(requestBody map[string]any) ([]byte, error)
 	parseMCPResponse(body []byte) (string, error)
+	parseMCPResponseFull(body []byte) (*LLMResponse, error)
 	isRetryableError(err error) bool
 }
--- a/mcp/request.go
+++ b/mcp/request.go
@@ -1,9 +1,34 @@
 package mcp

-// Message represents a conversation message
+// Message represents a conversation message.
+// Supports plain messages (Role+Content), assistant tool-call messages (ToolCalls),
+// and tool result messages (Role="tool", ToolCallID, Content).
 type Message struct {
-	Role    string `json:"role"`    // "system", "user", "assistant"
-	Content string `json:"content"` // Message content
+	Role       string     `json:"role"`                  // "system", "user", "assistant", "tool"
+	Content    string     `json:"content,omitempty"`     // Text content (omitted when ToolCalls present)
+	ToolCalls  []ToolCall `json:"tool_calls,omitempty"`  // Set by assistant when calling tools
+	ToolCallID string     `json:"tool_call_id,omitempty"` // Set on role="tool" result messages
+}
+
+// ToolCall is a single function call requested by the LLM.
+type ToolCall struct {
+	ID       string           `json:"id"`       // Unique call ID (e.g. "call_abc123")
+	Type     string           `json:"type"`     // Always "function"
+	Function ToolCallFunction `json:"function"` // Function name and JSON-serialised arguments
+}
+
+// ToolCallFunction holds the function name and raw JSON arguments string.
+type ToolCallFunction struct {
+	Name      string `json:"name"`      // Function name
+	Arguments string `json:"arguments"` // JSON-encoded argument object
+}
+
+// LLMResponse is returned by CallWithRequestFull and carries both the assistant
+// text reply (Content) and any structured tool calls (ToolCalls).
+// Exactly one of the two fields will be non-empty for a well-formed response.
+type LLMResponse struct {
+	Content   string     // Plain-text reply (final answer)
+	ToolCalls []ToolCall // Structured tool invocations
 }

 // Tool represents a tool/function that AI can call