{"record":{"id":"c827f67166566bf5","repo":"bytedance/deer-flow","slug":"custom-agent-management-api-is-disabled-set-agent","errorCode":null,"errorMessage":"Custom-agent management API is disabled. Set agents_api.enabled=true to expose agent and user-profile routes over HTTP.","messagePattern":"Custom-agent management API is disabled\\. Set agents_api\\.enabled=true to expose agent and user-profile routes over HTTP\\.","errorType":"http","errorClass":"HTTPException","httpStatus":403,"severity":"error","filePath":"backend/app/gateway/routers/agents.py","lineNumber":109,"sourceCode":"    Raises:\n        HTTPException: 422 if the name is invalid.\n    \"\"\"\n    if not AGENT_NAME_PATTERN.match(name):\n        raise HTTPException(\n            status_code=422,\n            detail=f\"Invalid agent name '{name}'. Must match ^[A-Za-z0-9-]+$ (letters, digits, and hyphens only).\",\n        )\n\n\ndef _normalize_agent_name(name: str) -> str:\n    \"\"\"Normalize agent name to lowercase for filesystem storage.\"\"\"\n    return name.lower()\n\n\ndef _require_agents_api_enabled() -> None:\n    \"\"\"Reject access unless the custom-agent management API is explicitly enabled.\"\"\"\n    if not get_agents_api_config().enabled:\n        raise HTTPException(\n            status_code=403,\n            detail=(\"Custom-agent management API is disabled. Set agents_api.enabled=true to expose agent and user-profile routes over HTTP.\"),\n        )\n\n\ndef _validate_model_exists(model: str | None) -> None:\n    \"\"\"Reject an agent ``model`` that is not a configured profile.\n\n    Mirrors the ``update_agent`` harness tool: without this, an unknown model\n    silently falls back to the default at runtime and the user sees confusing\n    repeated warnings on every later turn instead of an actionable error here.\n    ``None``/empty means \"use the global default\" and is always allowed.\n\n    Best-effort: if the app config cannot be loaded (e.g. no ``config.yaml`` on\n    disk in a bare/test deployment), skip the check rather than failing the\n    write — the runtime still falls back to the default for an unknown model.\n    \"\"\"\n    if not model:","sourceCodeStart":91,"sourceCodeEnd":127,"githubUrl":"https://github.com/bytedance/deer-flow/blob/1dd6ba1acb03700589994b0366c5d1c7d05e2eff/backend/app/gateway/routers/agents.py#L91-L127","documentation":"403 from `_require_agents_api_enabled`, called at the top of every agent and user-profile route. The custom-agent management API is opt-in: unless `agents_api.enabled=true` is set in config, the routes exist but refuse all requests. This is a deliberate off-by-default posture for an HTTP surface that writes agent configs.","triggerScenarios":"Calling any `/agents*` or `/user-profile` endpoint on a default deployment where `agents_api.enabled` was never set; a config.yaml regenerated from the example template that leaves the flag commented out.","commonSituations":"Fresh installs assuming the agent CRUD API is available; upgrading to a version that gated the API behind config; test environments booting with minimal config.","solutions":["Edit config.yaml and set `agents_api.enabled: true`, then restart the Gateway","If you did not intend to expose this API, keep it disabled and use the in-chat `update_agent` tools instead","After enabling, verify with a GET `/agents` call before wiring the frontend"],"exampleFix":"# config.yaml — before\nagents_api:\n  enabled: false\n# after\nagents_api:\n  enabled: true","handlingStrategy":"validation","validationCode":"// Probe once at client startup\nconst probe = await fetch(`${base}/api/agents`, { credentials: 'include' });\nif (probe.status === 403 && /disabled/.test(await probe.text())) {\n  agentsApiEnabled = false; // hide agent-management UI\n}","typeGuard":null,"tryCatchPattern":"try { return await api.listAgents(); }\ncatch (e) {\n  if (e.status === 403 && /agents_api.enabled/.test(e.detail)) return { agents: [], disabled: true };\n  throw e;\n}","preventionTips":["Enable agents_api in config.yaml before deploying any UI that calls agent routes","Gate the agent-management UI behind a startup capability probe","Keep the flag in the deployment checklist, not in tribal memory"],"tags":["config","http-403","feature-flag","agents"],"backgroundTag":null,"analyzedSha":"1dd6ba1acb03700589994b0366c5d1c7d05e2eff","analyzedAt":"2026-08-14T21:20:34.804Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}