Agent 可观测性：Trace、Eval 与调试

{
  "event": "tool_call_completed",
  "schema_version": 3,
  "run_id": "run_7f...",
  "trace_id": "4bf92f...",
  "step": 4,
  "tenant_hash": "h:...",
  "subject_hash": "h:...",
  "tool": "invoice.list",
  "tool_version": "2026-05-1",
  "argument_digest": "sha256:...",
  "policy": "allow",
  "state_version": 12,
  "duration_ms": 184,
  "result_class": "bounded_page",
  "error_code": null,
  "usage": {
    "input_tokens": 812,
    "output_tokens": 164,
    "estimated_cost_usd": 0.0019
  }
}

package main

import (
	"crypto/sha256"
	"encoding/hex"
	"encoding/json"
	"fmt"
)

type RunContext struct {
	RunID     string
	TenantID  string
	SubjectID string
}

type ToolInput struct {
	Name           string
	Version        string
	Arguments      map[string]any
	PolicyDecision string
	StateVersion   int
	DurationMS     int64
	ResultClass    string
	ErrorCode      string
}

type ToolEvent struct {
	Name       string         `json:"name"`
	Attributes map[string]any `json:"attributes"`
}

func digestText(value string) string {
	sum := sha256.Sum256([]byte(value))
	return "sha256:" + hex.EncodeToString(sum[:])
}

func digestJSON(value any) (string, error) {
	data, err := json.Marshal(value)
	if err != nil {
		return "", err
	}
	return digestText(string(data)), nil
}

func recordToolEvent(context RunContext, input ToolInput) (ToolEvent, error) {
	argumentDigest, err := digestJSON(input.Arguments)
	if err != nil {
		return ToolEvent{}, err
	}
	attributes := map[string]any{
		"agent.run_id":          context.RunID,
		"agent.tenant_hash":     digestText(context.TenantID),
		"agent.subject_hash":    digestText(context.SubjectID),
		"agent.tool.name":       input.Name,
		"agent.tool.version":    input.Version,
		"agent.argument_digest": argumentDigest,
		"agent.policy.decision": input.PolicyDecision,
		"agent.state.version":   input.StateVersion,
		"agent.duration_ms":     input.DurationMS,
		"agent.result.class":    input.ResultClass,
	}
	if input.ErrorCode != "" {
		attributes["agent.error.code"] = input.ErrorCode
	}
	return ToolEvent{Name: "ToolCall", Attributes: attributes}, nil
}

func main() {
	event, err := recordToolEvent(
		RunContext{RunID: "run_7f", TenantID: "tenant_a", SubjectID: "user_9"},
		ToolInput{
			Name:           "invoice.list",
			Version:        "2026-10-1",
			Arguments:      map[string]any{"status": "open"},
			PolicyDecision: "allow",
			StateVersion:   12,
			DurationMS:     184,
			ResultClass:    "bounded_page",
		},
	)
	if err != nil {
		panic(err)
	}
	output, err := json.MarshalIndent(event, "", "  ")
	if err != nil {
		panic(err)
	}
	fmt.Println(string(output))
}

package main

import (
	"bytes"
	"encoding/json"
	"errors"
	"fmt"
	"io"
)

type JudgeResult struct {
	Supported       string   `json:"supported"`
	Relevant        string   `json:"relevant"`
	MissingEvidence []string `json:"missingEvidence"`
	Rationale       string   `json:"rationale"`
}

func validateJudgeResult(data []byte) (JudgeResult, error) {
	decoder := json.NewDecoder(bytes.NewReader(data))
	decoder.DisallowUnknownFields()

	var result JudgeResult
	if err := decoder.Decode(&result); err != nil {
		return JudgeResult{}, err
	}
	if err := decoder.Decode(&struct{}{}); !errors.Is(err, io.EOF) {
		return JudgeResult{}, errors.New("invalid trailing JSON")
	}

	allowed := map[string]bool{"yes": true, "no": true, "uncertain": true}
	if !allowed[result.Supported] || !allowed[result.Relevant] {
		return JudgeResult{}, errors.New("invalid judgment enum")
	}
	if result.MissingEvidence == nil {
		return JudgeResult{}, errors.New("missingEvidence must be an array")
	}
	return result, nil
}

func main() {
	raw := []byte(`{
		"supported":"uncertain",
		"relevant":"yes",
		"missingEvidence":["invoice status"],
		"rationale":"The answer lacks a current source."
	}`)
	result, err := validateJudgeResult(raw)
	if err != nil {
		panic(err)
	}
	fmt.Printf("%+v\n", result)
}

package main

import "fmt"

type StepEvent struct {
	Step           int
	Tool           string
	ArgumentDigest string
	StateVersion   int
	Policy         string
	Outcome        string
}

func sameSignature(left, right StepEvent) bool {
	return left.Tool == right.Tool &&
		left.ArgumentDigest == right.ArgumentDigest &&
		left.StateVersion == right.StateVersion &&
		left.Policy == right.Policy &&
		left.Outcome == right.Outcome
}

func detectStall(events []StepEvent, window int) bool {
	if window <= 0 || len(events) < window*2 {
		return false
	}
	start := len(events) - window*2
	for index := 0; index < window; index++ {
		if !sameSignature(events[start+index], events[start+window+index]) {
			return false
		}
	}
	return true
}

func main() {
	events := []StepEvent{
		{Step: 1, Tool: "search", ArgumentDigest: "a", StateVersion: 4, Policy: "allow", Outcome: "empty"},
		{Step: 2, Tool: "search", ArgumentDigest: "b", StateVersion: 4, Policy: "allow", Outcome: "empty"},
		{Step: 3, Tool: "search", ArgumentDigest: "a", StateVersion: 4, Policy: "allow", Outcome: "empty"},
		{Step: 4, Tool: "search", ArgumentDigest: "b", StateVersion: 4, Policy: "allow", Outcome: "empty"},
	}
	fmt.Println(detectStall(events, 2))
}