UAT: `agents server serve` command description is misleading — default ASGI app only serves health probes, not A2A protocol #3968

New issue

Open

opened 2026-04-06 08:00:35 +00:00 by freemo · 0 comments

freemo commented

2026-04-06 08:00:35 +00:00

Owner

Metadata

Branch: fix/m9-server-serve-misleading-description
Commit Message: fix(cli): clarify server serve command description and default ASGI app limitations
Milestone: v3.8.0 (M9: Server Implementation)
Parent Epic: #399

Background and context

The agents server serve CLI command defaults to --app cleveragents.a2a.asgi:app, and its help text reads "Run the CleverAgents ASGI server process." Per docs/specification.md §Server and Client Architecture, the CleverAgents server is expected to handle A2A JSON-RPC 2.0 requests, manage agent lifecycles, and serve as the central hub for all agent operations in server mode. The current command description implies a fully functional A2A server is started, but the default ASGI app is intentionally minimal and only serves health probes.

Current behavior

The agents server serve command defaults to --app cleveragents.a2a.asgi:app. The cleveragents.a2a.asgi:app module explicitly states in its docstring that it intentionally keeps behavior minimal and dependency-free and only provides the required health probe endpoint for container and Kubernetes deployments.

The ASGI app only serves:

GET /health → {"status":"ok"}
GET /live → {"status":"alive"}
GET /ready → {"status":"ready"}
GET / → {"service":"cleveragents"}

It does not serve:

POST /api/v1/a2a (A2A JSON-RPC 2.0 endpoint)
GET /stream (SSE streaming endpoint)
Any A2A protocol operations

When a user runs agents server serve, they receive a health-probe-only server, not a functional A2A server. The command description and help text do not communicate this limitation at all.

Steps to reproduce:

Run agents server serve --help
The help text says "Run the CleverAgents ASGI server process" — no mention of health-probe-only limitation
Start the server and attempt to connect a client — all A2A requests return 404

Code locations:

src/cleveragents/cli/commands/server.py — server_serve() function
src/cleveragents/a2a/asgi.py — minimal ASGI app (health probes only)

Expected behavior

Per docs/specification.md §Server and Client Architecture:

The CleverAgents server is a FastAPI/Starlette application that serves as the central hub for all agent operations in server mode. It is responsible for handling client requests, managing agent lifecycles, and orchestrating complex workflows.

The agents server serve command description should either:

Clearly document that the default app is health-probe-only and that the full A2A server is not yet implemented (pending M9/v3.8.0), or
Raise an explicit, user-friendly error explaining that server mode is not yet available when the default app is used.

Users should never be silently served a health-probe-only server when they expect a functional A2A server.

Acceptance criteria

The server_serve() docstring and CLI --help text accurately describe the current limitation (health-probe-only default app)
Either a warning is emitted at startup when the default app is used, or the command raises a NotImplementedError/ClickException with a clear message pointing to the pending M9 implementation
The cleveragents.a2a.asgi:app module docstring is updated to cross-reference the CLI limitation
No user running agents server serve can be silently misled into thinking a full A2A server is running

Supporting information

Spec reference: docs/specification.md §Server and Client Architecture
Related Epic: #399 (Post-MVP Server & Clients)
Discovered during UAT of the server serve command in M9 scope
Impact: Users who run agents server serve expecting a functional A2A server will be confused when all client connections fail with 404

Subtasks

Update server_serve() docstring and Click help= string in src/cleveragents/cli/commands/server.py to accurately describe the health-probe-only default
Add a startup warning or ClickException when the default cleveragents.a2a.asgi:app is used, directing users to the pending full server implementation
Update src/cleveragents/a2a/asgi.py module docstring to cross-reference the CLI limitation
Tests (Behave): Add scenario verifying the warning/error is raised when default app is invoked
Tests (Behave): Add scenario verifying updated help text contains the limitation notice
Verify coverage >=97% via nox -s coverage_report
Run nox (all default sessions), fix any errors

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off.
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly (fix(cli): clarify server serve command description and default ASGI app limitations), followed by a blank line, then additional lines providing relevant details about the implementation, and ending with ISSUES CLOSED: #<this issue number>.
The commit is pushed to the remote on the branch matching the Branch in Metadata exactly (fix/m9-server-serve-misleading-description).
The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.
All nox stages pass.
Coverage >= 97%.

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-new-issue-creator

## Metadata - **Branch**: `fix/m9-server-serve-misleading-description` - **Commit Message**: `fix(cli): clarify server serve command description and default ASGI app limitations` - **Milestone**: v3.8.0 (M9: Server Implementation) - **Parent Epic**: #399 ## Background and context The `agents server serve` CLI command defaults to `--app cleveragents.a2a.asgi:app`, and its help text reads "Run the CleverAgents ASGI server process." Per `docs/specification.md` §Server and Client Architecture, the CleverAgents server is expected to handle A2A JSON-RPC 2.0 requests, manage agent lifecycles, and serve as the central hub for all agent operations in server mode. The current command description implies a fully functional A2A server is started, but the default ASGI app is intentionally minimal and only serves health probes. ## Current behavior The `agents server serve` command defaults to `--app cleveragents.a2a.asgi:app`. The `cleveragents.a2a.asgi:app` module explicitly states in its docstring that it **intentionally keeps behavior minimal and dependency-free** and only provides the **required health probe endpoint** for container and Kubernetes deployments. The ASGI app only serves: - `GET /health` → `{"status":"ok"}` - `GET /live` → `{"status":"alive"}` - `GET /ready` → `{"status":"ready"}` - `GET /` → `{"service":"cleveragents"}` It does **not** serve: - `POST /api/v1/a2a` (A2A JSON-RPC 2.0 endpoint) - `GET /stream` (SSE streaming endpoint) - Any A2A protocol operations When a user runs `agents server serve`, they receive a health-probe-only server, not a functional A2A server. The command description and help text do not communicate this limitation at all. **Steps to reproduce:** 1. Run `agents server serve --help` 2. The help text says "Run the CleverAgents ASGI server process" — no mention of health-probe-only limitation 3. Start the server and attempt to connect a client — all A2A requests return 404 **Code locations:** - `src/cleveragents/cli/commands/server.py` — `server_serve()` function - `src/cleveragents/a2a/asgi.py` — minimal ASGI app (health probes only) ## Expected behavior Per `docs/specification.md` §Server and Client Architecture: > The CleverAgents server is a FastAPI/Starlette application that serves as the central hub for all agent operations in server mode. It is responsible for handling client requests, managing agent lifecycles, and orchestrating complex workflows. The `agents server serve` command description should either: 1. Clearly document that the default app is health-probe-only and that the full A2A server is not yet implemented (pending M9/v3.8.0), **or** 2. Raise an explicit, user-friendly error explaining that server mode is not yet available when the default app is used. Users should never be silently served a health-probe-only server when they expect a functional A2A server. ## Acceptance criteria - The `server_serve()` docstring and CLI `--help` text accurately describe the current limitation (health-probe-only default app) - Either a warning is emitted at startup when the default app is used, or the command raises a `NotImplementedError`/`ClickException` with a clear message pointing to the pending M9 implementation - The `cleveragents.a2a.asgi:app` module docstring is updated to cross-reference the CLI limitation - No user running `agents server serve` can be silently misled into thinking a full A2A server is running ## Supporting information - Spec reference: `docs/specification.md` §Server and Client Architecture - Related Epic: #399 (Post-MVP Server & Clients) - Discovered during UAT of the server serve command in M9 scope - Impact: Users who run `agents server serve` expecting a functional A2A server will be confused when all client connections fail with 404 ## Subtasks - [ ] Update `server_serve()` docstring and Click `help=` string in `src/cleveragents/cli/commands/server.py` to accurately describe the health-probe-only default - [ ] Add a startup warning or `ClickException` when the default `cleveragents.a2a.asgi:app` is used, directing users to the pending full server implementation - [ ] Update `src/cleveragents/a2a/asgi.py` module docstring to cross-reference the CLI limitation - [ ] Tests (Behave): Add scenario verifying the warning/error is raised when default app is invoked - [ ] Tests (Behave): Add scenario verifying updated help text contains the limitation notice - [ ] Verify coverage >=97% via `nox -s coverage_report` - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly (`fix(cli): clarify server serve command description and default ASGI app limitations`), followed by a blank line, then additional lines providing relevant details about the implementation, and ending with `ISSUES CLOSED: #<this issue number>`. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly (`fix/m9-server-serve-misleading-description`). - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done. - All nox stages pass. - Coverage >= 97%. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added this to the v3.8.0 milestone

2026-04-06 08:00:40 +00:00

freemo added a new dependency

2026-04-06 08:00:57 +00:00

#399 Epic: Post-MVP Server & Clients

freemo referenced this issue

2026-04-06 08:02:26 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775

freemo referenced this issue

2026-04-06 08:04:04 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775

freemo added the