datawhalechina/hello-agents · error · HTTPException

Agent not initialized

Error message

Agent not initialized

What it means

Raised by POST /api/session/create when the module-level get_agent() returns None — the global HelloClawAgent singleton has not been initialized in this server process. Session creation requires a live agent (it may summarize the previous session via the LLM), so there is no degraded path; the route answers HTTP 500 immediately.

Source

Thrown at Co-creation-projects/tino-chen-HelloClaw/src/api/session.py:117

            updated_at=s["updated_at"]
        )
        for s in sessions
    ])


@router.post("/create", response_model=SessionCreateResponse)
async def create_session(request: SessionCreateRequest = None):
    """创建新会话

    可选参数：
    - summarize_old: 是否在创建新会话前总结旧会话
    - old_session_id: 要总结的旧会话 ID（如果不指定，则总结最近一个会话）

    返回新会话的 ID
    """
    agent = get_agent()
    if not agent:
        raise HTTPException(status_code=500, detail="Agent not initialized")

    request = request or SessionCreateRequest()
    summary_file = None

    # 如果需要总结旧会话
    if request.summarize_old:
        old_session_id = request.old_session_id

        # 如果没有指定旧会话，找最近的一个
        if not old_session_id:
            sessions = agent.list_sessions()
            if sessions:
                old_session_id = sessions[0]["id"]

        # 总结旧会话
        if old_session_id:
            summary_file = await _summarize_session(agent, old_session_id)

View on GitHub (pinned to 606a07d341)

Solutions

  1. Check server startup logs for agent initialization errors and fix them (usually config.json llm fields)
  2. Wait for a readiness/health signal before the first session call, or retry once after a short delay
  3. Ensure you go through the app's startup (lifespan) path instead of importing the router standalone

Example fix

// before
await fetch('/api/session/create', {method:'POST', body:'{}'})
// after
await waitForHealth(); // GET /health returns ok only after agent init
await fetch('/api/session/create', {method:'POST', body:'{}'})
Defensive patterns

Strategy: retry

Validate before calling

const health = await (await fetch('/health')).json();
if (!health.ready) await waitUntilReady();

Try / catch

for (let i = 0; i < 3; i++) {
  try { return await createSession(); }
  catch (e) { if (e.status !== 500 || i === 2) throw e; await sleep(500 * (i + 1)); }
}

Prevention

When it happens

Trigger: POST /api/session/create hit before app startup finished initializing the agent; agent init failed at boot (bad config.json llm credentials) and the server kept running; tests constructing the router without the app lifespan; calling the router function directly in a script.

Common situations: Race at startup: frontend fires the create-session call as soon as the port opens; config.json missing/invalid so initialization silently left the global None; running under a reloader that swapped the process holding the global.

Related errors

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