What causes "Failed to communicate with Agent Handler API: {e!s}" in crewAIInc/crewAI?

Retry the call — transient network/5xx failures are the most common cause (wrap in retry with backoff)

crewAIInc/crewAI · error · MergeAgentHandlerToolError

Failed to communicate with Agent Handler API: {e!s}

Error message

Failed to communicate with Agent Handler API: {e!s}

What it means

Wraps any requests.exceptions.RequestException (connection error, DNS failure, timeout after 60s, TLS error, 4xx/5xx from raise_for_status) encountered while POSTing the JSON-RPC payload to the Agent Handler API. The original exception is chained, so the network-level cause is preserved in __cause__.

Source

Thrown at lib/crewai-tools/src/crewai_tools/tools/merge_agent_handler_tool/merge_agent_handler_tool.py:113

        try:
            response = requests.post(url, json=payload, headers=headers, timeout=60)
            response.raise_for_status()
            result = response.json()

            if "error" in result:
                error_msg = result["error"].get("message", "Unknown error")
                error_code = result["error"].get("code", -1)
                logger.error(
                    f"Agent Handler API error (code {error_code}): {error_msg}"
                )
                raise MergeAgentHandlerToolError(f"API Error: {error_msg}")

            return cast(dict[str, Any], result)

        except requests.exceptions.RequestException as e:
            logger.error(f"Failed to call Agent Handler API: {e!s}")
            raise MergeAgentHandlerToolError(
                f"Failed to communicate with Agent Handler API: {e!s}"
            ) from e

    def _run(self, **kwargs: Any) -> Any:
        """Execute the Agent Handler tool with the given arguments."""
        try:
            logger.info(f"Executing {self.tool_name} with arguments: {kwargs}")

            result = self._make_mcp_request(
                method="tools/call",
                params={"name": self.tool_name, "arguments": kwargs},
            )

            if "result" in result and "content" in result["result"]:
                content = result["result"]["content"]
                if content and len(content) > 0:
                    text_content = content[0].get("text", "")
                    try:

View on GitHub (pinned to 754d7323be)

Solutions

Retry the call — transient network/5xx failures are the most common cause (wrap in retry with backoff)
Verify connectivity: curl -v https://ah-api.merge.dev from the same host/proxy settings
If a custom base_url is set, check it for typos and that it speaks the same /api/v1/... contract
For slow tools, reduce payload or accept that calls over 60s will always time out and need a different approach

Example fix

# before
result = tool._run(**kwargs)  # MergeAgentHandlerToolError on blip

# after
import time
from crewai_tools.tools.merge_agent_handler_tool.merge_agent_handler_tool import MergeAgentHandlerToolError

for attempt in range(3):
    try:
        result = tool._run(**kwargs)
        break
    except MergeAgentHandlerToolError as e:
        if "Failed to communicate" not in str(e) or attempt == 2:
            raise
        time.sleep(2 ** attempt)

Defensive patterns

Strategy: retry

Validate before calling

import socket, requests

def endpoint_reachable(base_url: str = "https://ah-api.merge.dev", timeout: float = 5.0) -> bool:
    try:
        requests.get(base_url, timeout=timeout)
        return True
    except requests.exceptions.RequestException:
        return False

Try / catch

import time
from crewai_tools.tools.merge_agent_handler_tool.merge_agent_handler_tool import MergeAgentHandlerToolError

last = None
for attempt in range(3):
    try:
        result = tool._run(**kwargs)
        break
    except MergeAgentHandlerToolError as e:
        if "Failed to communicate" not in str(e):
            raise
        last = e
        time.sleep(2 ** attempt)
else:
    raise last

Prevention

Wrap Agent Handler calls in bounded exponential-backoff retry
Add a pre-flight connectivity check to base_url in deployment healthchecks
Keep calls under the 60s client timeout or split large workloads

When it happens

Trigger: Base URL unreachable (custom base_url wrong, DNS failure); corporate proxy/firewall blocking https://ah-api.merge.dev; the 60-second timeout exceeded by a slow tool pack call; server-side 5xx causing raise_for_status() to raise HTTPError.

Common situations: Ephemeral network blips in long-running agent jobs; air-gapped or proxied environments; typos in a custom base_url; transient Merge API incidents.

Related errors

AI-assisted analysis of crewAIInc/crewAI@754d7323be (2026-08-15). Data as JSON: /api/errors/2ac741b87969e386. Report an issue: GitHub.