crewAIInc/crewAI · error · MergeAgentHandlerToolError

AGENT_HANDLER_API_KEY environment variable is required. Set

Error message

AGENT_HANDLER_API_KEY environment variable is required. Set it with: export AGENT_HANDLER_API_KEY='your-key-here'

What it means

MergeAgentHandlerTool reads its API key from the AGENT_HANDLER_API_KEY environment variable at request time (_get_api_key). If the variable is unset or empty, it raises MergeAgentHandlerToolError with the exact export command. Unlike api-key-constructor tools, there is no parameter fallback — env only.

Source

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

                description="Production API key for Agent Handler services",
                required=True,
            ),
        ]
    )

    def model_post_init(self, __context: Any) -> None:
        """Initialize session ID if not provided."""
        super().model_post_init(__context)
        if self.session_id is None:
            self.session_id = str(uuid4())

    def _get_api_key(self) -> str:
        """Get the API key from environment variables."""
        import os

        api_key = os.environ.get("AGENT_HANDLER_API_KEY")
        if not api_key:
            raise MergeAgentHandlerToolError(
                "AGENT_HANDLER_API_KEY environment variable is required. "
                "Set it with: export AGENT_HANDLER_API_KEY='your-key-here'"
            )
        return api_key

    def _make_mcp_request(
        self, method: str, params: dict[str, Any] | None = None
    ) -> dict[str, Any]:
        """Make a JSON-RPC 2.0 MCP request to Agent Handler."""
        url = f"{self.base_url}/api/v1/tool-packs/{self.tool_pack_id}/registered-users/{self.registered_user_id}/mcp"

        headers = {
            "Content-Type": "application/json",
            "Authorization": f"Bearer {self._get_api_key()}",
            "Mcp-Session-Id": self.session_id or str(uuid4()),
        }

        payload: dict[str, Any] = {

View on GitHub (pinned to 754d7323be)

Solutions

1. export AGENT_HANDLER_API_KEY='your-key' (or add it to .env and ensure load_dotenv() runs before the tool executes)
2. Add the variable to your deployment's secret store (GitHub Actions secrets, Docker env, etc.)
3. Verify inside the process: assert os.environ.get('AGENT_HANDLER_API_KEY') before invoking the tool

Example fix

# before
# AGENT_HANDLER_API_KEY not set
tools = MergeAgentHandlerTool.from_tool_name(...)  # MergeAgentHandlerToolError

# after
import os
from dotenv import load_dotenv
load_dotenv()  # .env contains AGENT_HANDLER_API_KEY=...
assert os.environ.get("AGENT_HANDLER_API_KEY"), "missing key"
tools = MergeAgentHandlerTool.from_tool_name(...)

import os

def agent_handler_key_present() -> bool:
    return bool(os.environ.get("AGENT_HANDLER_API_KEY"))

if not agent_handler_key_present():
    raise SystemExit("Set AGENT_HANDLER_API_KEY before running")

from crewai_tools.tools.merge_agent_handler_tool.merge_agent_handler_tool import MergeAgentHandlerToolError

try:
    result = tool._run(**kwargs)
except MergeAgentHandlerToolError as e:
    if "AGENT_HANDLER_API_KEY" in str(e):
        raise SystemExit("Set AGENT_HANDLER_API_KEY and restart") from e
    raise

When it happens

Trigger: Any call that triggers _make_mcp_request (e.g. _run, from_tool_name's tools/list) without AGENT_HANDLER_API_KEY in os.environ; setting the variable after the process started without restart; deploying where dotenv is loaded after tool construction and the request fires before.

Common situations: Missing .env entry or forgetting to load_dotenv() before running; CI/containers where the secret was not injected; shell-specific export mistakes (quotes inside value).

Related errors

• `api_key` is required, please set the `HYPERBROWSER_API_KEY`
• Failed to fetch tools from Agent Handler Tool Pack
• No appropriate API key found for model. Please set OPENAI_AP
• API key must be provided either through constructor or MINDS
• BRAVE_API_KEY environment variable is required for BraveSear

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