Please ensure you have read the contribution guide before creating a pull request.

Link to Issue or Description of Change

1. Link to an existing issue (if applicable):

• Closes: Unhandled exception for invalid app_name leads to 500 response #5374
• Related: Fix: return 404 for invalid app_name in /run and /run_sse endpoints #5376 (earlier attempt, now merge-conflicted and targeting the deprecated adk_web_server.py shim; this PR applies the fix to the current api_server.py)

2. Or, if no issue exists, describe the change:

Problem:
AgentLoader.load_agent raises ValueError("Agent not found: ...") for an unknown app name, and neither get_runner_async nor the /apps/{app_name}/app-info handler in cli/api_server.py catches it. A request with an invalid app_name to /run, /run_sse, or /apps/{app_name}/app-info therefore returns an unhandled 500 instead of a 404.

Solution:
Catch ValueError tightly around the two load_agent call sites and convert it to HTTPException(status_code=404, detail=str(ve)), chained with from ve — the same pattern the dev server already uses. The try blocks wrap only the load_agent call, so unrelated ValueErrors (plugin loading, YAML parsing, agent construction) still fail loudly. Since /run and /run_sse both resolve their runner through get_runner_async, all three reported endpoints are covered.

Testing Plan

Unit Tests:

• I have added or updated unit tests for my change.
• All unit tests pass locally.

Three endpoint-level regression tests added to tests/unittests/cli/test_fast_api.py, each driving the real endpoint through FastAPI's TestClient with a nonexistent app name and asserting a 404 whose detail carries the "Agent not found" message:

• POST /run → 404
• POST /run_sse → 404
• GET /apps/{app_name}/app-info → 404

All three fail on the unfixed code (unhandled ValueError) and pass with the fix:

# before fix:
3 failed (ValueError: Agent not found: 'unknown_app' ...)

# with fix:
$ pytest tests/unittests/cli/test_fast_api.py -q
86 passed

pyink --check and isort --check-only are clean on both touched files.

Manual End-to-End (E2E) Tests:

To reproduce: start adk api_server in any agents directory, then curl -X POST localhost:8000/run -H 'Content-Type: application/json' -d '{"app_name": "no_such_app", "user_id": "u", "session_id": "s", "new_message": {"role": "user", "parts": [{"text": "hi"}]}}'. Before this change the server returns a 500 with a traceback in the logs; with it, a 404 with "Agent not found: 'no_such_app'..." in the detail. Same for GET /apps/no_such_app/app-info.

Checklist

• I have read the CONTRIBUTING.md document.
• I have performed a self-review of my own code.
• I have commented my code, particularly in hard-to-understand areas.
• I have added tests that prove my fix is effective or that my feature works.
• New and existing unit tests pass locally with my changes.
• I have manually tested my changes end-to-end.
• Any dependent changes have been merged and published in downstream modules.

Additional context

get_runner_async has callers beyond the three endpoints (websocket /run_live, trigger routes); all were checked. The websocket path leaves an unknown app equally unhandled before and after this change (pre-existing, out of scope), and the trigger path's retry loop treats HTTPException exactly as it treated ValueError (non-transient, immediate re-raise). No caller depended on catching ValueError.