{"record":{"id":"1cf98905ceb82ccf","repo":"crewAIInc/crewAI","slug":"agent-handler-api-key-environment-variable-is-requ","errorCode":null,"errorMessage":"AGENT_HANDLER_API_KEY environment variable is required. Set it with: export AGENT_HANDLER_API_KEY='your-key-here'","messagePattern":"AGENT_HANDLER_API_KEY environment variable is required\\. Set it with: export AGENT_HANDLER_API_KEY='your-key-here'","errorType":"exception","errorClass":"MergeAgentHandlerToolError","httpStatus":null,"severity":"error","filePath":"lib/crewai-tools/src/crewai_tools/tools/merge_agent_handler_tool/merge_agent_handler_tool.py","lineNumber":67,"sourceCode":"                description=\"Production API key for Agent Handler services\",\n                required=True,\n            ),\n        ]\n    )\n\n    def model_post_init(self, __context: Any) -> None:\n        \"\"\"Initialize session ID if not provided.\"\"\"\n        super().model_post_init(__context)\n        if self.session_id is None:\n            self.session_id = str(uuid4())\n\n    def _get_api_key(self) -> str:\n        \"\"\"Get the API key from environment variables.\"\"\"\n        import os\n\n        api_key = os.environ.get(\"AGENT_HANDLER_API_KEY\")\n        if not api_key:\n            raise MergeAgentHandlerToolError(\n                \"AGENT_HANDLER_API_KEY environment variable is required. \"\n                \"Set it with: export AGENT_HANDLER_API_KEY='your-key-here'\"\n            )\n        return api_key\n\n    def _make_mcp_request(\n        self, method: str, params: dict[str, Any] | None = None\n    ) -> dict[str, Any]:\n        \"\"\"Make a JSON-RPC 2.0 MCP request to Agent Handler.\"\"\"\n        url = f\"{self.base_url}/api/v1/tool-packs/{self.tool_pack_id}/registered-users/{self.registered_user_id}/mcp\"\n\n        headers = {\n            \"Content-Type\": \"application/json\",\n            \"Authorization\": f\"Bearer {self._get_api_key()}\",\n            \"Mcp-Session-Id\": self.session_id or str(uuid4()),\n        }\n\n        payload: dict[str, Any] = {","sourceCodeStart":49,"sourceCodeEnd":85,"githubUrl":"https://github.com/crewAIInc/crewAI/blob/754d7323beb2fd042e33444a115ea2d5a47193f0/lib/crewai-tools/src/crewai_tools/tools/merge_agent_handler_tool/merge_agent_handler_tool.py#L49-L85","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","solutions":["export AGENT_HANDLER_API_KEY='your-key' (or add it to .env and ensure load_dotenv() runs before the tool executes)","Add the variable to your deployment's secret store (GitHub Actions secrets, Docker env, etc.)","Verify inside the process: assert os.environ.get('AGENT_HANDLER_API_KEY') before invoking the tool"],"exampleFix":"# before\n# AGENT_HANDLER_API_KEY not set\ntools = MergeAgentHandlerTool.from_tool_name(...)  # MergeAgentHandlerToolError\n\n# after\nimport os\nfrom dotenv import load_dotenv\nload_dotenv()  # .env contains AGENT_HANDLER_API_KEY=...\nassert os.environ.get(\"AGENT_HANDLER_API_KEY\"), \"missing key\"\ntools = MergeAgentHandlerTool.from_tool_name(...)","handlingStrategy":"validation","validationCode":"import os\n\ndef agent_handler_key_present() -> bool:\n    return bool(os.environ.get(\"AGENT_HANDLER_API_KEY\"))\n\nif not agent_handler_key_present():\n    raise SystemExit(\"Set AGENT_HANDLER_API_KEY before running\")","typeGuard":null,"tryCatchPattern":"from crewai_tools.tools.merge_agent_handler_tool.merge_agent_handler_tool import MergeAgentHandlerToolError\n\ntry:\n    result = tool._run(**kwargs)\nexcept MergeAgentHandlerToolError as e:\n    if \"AGENT_HANDLER_API_KEY\" in str(e):\n        raise SystemExit(\"Set AGENT_HANDLER_API_KEY and restart\") from e\n    raise","preventionTips":["load_dotenv() at process start, before any tool runs","Fail fast at startup on required env vars instead of at first API call","Inject secrets via the platform secret store, not hardcoded values"],"tags":["env-var","api-key","merge","configuration","crewai-tools"],"backgroundTag":null,"analyzedSha":"754d7323beb2fd042e33444a115ea2d5a47193f0","analyzedAt":"2026-08-15T04:06:56.746Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}