BytesRouter

主题

CrewAI 文档版本 跟随上游 源快照 db91a99f 更新于 2026-10-18

Merge Agent Handler 工具

让 CrewAI 智能体通过 Merge 的 Agent Handler 平台安全访问 Linear、GitHub、Slack 等第三方集成

MergeAgentHandlerTool

MergeAgentHandlerTool 使 CrewAI 智能体能够通过 Merge 的 Agent Handler 平台安全访问第三方集成。Agent Handler 提供预构建的安全连接器，可连接 Linear、GitHub、Slack、Notion 以及数百种其他热门工具——全部内置身份认证、权限管理和监控。

安装

bash
uv pip install 'crewai[tools]'

要求

  • 已配置 Tool Pack 的 Merge Agent Handler 账户
  • Agent Handler API 密钥
  • 至少一个与你的 Tool Pack 关联的注册用户
  • 在你的 Tool Pack 中配置的第三方集成

Agent Handler 入门

  1. 在 ah.merge.dev/signup 注册 Merge Agent Handler 账户
  2. 创建 Tool Pack 并配置你需要的集成
  3. 注册用户，这些用户将通过第三方服务进行身份认证
  4. 从 Agent Handler 控制台获取 API 密钥
  5. 设置环境变量：export AGENT_HANDLER_API_KEY='your-key-here'
  6. 在 CrewAI 中使用 MergeAgentHandlerTool 开始构建

说明

  • Tool Pack ID 和 Registered User ID 可在你的 Agent Handler 控制台中找到，或通过 API 创建
  • 该工具使用 Model Context Protocol (MCP) 与 Agent Handler 通信
  • 会话 ID 会自动生成，但可以自定义以实现上下文持久化
  • 所有工具调用都会通过 Agent Handler 平台记录并可审计
  • 工具参数从 Agent Handler API 动态发现并自动校验

用量

单个工具用法

以下是如何使用 Tool Pack 中的某个特定工具：

python
from crewai import Agent, Task, Crew
from crewai_tools import MergeAgentHandlerTool

# Create a tool for Linear issue creation
linear_create_tool = MergeAgentHandlerTool.from_tool_name(
    tool_name="linear__create_issue",
    tool_pack_id="134e0111-0f67-44f6-98f0-597000290bb3",
    registered_user_id="91b2b905-e866-40c8-8be2-efe53827a0aa"
)

# Create a CrewAI agent that uses the tool
project_manager = Agent(
    role='Project Manager',
    goal='Manage project tasks and issues efficiently',
    backstory='I am an expert at tracking project work and creating actionable tasks.',
    tools=[linear_create_tool],
    verbose=True
)

# Create a task for the agent
create_issue_task = Task(
    description="Create a new high-priority issue in Linear titled 'Implement user authentication' with a detailed description of the requirements.",
    agent=project_manager,
    expected_output="Confirmation that the issue was created with its ID"
)

# Create a crew with the agent
crew = Crew(
    agents=[project_manager],
    tasks=[create_issue_task],
    verbose=True
)

# Run the crew
result = crew.kickoff()
print(result)

从 Tool Pack 加载多个工具

你可以一次性加载 Tool Pack 中所有可用的工具：

python
from crewai import Agent, Task, Crew
from crewai_tools import MergeAgentHandlerTool

# Load all tools from the Tool Pack
tools = MergeAgentHandlerTool.from_tool_pack(
    tool_pack_id="134e0111-0f67-44f6-98f0-597000290bb3",
    registered_user_id="91b2b905-e866-40c8-8be2-efe53827a0aa"
)

# Create an agent with access to all tools
automation_expert = Agent(
    role='Automation Expert',
    goal='Automate workflows across multiple platforms',
    backstory='I can work with any tool in the toolbox to get things done.',
    tools=tools,
    verbose=True
)

automation_task = Task(
    description="Check for any high-priority issues in Linear and post a summary to Slack.",
    agent=automation_expert
)

crew = Crew(
    agents=[automation_expert],
    tasks=[automation_task],
    verbose=True
)

result = crew.kickoff()

仅加载特定工具

只加载你需要的工具：

python
from crewai import Agent, Task, Crew
from crewai_tools import MergeAgentHandlerTool

# Load specific tools from the Tool Pack
selected_tools = MergeAgentHandlerTool.from_tool_pack(
    tool_pack_id="134e0111-0f67-44f6-98f0-597000290bb3",
    registered_user_id="91b2b905-e866-40c8-8be2-efe53827a0aa",
    tool_names=["linear__create_issue", "linear__get_issues", "slack__post_message"]
)

developer_assistant = Agent(
    role='Developer Assistant',
    goal='Help developers track and communicate about their work',
    backstory='I help developers stay organized and keep the team informed.',
    tools=selected_tools,
    verbose=True
)

daily_update_task = Task(
    description="Get all issues assigned to the current user in Linear and post a summary to the #dev-updates Slack channel.",
    agent=developer_assistant
)

crew = Crew(
    agents=[developer_assistant],
    tasks=[daily_update_task],
    verbose=True
)

result = crew.kickoff()

工具参数

from_tool_name() 方法

参数类型必填默认值描述
tool_namestr是None要使用的特定工具名称（例如 "linear__create_issue"）
tool_pack_idstr是None你的 Agent Handler Tool Pack 的 UUID
registered_user_idstr是None已注册用户的 UUID 或 origin_id
base_urlstr否"https://ah-api.merge.dev"Agent Handler API 的基础 URL
session_idstr否自动生成用于维护上下文的 MCP 会话 ID

from_tool_pack() 方法

参数类型必填默认值描述
tool_pack_idstr是None你的 Agent Handler Tool Pack 的 UUID
registered_user_idstr是None已注册用户的 UUID 或 origin_id
tool_nameslist[str]否None要加载的特定工具名称。若为 None，则加载所有可用工具
base_urlstr否"https://ah-api.merge.dev"Agent Handler API 的基础 URL

环境变量

bash
AGENT_HANDLER_API_KEY=your_api_key_here  # Required for authentication

高级用法

具有不同工具访问权限的多智能体工作流

python
from crewai import Agent, Task, Crew, Process
from crewai_tools import MergeAgentHandlerTool

# Create specialized tools for different agents
github_tools = MergeAgentHandlerTool.from_tool_pack(
    tool_pack_id="134e0111-0f67-44f6-98f0-597000290bb3",
    registered_user_id="91b2b905-e866-40c8-8be2-efe53827a0aa",
    tool_names=["github__create_pull_request", "github__get_pull_requests"]
)

linear_tools = MergeAgentHandlerTool.from_tool_pack(
    tool_pack_id="134e0111-0f67-44f6-98f0-597000290bb3",
    registered_user_id="91b2b905-e866-40c8-8be2-efe53827a0aa",
    tool_names=["linear__create_issue", "linear__update_issue"]
)

slack_tool = MergeAgentHandlerTool.from_tool_name(
    tool_name="slack__post_message",
    tool_pack_id="134e0111-0f67-44f6-98f0-597000290bb3",
    registered_user_id="91b2b905-e866-40c8-8be2-efe53827a0aa"
)

# Create specialized agents
code_reviewer = Agent(
    role='Code Reviewer',
    goal='Review pull requests and ensure code quality',
    backstory='I am an expert at reviewing code changes and providing constructive feedback.',
    tools=github_tools
)

task_manager = Agent(
    role='Task Manager',
    goal='Track and update project tasks based on code changes',
    backstory='I keep the project board up to date with the latest development progress.',
    tools=linear_tools
)

communicator = Agent(
    role='Team Communicator',
    goal='Keep the team informed about important updates',
    backstory='I make sure everyone knows what is happening in the project.',
    tools=[slack_tool]
)

# Create sequential tasks
review_task = Task(
    description="Review all open pull requests in the 'api-service' repository and identify any that need attention.",
    agent=code_reviewer,
    expected_output="List of pull requests that need review or have issues"
)

update_task = Task(
    description="Update Linear issues based on the pull request review findings. Mark completed PRs as done.",
    agent=task_manager,
    expected_output="Summary of updated Linear issues"
)

notify_task = Task(
    description="Post a summary of today's code review and task updates to the #engineering Slack channel.",
    agent=communicator,
    expected_output="Confirmation that the message was posted"
)

# Create a crew with sequential processing
crew = Crew(
    agents=[code_reviewer, task_manager, communicator],
    tasks=[review_task, update_task, notify_task],
    process=Process.sequential,
    verbose=True
)

result = crew.kickoff()

自定义会话管理

使用会话 ID 在多次工具调用之间保持上下文：

python
from crewai import Agent, Task, Crew
from crewai_tools import MergeAgentHandlerTool

# Create tools with the same session ID to maintain context
session_id = "project-sprint-planning-2024"

create_tool = MergeAgentHandlerTool(
    name="linear_create_issue",
    description="Creates a new issue in Linear",
    tool_name="linear__create_issue",
    tool_pack_id="134e0111-0f67-44f6-98f0-597000290bb3",
    registered_user_id="91b2b905-e866-40c8-8be2-efe53827a0aa",
    session_id=session_id
)

update_tool = MergeAgentHandlerTool(
    name="linear_update_issue",
    description="Updates an existing issue in Linear",
    tool_name="linear__update_issue",
    tool_pack_id="134e0111-0f67-44f6-98f0-597000290bb3",
    registered_user_id="91b2b905-e866-40c8-8be2-efe53827a0aa",
    session_id=session_id
)

sprint_planner = Agent(
    role='Sprint Planner',
    goal='Plan and organize sprint tasks',
    backstory='I help teams plan effective sprints with well-defined tasks.',
    tools=[create_tool, update_tool],
    verbose=True
)

planning_task = Task(
    description="Create 5 sprint tasks for the authentication feature and set their priorities based on dependencies.",
    agent=sprint_planner
)

crew = Crew(
    agents=[sprint_planner],
    tasks=[planning_task],
    verbose=True
)

result = crew.kickoff()

使用场景

统一集成访问

  • 通过单一统一 API 访问数百种第三方工具，无需管理多个 SDK
  • 让智能体从一个集成点使用 Linear、GitHub、Slack、Notion、Jira、Asana 等工具
  • 由 Agent Handler 管理身份认证和 API 版本控制，降低集成复杂度

安全的企业版工作流

  • 利用内置的身份认证和权限管理来管理所有第三方集成
  • 通过集中式访问控制和审计日志维持企业安全标准
  • 让智能体访问公司工具，而无需在代码中暴露 API 密钥或凭据

跨平台自动化

  • 构建跨越多个平台的工作流（例如，根据 Linear 任务创建 GitHub issue，将 Notion 页面同步到 Slack）
  • 在你的技术栈中实现不同工具之间的无缝数据流
  • 创建能够理解跨平台上下文的智能自动化

动态工具发现

  • 在运行时加载所有可用工具，无需硬编码集成逻辑
  • 让智能体在 Tool Pack 中新增工具时发现并使用它们
  • 构建能够适应工具可用性变化的灵活智能体

用户特定的工具访问权限

  • 不同用户可以拥有不同的工具权限和访问级别
  • 支持多租户工作流，使智能体代表特定用户执行操作
  • 为所有工具操作维护正确的归属和权限

可用集成

Merge Agent Handler 支持跨多个类别的数百种集成：

  • 项目管理：Linear、Jira、Asana、Monday.com、ClickUp
  • 代码管理：GitHub、GitLab、Bitbucket
  • 沟通协作：Slack、Microsoft Teams、Discord
  • 文档：Notion、Confluence、Google Docs
  • CRM：Salesforce、HubSpot、Pipedrive
  • 以及更多……

访问 Merge Agent Handler 文档 获取可用集成的完整列表。

错误处理

该工具提供全面的错误处理：

  • 身份认证错误：API 密钥无效或缺失
  • 权限错误：用户对所请求的操作没有权限
  • API 错误：与 Agent Handler 或第三方服务通信时出现问题
  • 校验错误：传递给工具方法的参数无效

所有错误都包装为 MergeAgentHandlerToolError，以提供一致的错误处理。

友情链接

  • Agents.md面向 AI 编码助手的仓库说明文件规范
  • LangChainLangChain 是一个开放的Agent平台
  • LangSmithAgent 工程平台：可观测与评估、部署、Fleet、Engine 等
  • EmbabelEmbabel 是一个JVM平台Agent框架
  • SpringAISpringAI 是一个基于 Spring 的 AI 框架
  • MCPModel Context Protocol，连接 AI 应用与外部数据/工具的开放标准
  • LangChain4jJava 生态的 LLM 应用开发框架
  • LlamaIndex把数据接入 LLM 的框架与文档平台
  • LlamaParse智能体式 OCR 文档解析：把 PDF、扫描件变成 LLM 可用的文本与结构化数据
  • LiteParse本地优先、轻量的文档解析库，不需要 API key
  • CrewAI多智能体编排框架：以 Crew/Flow 组织自主协作的 AI Agent
  • MAFMicrosoft Agent Framework，企业级 .NET/Python 智能体框架

BytesRouter 是社区翻译站点，所有译文仅供参考，一切以官方英文原文为准。

© 2026 BytesRouter · 译文采用 CC BY 4.0 许可