如何构建 AI Agent：生产级架构与代码实战

Agent = 模型 + Harness + 工具 + 运行环境

package refund

import (
	"errors"
	"regexp"
)

var orderIDPattern = regexp.MustCompile(`^ord_[a-zA-Z0-9]+$`)

type Draft struct {
	OrderID     string
	AmountCents int64
	Reason      string
}

func (draft Draft) Validate(maxAmountCents int64) error {
	if !orderIDPattern.MatchString(draft.OrderID) {
		return errors.New("invalid order ID")
	}
	if draft.AmountCents <= 0 || draft.AmountCents > maxAmountCents {
		return errors.New("refund amount is outside policy")
	}
	switch draft.Reason {
	case "duplicate", "damaged", "not_received":
		return nil
	default:
		return errors.New("unsupported refund reason")
	}
}

const (
	maxTurns       = 12
	maxToolCalls   = 20
	maxWallSeconds = 90
	maxCostMicros  = 500_000
)

package main

import (
	"context"
	"errors"
	"fmt"
)

type actionKind string

const (
	callTool actionKind = "call_tool"
	finish   actionKind = "finish"
)

type decision struct {
	Kind    actionKind
	Tool    string
	OrderID string
	Final   *finalAnswer
}

type finalAnswer struct {
	OrderID    string
	Status     string
	Refundable bool
}

type observation struct {
	Code       string
	OrderID    string
	Status     string
	Refundable bool
}

type runState struct {
	Goal         string
	Turns        int
	ToolCalls    int
	Observations []observation
	Result       string
}

type model interface {
	Decide(context.Context, runState) (decision, error)
}

type scriptedModel struct{}

func (scriptedModel) Decide(_ context.Context, state runState) (decision, error) {
	if len(state.Observations) == 0 {
		return decision{Kind: callTool, Tool: "get_order_status", OrderID: "ord_1001"}, nil
	}
	current := state.Observations[len(state.Observations)-1]
	if current.Code != "ok" {
		return decision{}, errors.New("cannot produce a verified answer")
	}
	return decision{
		Kind: finish,
		Final: &finalAnswer{
			OrderID:    current.OrderID,
			Status:     current.Status,
			Refundable: current.Refundable,
		},
	}, nil
}

type authContext struct {
	TenantID    string
	PrincipalID string
}

type order struct {
	ID         string
	TenantID   string
	Status     string
	Refundable bool
}

type runtime struct {
	Model        model
	Orders       map[string]order
	MaxTurns     int
	MaxToolCalls int
	Checkpoint   func(runState) error
}

func (agent runtime) Run(
	ctx context.Context,
	auth authContext,
	goal string,
) (runState, error) {
	state := runState{Goal: goal}
	for state.Turns < agent.MaxTurns {
		if err := ctx.Err(); err != nil {
			return state, err
		}
		next, err := agent.Model.Decide(ctx, state)
		if err != nil {
			return state, err
		}
		state.Turns++

		switch next.Kind {
		case callTool:
			if state.ToolCalls >= agent.MaxToolCalls {
				return state, errors.New("tool-call budget exhausted")
			}
			if next.Tool != "get_order_status" {
				return state, errors.New("tool is not allowlisted")
			}
			result, err := agent.getOrderStatus(auth, next.OrderID)
			if err != nil {
				return state, err
			}
			state.ToolCalls++
			state.Observations = append(state.Observations, result)
		case finish:
			if len(state.Observations) == 0 || next.Final == nil {
				return state, errors.New("final answer has no supporting observation")
			}
			current := state.Observations[len(state.Observations)-1]
			if next.Final.OrderID != current.OrderID ||
				next.Final.Status != current.Status ||
				next.Final.Refundable != current.Refundable {
				return state, errors.New("final answer contradicts tool evidence")
			}
			state.Result = fmt.Sprintf(
				"Order %s is %s; refundable=%t.",
				next.Final.OrderID,
				next.Final.Status,
				next.Final.Refundable,
			)
			if err := agent.checkpoint(state); err != nil {
				return state, fmt.Errorf("checkpoint final state: %w", err)
			}
			return state, nil
		default:
			return state, errors.New("unsupported model decision")
		}

		if err := agent.checkpoint(state); err != nil {
			return state, fmt.Errorf("checkpoint transition: %w", err)
		}
	}
	return state, errors.New("turn budget exhausted")
}

func (agent runtime) checkpoint(state runState) error {
	if agent.Checkpoint == nil {
		return nil
	}
	return agent.Checkpoint(state)
}

func (agent runtime) getOrderStatus(
	auth authContext,
	orderID string,
) (observation, error) {
	if auth.PrincipalID == "" || auth.TenantID == "" {
		return observation{}, errors.New("authenticated context is required")
	}
	item, ok := agent.Orders[orderID]
	if !ok || item.TenantID != auth.TenantID {
		return observation{}, errors.New("order not found or not authorized")
	}
	return observation{
		Code:       "ok",
		OrderID:    item.ID,
		Status:     item.Status,
		Refundable: item.Refundable,
	}, nil
}

func main() {
	agent := runtime{
		Model: scriptedModel{},
		Orders: map[string]order{
			"ord_1001": {
				ID:         "ord_1001",
				TenantID:   "tenant-a",
				Status:     "delivered",
				Refundable: true,
			},
		},
		MaxTurns:     6,
		MaxToolCalls: 2,
		Checkpoint: func(state runState) error {
			fmt.Printf("checkpoint turns=%d tools=%d\n", state.Turns, state.ToolCalls)
			return nil
		},
	}

	state, err := agent.Run(
		context.Background(),
		authContext{TenantID: "tenant-a", PrincipalID: "user-42"},
		"Can order ord_1001 still be refunded?",
	)
	if err != nil {
		panic(err)
	}
	fmt.Println(state.Result)
}

go run support_agent.go