handoff

package

v1.1.0 Latest Latest Go to latest Published: Feb 24, 2026 License: MIT Imports: 5 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/BaSui01/agentflow

Links

Open Source Insights

Documentation ¶

Overview ¶

包 handoff 提供智能体间的任务交接协议与上下文传递能力。

概述 ¶

handoff 解决的核心问题是：当一个 Agent 无法独立完成任务或需要将子任务委派给更合适的 Agent 时，如何安全、可靠地完成任务移交并保持上下文连续性。它定义了一套完整的交接协议，涵盖任务发起、能力匹配、接受确认、执行跟踪与结果回传的全生命周期。

核心模型 ¶

本包围绕以下类型展开：

Handoff：交接记录，包含来源/目标 Agent、任务、状态、上下文与结果
Task：被交接的任务，携带类型、描述、输入数据与优先级
HandoffContext：交接上下文，传递对话历史、变量与父级交接链
HandoffResult：交接执行结果，包含输出数据、错误信息与耗时
HandoffAgent：支持交接的 Agent 接口，声明能力并处理交接请求
HandoffManager：交接管理器，协调 Agent 注册、能力匹配与交接执行

交接状态通过 HandoffStatus 枚举管理： pending -> accepted -> in_progress -> completed / failed / rejected。

主要能力 ¶

Agent 能力注册：通过 AgentCapability 声明可处理的任务类型与优先级
智能路由：根据任务类型自动匹配最优 Agent（按优先级排序）
同步/异步交接：通过 HandoffOptions.Wait 控制是否等待执行完成
超时与重试：支持交接超时控制与最大重试次数配置
上下文传递：在交接过程中保持对话历史与变量的连续性

与其他包协同 ¶

handoff 可与 agent/federation 配合实现跨组织的任务委派，也可与核心 agent 包集成，作为多 Agent 协作的基础通信协议。

Index ¶

type AgentCapability
type Handoff
type HandoffAgent
type HandoffContext
type HandoffManager
- func NewHandoffManager(logger *zap.Logger) *HandoffManager
type HandoffOptions
type HandoffResult
type HandoffStatus
type Message
type Task

Constants ¶

This section is empty.

Variables ¶

This section is empty.

Functions ¶

This section is empty.

Types ¶

type AgentCapability ¶

type AgentCapability struct {
	Name        string   `json:"name"`
	Description string   `json:"description"`
	TaskTypes   []string `json:"task_types"`
	Priority    int      `json:"priority"`
}

Agent Captainable 描述一个代理能够做什么.

type Handoff ¶

type Handoff struct {
	ID          string         `json:"id"`
	FromAgentID string         `json:"from_agent_id"`
	ToAgentID   string         `json:"to_agent_id"`
	Task        Task           `json:"task"`
	Status      HandoffStatus  `json:"status"`
	Context     HandoffContext `json:"context"`
	Result      *HandoffResult `json:"result,omitempty"`
	CreatedAt   time.Time      `json:"created_at"`
	AcceptedAt  *time.Time     `json:"accepted_at,omitempty"`
	CompletedAt *time.Time     `json:"completed_at,omitempty"`
	Timeout     time.Duration  `json:"timeout"`
	RetryCount  int            `json:"retry_count"`
	MaxRetries  int            `json:"max_retries"`
	// contains filtered or unexported fields
}

Handoff代表着从一个代理人到另一个代理人的任务代表团.

type HandoffAgent ¶

type HandoffAgent interface {
	ID() string
	Capabilities() []AgentCapability
	CanHandle(task Task) bool
	AcceptHandoff(ctx context.Context, handoff *Handoff) error
	ExecuteHandoff(ctx context.Context, handoff *Handoff) (*HandoffResult, error)
}

支持交接的代理商的交接代理接口.

type HandoffContext ¶

type HandoffContext struct {
	ConversationID string         `json:"conversation_id,omitempty"`
	Messages       []Message      `json:"messages,omitempty"`
	Variables      map[string]any `json:"variables,omitempty"`
	ParentHandoff  string         `json:"parent_handoff,omitempty"`
}

HandoffContext为交接提供了上下文.

type HandoffManager ¶

type HandoffManager struct {
	// contains filtered or unexported fields
}

HandoffManager管理代理人的交割.

func NewHandoffManager ¶

func NewHandoffManager(logger *zap.Logger) *HandoffManager

NewHandoffManager创建了新的交接管理器.

func (*HandoffManager) FindAgent ¶

func (m *HandoffManager) FindAgent(task Task) (HandoffAgent, error)

FindAgent 找到任务的最佳代理。

func (*HandoffManager) GetHandoff ¶

func (m *HandoffManager) GetHandoff(handoffID string) (*Handoff, error)

找汉多夫拿回身份证

func (*HandoffManager) Handoff ¶

func (m *HandoffManager) Handoff(ctx context.Context, opts HandoffOptions) (*Handoff, error)

Handoff会向另一个特工交接

func (*HandoffManager) RegisterAgent ¶

func (m *HandoffManager) RegisterAgent(agent HandoffAgent)

代理人登记代理人进行交割.

func (*HandoffManager) UnregisterAgent ¶

func (m *HandoffManager) UnregisterAgent(agentID string)

未注册代理删除代理。

type HandoffOptions ¶

type HandoffOptions struct {
	FromAgentID string
	ToAgentID   string
	Task        Task
	Context     HandoffContext
	Timeout     time.Duration
	MaxRetries  int
	Wait        bool
}

交接选项配置交接。

type HandoffResult ¶

type HandoffResult struct {
	Output   any    `json:"output"`
	Error    string `json:"error,omitempty"`
	Duration int64  `json:"duration_ms"`
}

HandoffResult包含完成交接的结果.

type HandoffStatus ¶

type HandoffStatus string

交接状态代表交接状态.

const (
	StatusPending    HandoffStatus = "pending"
	StatusAccepted   HandoffStatus = "accepted"
	StatusRejected   HandoffStatus = "rejected"
	StatusInProgress HandoffStatus = "in_progress"
	StatusCompleted  HandoffStatus = "completed"
	StatusFailed     HandoffStatus = "failed"
)

type Message ¶

type Message struct {
	Role    string `json:"role"`
	Content string `json:"content"`
}

信件代表对话信息。

type Task ¶

type Task struct {
	Type        string         `json:"type"`
	Description string         `json:"description"`
	Input       any            `json:"input"`
	Priority    int            `json:"priority"`
	Metadata    map[string]any `json:"metadata,omitempty"`
}

任务代表着正在移交的任务。

Source Files ¶

View all Source files

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL