Skip to content

Commit 34b9093

Browse files
gilfeiggilfeig
authored
Add docs for the agent handler connector (#4012)
* Add docs for the agent handler connector * Fix links * Update docs
1 parent 22684b5 commit 34b9093

File tree

3 files changed

+373
-1
lines changed

3 files changed

+373
-1
lines changed

‎docs/docs.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -253,7 +253,8 @@
253253
"pages": [
254254
"en/tools/integration/overview",
255255
"en/tools/integration/bedrockinvokeagenttool",
256-
"en/tools/integration/crewaiautomationtool"
256+
"en/tools/integration/crewaiautomationtool",
257+
"en/tools/integration/mergeagenthandlertool"
257258
]
258259
},
259260
{

‎docs/en/tools/integration/mergeagenthandlertool.mdx‎

Lines changed: 367 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,367 @@
1+
---
2+
title: Merge Agent Handler Tool
3+
description: Enables CrewAI agents to securely access third-party integrations like Linear, GitHub, Slack, and more through Merge's Agent Handler platform
4+
icon: diagram-project
5+
mode: "wide"
6+
---
7+
8+
# `MergeAgentHandlerTool`
9+
10+
The `MergeAgentHandlerTool` enables CrewAI agents to securely access third-party integrations through [Merge's Agent Handler](https://www.merge.dev/products/merge-agent-handler) platform. Agent Handler provides pre-built, secure connectors to popular tools like Linear, GitHub, Slack, Notion, and hundreds more—all with built-in authentication, permissions, and monitoring.
11+
12+
## Installation
13+
14+
```bash
15+
uv pip install 'crewai[tools]'
16+
```
17+
18+
## Requirements
19+
20+
- Merge Agent Handler account with a configured Tool Pack
21+
- Agent Handler API key
22+
- At least one registered user linked to your Tool Pack
23+
- Third-party integrations configured in your Tool Pack
24+
25+
## Getting Started with Agent Handler
26+
27+
1. **Sign up** for a Merge Agent Handler account at [ah.merge.dev/signup](https://ah.merge.dev/signup)
28+
2. **Create a Tool Pack** and configure the integrations you need
29+
3. **Register users** who will authenticate with the third-party services
30+
4. **Get your API key** from the Agent Handler dashboard
31+
5. **Set environment variable**: `export AGENT_HANDLER_API_KEY='your-key-here'`
32+
6. **Start building** with the MergeAgentHandlerTool in CrewAI
33+
34+
## Notes
35+
36+
- Tool Pack IDs and Registered User IDs can be found in your Agent Handler dashboard or created via API
37+
- The tool uses the Model Context Protocol (MCP) for communication with Agent Handler
38+
- Session IDs are automatically generated but can be customized for context persistence
39+
- All tool calls are logged and auditable through the Agent Handler platform
40+
- Tool parameters are dynamically discovered from the Agent Handler API and validated automatically
41+
42+
## Usage
43+
44+
### Single Tool Usage
45+
46+
Here's how to use a specific tool from your Tool Pack:
47+
48+
```python {2, 4-9}
49+
from crewai import Agent, Task, Crew
50+
from crewai_tools import MergeAgentHandlerTool
51+
52+
# Create a tool for Linear issue creation
53+
linear_create_tool = MergeAgentHandlerTool.from_tool_name(
54+
tool_name="linear__create_issue",
55+
tool_pack_id="134e0111-0f67-44f6-98f0-597000290bb3",
56+
registered_user_id="91b2b905-e866-40c8-8be2-efe53827a0aa"
57+
)
58+
59+
# Create a CrewAI agent that uses the tool
60+
project_manager = Agent(
61+
role='Project Manager',
62+
goal='Manage project tasks and issues efficiently',
63+
backstory='I am an expert at tracking project work and creating actionable tasks.',
64+
tools=[linear_create_tool],
65+
verbose=True
66+
)
67+
68+
# Create a task for the agent
69+
create_issue_task = Task(
70+
description="Create a new high-priority issue in Linear titled 'Implement user authentication' with a detailed description of the requirements.",
71+
agent=project_manager,
72+
expected_output="Confirmation that the issue was created with its ID"
73+
)
74+
75+
# Create a crew with the agent
76+
crew = Crew(
77+
agents=[project_manager],
78+
tasks=[create_issue_task],
79+
verbose=True
80+
)
81+
82+
# Run the crew
83+
result = crew.kickoff()
84+
print(result)
85+
```
86+
87+
### Loading Multiple Tools from a Tool Pack
88+
89+
You can load all available tools from your Tool Pack at once:
90+
91+
```python {2, 4-8}
92+
from crewai import Agent, Task, Crew
93+
from crewai_tools import MergeAgentHandlerTool
94+
95+
# Load all tools from the Tool Pack
96+
tools = MergeAgentHandlerTool.from_tool_pack(
97+
tool_pack_id="134e0111-0f67-44f6-98f0-597000290bb3",
98+
registered_user_id="91b2b905-e866-40c8-8be2-efe53827a0aa"
99+
)
100+
101+
# Create an agent with access to all tools
102+
automation_expert = Agent(
103+
role='Automation Expert',
104+
goal='Automate workflows across multiple platforms',
105+
backstory='I can work with any tool in the toolbox to get things done.',
106+
tools=tools,
107+
verbose=True
108+
)
109+
110+
automation_task = Task(
111+
description="Check for any high-priority issues in Linear and post a summary to Slack.",
112+
agent=automation_expert
113+
)
114+
115+
crew = Crew(
116+
agents=[automation_expert],
117+
tasks=[automation_task],
118+
verbose=True
119+
)
120+
121+
result = crew.kickoff()
122+
```
123+
124+
### Loading Specific Tools Only
125+
126+
Load only the tools you need:
127+
128+
```python {2, 4-10}
129+
from crewai import Agent, Task, Crew
130+
from crewai_tools import MergeAgentHandlerTool
131+
132+
# Load specific tools from the Tool Pack
133+
selected_tools = MergeAgentHandlerTool.from_tool_pack(
134+
tool_pack_id="134e0111-0f67-44f6-98f0-597000290bb3",
135+
registered_user_id="91b2b905-e866-40c8-8be2-efe53827a0aa",
136+
tool_names=["linear__create_issue", "linear__get_issues", "slack__post_message"]
137+
)
138+
139+
developer_assistant = Agent(
140+
role='Developer Assistant',
141+
goal='Help developers track and communicate about their work',
142+
backstory='I help developers stay organized and keep the team informed.',
143+
tools=selected_tools,
144+
verbose=True
145+
)
146+
147+
daily_update_task = Task(
148+
description="Get all issues assigned to the current user in Linear and post a summary to the #dev-updates Slack channel.",
149+
agent=developer_assistant
150+
)
151+
152+
crew = Crew(
153+
agents=[developer_assistant],
154+
tasks=[daily_update_task],
155+
verbose=True
156+
)
157+
158+
result = crew.kickoff()
159+
```
160+
161+
## Tool Arguments
162+
163+
### `from_tool_name()` Method
164+
165+
| Argument | Type | Required | Default | Description |
166+
|:---------|:-----|:---------|:--------|:------------|
167+
| **tool_name** | `str` | Yes | None | Name of the specific tool to use (e.g., "linear__create_issue") |
168+
| **tool_pack_id** | `str` | Yes | None | UUID of your Agent Handler Tool Pack |
169+
| **registered_user_id** | `str` | Yes | None | UUID or origin_id of the registered user |
170+
| **base_url** | `str` | No | "https://ah-api.merge.dev" | Base URL for Agent Handler API |
171+
| **session_id** | `str` | No | Auto-generated | MCP session ID for maintaining context |
172+
173+
### `from_tool_pack()` Method
174+
175+
| Argument | Type | Required | Default | Description |
176+
|:---------|:-----|:---------|:--------|:------------|
177+
| **tool_pack_id** | `str` | Yes | None | UUID of your Agent Handler Tool Pack |
178+
| **registered_user_id** | `str` | Yes | None | UUID or origin_id of the registered user |
179+
| **tool_names** | `list[str]` | No | None | Specific tool names to load. If None, loads all available tools |
180+
| **base_url** | `str` | No | "https://ah-api.merge.dev" | Base URL for Agent Handler API |
181+
182+
## Environment Variables
183+
184+
```bash
185+
AGENT_HANDLER_API_KEY=your_api_key_here # Required for authentication
186+
```
187+
188+
## Advanced Usage
189+
190+
### Multi-Agent Workflow with Different Tool Access
191+
192+
```python {2, 4-20}
193+
from crewai import Agent, Task, Crew, Process
194+
from crewai_tools import MergeAgentHandlerTool
195+
196+
# Create specialized tools for different agents
197+
github_tools = MergeAgentHandlerTool.from_tool_pack(
198+
tool_pack_id="134e0111-0f67-44f6-98f0-597000290bb3",
199+
registered_user_id="91b2b905-e866-40c8-8be2-efe53827a0aa",
200+
tool_names=["github__create_pull_request", "github__get_pull_requests"]
201+
)
202+
203+
linear_tools = MergeAgentHandlerTool.from_tool_pack(
204+
tool_pack_id="134e0111-0f67-44f6-98f0-597000290bb3",
205+
registered_user_id="91b2b905-e866-40c8-8be2-efe53827a0aa",
206+
tool_names=["linear__create_issue", "linear__update_issue"]
207+
)
208+
209+
slack_tool = MergeAgentHandlerTool.from_tool_name(
210+
tool_name="slack__post_message",
211+
tool_pack_id="134e0111-0f67-44f6-98f0-597000290bb3",
212+
registered_user_id="91b2b905-e866-40c8-8be2-efe53827a0aa"
213+
)
214+
215+
# Create specialized agents
216+
code_reviewer = Agent(
217+
role='Code Reviewer',
218+
goal='Review pull requests and ensure code quality',
219+
backstory='I am an expert at reviewing code changes and providing constructive feedback.',
220+
tools=github_tools
221+
)
222+
223+
task_manager = Agent(
224+
role='Task Manager',
225+
goal='Track and update project tasks based on code changes',
226+
backstory='I keep the project board up to date with the latest development progress.',
227+
tools=linear_tools
228+
)
229+
230+
communicator = Agent(
231+
role='Team Communicator',
232+
goal='Keep the team informed about important updates',
233+
backstory='I make sure everyone knows what is happening in the project.',
234+
tools=[slack_tool]
235+
)
236+
237+
# Create sequential tasks
238+
review_task = Task(
239+
description="Review all open pull requests in the 'api-service' repository and identify any that need attention.",
240+
agent=code_reviewer,
241+
expected_output="List of pull requests that need review or have issues"
242+
)
243+
244+
update_task = Task(
245+
description="Update Linear issues based on the pull request review findings. Mark completed PRs as done.",
246+
agent=task_manager,
247+
expected_output="Summary of updated Linear issues"
248+
)
249+
250+
notify_task = Task(
251+
description="Post a summary of today's code review and task updates to the #engineering Slack channel.",
252+
agent=communicator,
253+
expected_output="Confirmation that the message was posted"
254+
)
255+
256+
# Create a crew with sequential processing
257+
crew = Crew(
258+
agents=[code_reviewer, task_manager, communicator],
259+
tasks=[review_task, update_task, notify_task],
260+
process=Process.sequential,
261+
verbose=True
262+
)
263+
264+
result = crew.kickoff()
265+
```
266+
267+
### Custom Session Management
268+
269+
Maintain context across multiple tool calls using session IDs:
270+
271+
```python {2, 4-17}
272+
from crewai import Agent, Task, Crew
273+
from crewai_tools import MergeAgentHandlerTool
274+
275+
# Create tools with the same session ID to maintain context
276+
session_id = "project-sprint-planning-2024"
277+
278+
create_tool = MergeAgentHandlerTool(
279+
name="linear_create_issue",
280+
description="Creates a new issue in Linear",
281+
tool_name="linear__create_issue",
282+
tool_pack_id="134e0111-0f67-44f6-98f0-597000290bb3",
283+
registered_user_id="91b2b905-e866-40c8-8be2-efe53827a0aa",
284+
session_id=session_id
285+
)
286+
287+
update_tool = MergeAgentHandlerTool(
288+
name="linear_update_issue",
289+
description="Updates an existing issue in Linear",
290+
tool_name="linear__update_issue",
291+
tool_pack_id="134e0111-0f67-44f6-98f0-597000290bb3",
292+
registered_user_id="91b2b905-e866-40c8-8be2-efe53827a0aa",
293+
session_id=session_id
294+
)
295+
296+
sprint_planner = Agent(
297+
role='Sprint Planner',
298+
goal='Plan and organize sprint tasks',
299+
backstory='I help teams plan effective sprints with well-defined tasks.',
300+
tools=[create_tool, update_tool],
301+
verbose=True
302+
)
303+
304+
planning_task = Task(
305+
description="Create 5 sprint tasks for the authentication feature and set their priorities based on dependencies.",
306+
agent=sprint_planner
307+
)
308+
309+
crew = Crew(
310+
agents=[sprint_planner],
311+
tasks=[planning_task],
312+
verbose=True
313+
)
314+
315+
result = crew.kickoff()
316+
```
317+
318+
## Use Cases
319+
320+
### Unified Integration Access
321+
- Access hundreds of third-party tools through a single unified API without managing multiple SDKs
322+
- Enable agents to work with Linear, GitHub, Slack, Notion, Jira, Asana, and more from one integration point
323+
- Reduce integration complexity by letting Agent Handler manage authentication and API versioning
324+
325+
### Secure Enterprise Workflows
326+
- Leverage built-in authentication and permission management for all third-party integrations
327+
- Maintain enterprise security standards with centralized access control and audit logging
328+
- Enable agents to access company tools without exposing API keys or credentials in code
329+
330+
### Cross-Platform Automation
331+
- Build workflows that span multiple platforms (e.g., create GitHub issues from Linear tasks, sync Notion pages to Slack)
332+
- Enable seamless data flow between different tools in your tech stack
333+
- Create intelligent automation that understands context across different platforms
334+
335+
### Dynamic Tool Discovery
336+
- Load all available tools at runtime without hardcoding integration logic
337+
- Enable agents to discover and use new tools as they're added to your Tool Pack
338+
- Build flexible agents that can adapt to changing tool availability
339+
340+
### User-Specific Tool Access
341+
- Different users can have different tool permissions and access levels
342+
- Enable multi-tenant workflows where agents act on behalf of specific users
343+
- Maintain proper attribution and permissions for all tool actions
344+
345+
## Available Integrations
346+
347+
Merge Agent Handler supports hundreds of integrations across multiple categories:
348+
349+
- **Project Management**: Linear, Jira, Asana, Monday.com, ClickUp
350+
- **Code Management**: GitHub, GitLab, Bitbucket
351+
- **Communication**: Slack, Microsoft Teams, Discord
352+
- **Documentation**: Notion, Confluence, Google Docs
353+
- **CRM**: Salesforce, HubSpot, Pipedrive
354+
- **And many more...**
355+
356+
Visit the [Merge Agent Handler documentation](https://docs.ah.merge.dev/) for a complete list of available integrations.
357+
358+
## Error Handling
359+
360+
The tool provides comprehensive error handling:
361+
362+
- **Authentication Errors**: Invalid or missing API keys
363+
- **Permission Errors**: User lacks permission for the requested action
364+
- **API Errors**: Issues communicating with Agent Handler or third-party services
365+
- **Validation Errors**: Invalid parameters passed to tool methods
366+
367+
All errors are wrapped in `MergeAgentHandlerToolError` for consistent error handling.

‎docs/en/tools/integration/overview.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,10 @@ Integration tools let your agents hand off work to other automation platforms an
1010
## **Available Tools**
1111

1212
<CardGroup cols={2}>
13+
<Card title="Merge Agent Handler Tool" icon="diagram-project" href="/en/tools/integration/mergeagenthandlertool">
14+
Securely access hundreds of third-party tools like Linear, GitHub, Slack, and more through Merge's unified API.
15+
</Card>
16+
1317
<Card title="CrewAI Run Automation Tool" icon="robot" href="/en/tools/integration/crewaiautomationtool">
1418
Invoke live CrewAI Platform automations, pass custom inputs, and poll for results directly from your agent.
1519
</Card>

0 commit comments

Comments
 (0)