Merge Agent Handler 도구

Merge Agent Handler 도구 (MergeAgentHandlerTool)

CrewAI의 MergeAgentHandlerTool은 Merge의 Agent Handler 플랫폼을 통해 CrewAI 에이전트가 서드파티 통합 기능에 안전하게 접근할 수 있게 해주는 도구예요. Agent Handler는 Linear, GitHub, Slack, Notion 등 수백 개의 인기 도구를 위한 사전 구축된 보안 커넥터를 제공하며, 인증·권한·모니터링이 모두 내장되어 있답니다.

출처: 문서

본문

MergeAgentHandlerTool은 Merge의 Agent Handler 플랫폼을 통해 CrewAI 에이전트가 서드파티 통합에 안전하게 접근할 수 있게 해줍니다. Agent Handler는 Linear, GitHub, Slack, Notion 등 수백 개의 인기 도구를 위한 사전 구축된 보안 커넥터를 제공하며, 인증·권한·모니터링이 모두 내장되어 있어요.

설치 (Installation)

uv pip install 'crewai[tools]'

사전 요구사항 (Requirements)

Tool Pack이 구성된 Merge Agent Handler 계정
Agent Handler API key
Tool Pack에 연결된 등록 사용자(registered user) 최소 1명
Tool Pack에 구성된 서드파티 통합들

Agent Handler 시작하기 (Getting Started with Agent Handler)

ah.merge.dev/signup에서 Merge Agent Handler 계정에 가입하세요
Tool Pack을 만들고 필요한 통합을 구성하세요
서드파티 서비스로 인증할 사용자를 등록하세요
Agent Handler 대시보드에서 API key를 받으세요
환경변수 설정: export AGENT_HANDLER_API_KEY='your-key-here'
CrewAI에서 MergeAgentHandlerTool로 구축을 시작하세요

참고 사항 (Notes)

Tool Pack ID와 Registered User ID는 Agent Handler 대시보드에서 찾거나 API로 생성할 수 있어요
이 도구는 Agent Handler와 통신할 때 Model Context Protocol(MCP)을 사용합니다
세션 ID는 자동 생성되지만 컨텍스트 유지를 위해 커스터마이즈할 수 있어요
모든 도구 호출은 Agent Handler 플랫폼을 통해 기록되고 감사(audit) 가능합니다
도구 파라미터는 Agent Handler API에서 동적으로 발견되어 자동으로 검증됩니다

사용법 (Usage)

단일 도구 사용 (Single Tool Usage)

Tool Pack에서 특정 도구를 사용하는 방법은 다음과 같습니다.

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

# Linear 이슈 생성을 위한 도구 생성
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"
)

# 이 도구를 사용하는 CrewAI 에이전트 생성
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_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"
)

# 에이전트로 크루 생성
crew = Crew(
    agents=[project_manager],
    tasks=[create_issue_task],
    verbose=True
)

# 크루 실행
result = crew.kickoff()
print(result)

Tool Pack에서 여러 도구 로드하기 (Loading Multiple Tools from a Tool Pack)

Tool Pack의 모든 사용 가능한 도구를 한 번에 로드할 수 있어요.

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

# Tool Pack의 모든 도구 로드
tools = MergeAgentHandlerTool.from_tool_pack(
    tool_pack_id="134e0111-0f67-44f6-98f0-597000290bb3",
    registered_user_id="91b2b905-e866-40c8-8be2-efe53827a0aa"
)

# 모든 도구에 접근할 수 있는 에이전트 생성
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()

특정 도구만 로드하기 (Loading Specific Tools Only)

필요한 도구만 골라서 로드할 수 있습니다.

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

# 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()

도구 인자 (Tool Arguments)

`from_tool_name()` 메서드

Argument	Type	Required	Default	Description
tool_name	`str`	Yes	None	사용할 특정 도구의 이름 (예: "linear__create_issue")
tool_pack_id	`str`	Yes	None	Agent Handler Tool Pack의 UUID
registered_user_id	`str`	Yes	None	등록된 사용자의 UUID 또는 origin_id
base_url	`str`	No	"https://ah-api.merge.dev"	Agent Handler API의 기본 URL
session_id	`str`	No	자동 생성	컨텍스트 유지를 위한 MCP 세션 ID

`from_tool_pack()` 메서드

Argument	Type	Required	Default	Description
tool_pack_id	`str`	Yes	None	Agent Handler Tool Pack의 UUID
registered_user_id	`str`	Yes	None	등록된 사용자의 UUID 또는 origin_id
tool_names	`list[str]`	No	None	로드할 특정 도구 이름. None이면 사용 가능한 모든 도구를 로드
base_url	`str`	No	"https://ah-api.merge.dev"	Agent Handler API의 기본 URL

환경변수 (Environment Variables)

AGENT_HANDLER_API_KEY=your_api_key_here  # 인증에 필요

고급 사용법 (Advanced Usage)

서로 다른 도구 접근이 있는 멀티 에이전트 워크플로

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

# 서로 다른 에이전트를 위한 전문화된 도구 생성
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"
)

# 전문화된 에이전트 생성
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]
)

# 순차 태스크 생성
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"
)

# 순차 처리로 크루 생성
crew = Crew(
    agents=[code_reviewer, task_manager, communicator],
    tasks=[review_task, update_task, notify_task],
    process=Process.sequential,
    verbose=True
)

result = crew.kickoff()

커스텀 세션 관리 (Custom Session Management)

세션 ID를 사용해 여러 도구 호출에 걸쳐 컨텍스트를 유지할 수 있어요.

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

# 동일한 세션 ID로 도구를 생성해 컨텍스트 유지
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()

사용 사례 (Use Cases)

통합 접근 통합 (Unified Integration Access)

여러 SDK를 관리하지 않고 단일 통합 API로 수백 개의 서드파티 도구에 접근하기
하나의 통합 지점에서 Linear, GitHub, Slack, Notion, Jira, Asana 등과 에이전트가 작업하도록 하기
Agent Handler가 인증과 API 버전 관리를 처리하도록 맡겨 통합 복잡성 줄이기

안전한 엔터프라이즈 워크플로 (Secure Enterprise Workflows)

모든 서드파티 통합에 내장된 인증과 권한 관리 활용하기
중앙 집중식 접근 제어와 감사 로깅으로 엔터프라이즈 보안 기준 유지하기
코드에서 API 키나 자격 증명을 노출하지 않고 에이전트가 회사 도구에 접근하게 하기

크로스 플랫폼 자동화 (Cross-Platform Automation)

여러 플랫폼에 걸친 워크플로 구축하기 (예: Linear 태스크에서 GitHub 이슈 생성, Notion 페이지를 Slack으로 동기화)
기술 스택의 서로 다른 도구 간의 원활한 데이터 흐름 구현하기
서로 다른 플랫폼의 컨텍스트를 이해하는 지능형 자동화 만들기

동적 도구 발견 (Dynamic Tool Discovery)

통합 로직을 하드코딩하지 않고 런타임에 모든 사용 가능한 도구 로드하기
Tool Pack에 새 도구가 추가되면 에이전트가 이를 발견하고 사용하게 하기
변화하는 도구 가용성에 적응할 수 있는 유연한 에이전트 구축하기

사용자별 도구 접근 (User-Specific Tool Access)

서로 다른 사용자는 서로 다른 도구 권한과 접근 수준을 가질 수 있어요
에이전트가 특정 사용자를 대신해 행동하는 멀티테넌트 워크플로 구현하기
모든 도구 작업에 적절한 귀속(attribution)과 권한 유지하기

사용 가능한 통합 (Available Integrations)

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 문서를 참고하세요.

에러 처리 (Error Handling)

이 도구는 종합적인 에러 처리를 제공합니다.

인증 오류: 잘못되었거나 누락된 API key
권한 오류: 사용자가 요청한 작업에 대한 권한이 없음
API 오류: Agent Handler 또는 서드파티 서비스와의 통신 문제
검증 오류: 도구 메서드에 전달된 잘못된 파라미터

모든 에러는 일관된 처리를 위해 MergeAgentHandlerToolError로 감싸집니다.

Merge Agent Handler 도구