{"record":{"id":"e57329002459de40","repo":"datawhalechina/hello-agents","slug":"str-e-e57329","errorCode":null,"errorMessage":"服务不可用: {str(e)}","messagePattern":"服务不可用: (.+?)","errorType":"http","errorClass":"HTTPException","httpStatus":503,"severity":"error","filePath":"code/chapter13/helloagents-trip-planner/backend/app/api/routes/trip.py","lineNumber":82,"sourceCode":"@router.get(\n    \"/health\",\n    summary=\"健康检查\",\n    description=\"检查旅行规划服务是否正常\"\n)\nasync def health_check():\n    \"\"\"健康检查\"\"\"\n    try:\n        # 检查Agent是否可用\n        agent = get_trip_planner_agent()\n        \n        return {\n            \"status\": \"healthy\",\n            \"service\": \"trip-planner\",\n            \"agent_name\": agent.agent.name,\n            \"tools_count\": len(agent.agent.list_tools())\n        }\n    except Exception as e:\n        raise HTTPException(\n            status_code=503,\n            detail=f\"服务不可用: {str(e)}\"\n        )\n\n","sourceCodeStart":64,"sourceCodeEnd":87,"githubUrl":"https://github.com/datawhalechina/hello-agents/blob/606a07d341a47be773fab7f4b71177f53f96b2c3/code/chapter13/helloagents-trip-planner/backend/app/api/routes/trip.py#L64-L87","documentation":"HTTPException(503) raised by GET /trip/health when the trip planner agent cannot be initialized — get_trip_planner_agent() throws during construction (LLM config, tool registration) or the introspection agent.agent.name / agent.agent.list_tools() fails. Like the map health check it probes internals, so structural changes in the underlying agent framework also surface here.","triggerScenarios":"LLM_API_KEY/OPENAI_API_KEY missing so agent construction fails; Amap MCP tool init failing (missing AMAP_API_KEY, uvx unavailable); framework version change removing list_tools() or renaming .name.","commonSituations":"Deploying without .env; container missing uvx; upgrading the agent library with breaking API changes; using /trip/health in a readiness probe so bad config prevents rollout — which is the intended behavior.","solutions":["Ensure backend/.env sets AMAP_API_KEY and LLM_API_KEY (or OPENAI_API_KEY) — see config validation warnings","Check backend logs for the underlying exception raised during get_trip_planner_agent()","Verify `uvx amap-mcp-server` runs on the host","Pin the agent framework version; the check relies on list_tools() existing"],"exampleFix":"# before\n# container readiness probe hits /trip/health, fails, but pod keeps restarting with no info\n\n# after\n# log the cause at startup so the 503 is self-explanatory\ntry:\n    agent = get_trip_planner_agent()\nexcept Exception as e:\n    logging.exception('Trip agent init failed')\n    raise HTTPException(status_code=503, detail=f'服务不可用: {str(e)}')","handlingStrategy":"try-catch","validationCode":"import requests\n\nh = requests.get(f'{BASE}/trip/health', timeout=5)\nif h.status_code == 503:\n    raise SystemExit(f'trip-planner unhealthy: {h.json().get(\"detail\")}')\n# only send /trip/plan traffic when healthy","typeGuard":null,"tryCatchPattern":"r = requests.get(f'{BASE}/trip/health')\nif r.status_code == 503:\n    detail = r.json().get('detail', '')\n    if 'KEY' in detail.upper() or 'API_KEY' in detail:\n        fix_env_and_restart()      # AMAP_API_KEY / LLM_API_KEY\n    else:\n        check_agent_framework_version()","preventionTips":["Use /trip/health as a readiness gate in deployments and CI smoke tests","Keep AMAP_API_KEY + LLM_API_KEY in backend/.env and validate at boot","Pin the agent framework version — the probe calls list_tools()/name directly"],"tags":["fastapi","http-503","health-check","agent","readiness"],"backgroundTag":null,"analyzedSha":"606a07d341a47be773fab7f4b71177f53f96b2c3","analyzedAt":"2026-08-14T22:57:27.446Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}