datawhalechina/hello-agents · error · HTTPException

服务不可用: {str(e)}

Error message

服务不可用: {str(e)}

What it means

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.

Source

Thrown at code/chapter13/helloagents-trip-planner/backend/app/api/routes/trip.py:82

@router.get(
    "/health",
    summary="健康检查",
    description="检查旅行规划服务是否正常"
)
async def health_check():
    """健康检查"""
    try:
        # 检查Agent是否可用
        agent = get_trip_planner_agent()
        
        return {
            "status": "healthy",
            "service": "trip-planner",
            "agent_name": agent.agent.name,
            "tools_count": len(agent.agent.list_tools())
        }
    except Exception as e:
        raise HTTPException(
            status_code=503,
            detail=f"服务不可用: {str(e)}"
        )

View on GitHub (pinned to 606a07d341)

Solutions

  1. Ensure backend/.env sets AMAP_API_KEY and LLM_API_KEY (or OPENAI_API_KEY) — see config validation warnings
  2. Check backend logs for the underlying exception raised during get_trip_planner_agent()
  3. Verify `uvx amap-mcp-server` runs on the host
  4. Pin the agent framework version; the check relies on list_tools() existing

Example fix

# before
# container readiness probe hits /trip/health, fails, but pod keeps restarting with no info

# after
# log the cause at startup so the 503 is self-explanatory
try:
    agent = get_trip_planner_agent()
except Exception as e:
    logging.exception('Trip agent init failed')
    raise HTTPException(status_code=503, detail=f'服务不可用: {str(e)}')
Defensive patterns

Strategy: try-catch

Validate before calling

import requests

h = requests.get(f'{BASE}/trip/health', timeout=5)
if h.status_code == 503:
    raise SystemExit(f'trip-planner unhealthy: {h.json().get("detail")}')
# only send /trip/plan traffic when healthy

Try / catch

r = requests.get(f'{BASE}/trip/health')
if r.status_code == 503:
    detail = r.json().get('detail', '')
    if 'KEY' in detail.upper() or 'API_KEY' in detail:
        fix_env_and_restart()      # AMAP_API_KEY / LLM_API_KEY
    else:
        check_agent_framework_version()

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of datawhalechina/hello-agents@606a07d341 (2026-08-14). Data as JSON: /api/errors/e57329002459de40. Report an issue: GitHub.