feat(server): integrate LangGraph Platform with RemoteGraph for server execution #722

Closed
freemo wants to merge 4 commits from feature/m9-langgraph-platform into master
Owner

Summary

Implements LangGraph Platform integration with RemoteGraph for server-side actor execution per ADR-048 (Server Application Architecture), establishing the server application structure with FastAPI, PostgreSQL support, and Docker deployment.

Closes #693

Changes

New package: src/cleveragents/server/

  • app.py — FastAPI application shell with:
    • A2A JSON-RPC endpoint (/a2a) wired to the JSON-RPC router from #690
    • Agent Card endpoint (/.well-known/agent.json)
    • Health check endpoint (/health)
    • CORS, authentication middleware, and startup/shutdown lifecycle hooks
  • remote_graph.pyRemoteGraph integration for server-side actor execution:
    • Wraps existing LangGraph-defined actor graphs for remote execution
    • Thread-safe graph invocation with proper async handling
    • Configuration for LangGraph Platform deployment URL and API key
  • database.py — PostgreSQL connection support replacing SQLite for server-side persistence:
    • Async connection pool via asyncpg
    • Migration compatibility with existing SQLAlchemy models
    • Connection string configuration via environment variables

Deployment

  • docker/Dockerfile — Multi-stage Docker build for the server application
  • docker/docker-compose.yml — Docker Compose configuration with PostgreSQL, the server app, and health checks

Test files

  • features/server_app.feature + step definitions — BDD tests for server endpoints, RemoteGraph wiring, and health checks
  • robot/server_app.robot + helper — Integration tests for Docker-based server deployment

Dependencies

Depends on #691 (stdio transport) and #692 (HTTP transport) for the transport layer used by the server.

Quality Checks

  • nox -e typecheck — 0 Pyright errors
  • nox -e lint — all checks passed
  • nox -e format — all files unchanged
## Summary Implements LangGraph Platform integration with `RemoteGraph` for server-side actor execution per ADR-048 (Server Application Architecture), establishing the server application structure with FastAPI, PostgreSQL support, and Docker deployment. Closes #693 ## Changes ### New package: `src/cleveragents/server/` - **`app.py`** — FastAPI application shell with: - A2A JSON-RPC endpoint (`/a2a`) wired to the JSON-RPC router from #690 - Agent Card endpoint (`/.well-known/agent.json`) - Health check endpoint (`/health`) - CORS, authentication middleware, and startup/shutdown lifecycle hooks - **`remote_graph.py`** — `RemoteGraph` integration for server-side actor execution: - Wraps existing LangGraph-defined actor graphs for remote execution - Thread-safe graph invocation with proper async handling - Configuration for LangGraph Platform deployment URL and API key - **`database.py`** — PostgreSQL connection support replacing SQLite for server-side persistence: - Async connection pool via `asyncpg` - Migration compatibility with existing SQLAlchemy models - Connection string configuration via environment variables ### Deployment - **`docker/Dockerfile`** — Multi-stage Docker build for the server application - **`docker/docker-compose.yml`** — Docker Compose configuration with PostgreSQL, the server app, and health checks ### Test files - `features/server_app.feature` + step definitions — BDD tests for server endpoints, RemoteGraph wiring, and health checks - `robot/server_app.robot` + helper — Integration tests for Docker-based server deployment ### Dependencies Depends on #691 (stdio transport) and #692 (HTTP transport) for the transport layer used by the server. ## Quality Checks - `nox -e typecheck` — 0 Pyright errors - `nox -e lint` — all checks passed - `nox -e format` — all files unchanged
refactor(a2a): rename ACP module and symbols to A2A standard
All checks were successful
CI / benchmark-publish (pull_request) Has been skipped
CI / lint (pull_request) Successful in 20s
CI / build (pull_request) Successful in 16s
CI / quality (pull_request) Successful in 35s
CI / security (pull_request) Successful in 47s
CI / typecheck (pull_request) Successful in 1m37s
CI / integration_tests (pull_request) Successful in 3m38s
CI / unit_tests (pull_request) Successful in 4m44s
CI / docker (pull_request) Successful in 1m6s
CI / coverage (pull_request) Successful in 5m30s
CI / benchmark-regression (pull_request) Successful in 35m37s
2fe95d1b38
Renamed src/cleveragents/acp/ to src/cleveragents/a2a/ and all 13
Acp* classes to A2a* per ADR-047 (A2A Standard Adoption). Updated
all imports, structlog event names (acp.* → a2a.*), field names
(acp_version → a2a_version), and test references across the entire
codebase. This is a cosmetic rename only — no behavioral changes.

ISSUES CLOSED: #688
feat(a2a): implement JSON-RPC 2.0 wire format and method routing
All checks were successful
CI / benchmark-publish (pull_request) Has been skipped
CI / lint (pull_request) Successful in 14s
CI / build (pull_request) Successful in 16s
CI / quality (pull_request) Successful in 18s
CI / security (pull_request) Successful in 35s
CI / typecheck (pull_request) Successful in 55s
CI / unit_tests (pull_request) Successful in 2m57s
CI / integration_tests (pull_request) Successful in 3m23s
CI / docker (pull_request) Successful in 41s
CI / coverage (pull_request) Successful in 5m36s
CI / benchmark-regression (pull_request) Successful in 35m11s
33900eab03
Implement the JSON-RPC 2.0 wire format layer and method routing for the
A2A protocol, building on the ACP-to-A2A rename from #688.

New modules in src/cleveragents/a2a/:
- jsonrpc_models.py: Pydantic v2 models for JSON-RPC 2.0 request,
  response, error, and notification envelopes
- jsonrpc_router.py: Method router that dispatches JSON-RPC requests
  to registered handlers, with support for standard A2A methods and
  _cleveragents/ extension methods
- jsonrpc_handlers.py: Handlers for standard A2A methods (message/send,
  message/stream, tasks/get, tasks/cancel) and extension method factory
  that delegates to A2aLocalFacade
- jsonrpc_errors.py: Maps domain error taxonomy to JSON-RPC 2.0 error
  codes (standard -32700 to -32603, application -32001 to -32008)
- agent_card.py: Agent Card model and generation for the
  /.well-known/agent.json capability advertisement endpoint

Standard A2A methods:
- message/send: Create/update tasks via messages
- message/stream: Streaming variant with SSE event indicators
- tasks/get: Retrieve task by ID
- tasks/cancel: Cancel running tasks

CleverAgents extension methods (_cleveragents/ prefix):
- plan/use, execute, status, diff, apply, cancel
- registry/list_tools, list_resources
- context/show
- sync/status
- namespace/list
- health

Tests:
- Behave BDD: features/a2a_jsonrpc.feature (28 scenarios)
- Robot Framework: robot/a2a_jsonrpc.robot (9 integration tests)

ISSUES CLOSED: #690
feat(a2a): implement A2A stdio transport for local mode
All checks were successful
CI / benchmark-publish (pull_request) Has been skipped
CI / lint (pull_request) Successful in 15s
CI / build (pull_request) Successful in 19s
CI / quality (pull_request) Successful in 19s
CI / security (pull_request) Successful in 36s
CI / typecheck (pull_request) Successful in 38s
CI / unit_tests (pull_request) Successful in 3m0s
CI / integration_tests (pull_request) Successful in 3m27s
CI / docker (pull_request) Successful in 41s
CI / coverage (pull_request) Successful in 5m31s
CI / benchmark-regression (pull_request) Successful in 35m39s
680cc8c352
Add A2aStdioTransport class that manages subprocess lifecycle and
communicates via newline-delimited JSON-RPC 2.0 messages over
stdin/stdout. Add A2aTransport protocol (typing.Protocol) defining
the abstract transport interface. Add A2aTransportSelector that
picks A2aStdioTransport in local mode (no server URL) or
A2aHttpTransport in server mode.

New files:
- transport_protocol.py: A2aTransport Protocol
- stdio_transport.py: A2aStdioTransport with subprocess management
- transport_selector.py: A2aTransportSelector configuration-based
- echo_agent.py: Minimal echo agent fixture for tests

Tests:
- 20 Behave BDD scenarios covering protocol conformance, construction,
  subprocess lifecycle, send/receive, context manager, transport
  selector, and contract round-trip tests
- 7 Robot Framework integration tests with helper script

ISSUES CLOSED: #691
feat(server): integrate LangGraph Platform with RemoteGraph for server execution
All checks were successful
CI / benchmark-publish (pull_request) Has been skipped
CI / lint (pull_request) Successful in 14s
CI / quality (pull_request) Successful in 18s
CI / build (pull_request) Successful in 18s
CI / security (pull_request) Successful in 35s
CI / typecheck (pull_request) Successful in 38s
CI / unit_tests (pull_request) Successful in 4m48s
CI / integration_tests (pull_request) Successful in 5m28s
CI / docker (pull_request) Successful in 54s
CI / coverage (pull_request) Successful in 5m35s
CI / benchmark-regression (pull_request) Successful in 35m5s
e13308b322
Implement the server application module (ADR-048) with:

- FastAPI application factory (app.py) exposing the A2A JSON-RPC 2.0
  endpoint as the sole client-facing interface. Routes: POST /a2a
  (JSON-RPC dispatch), GET /.well-known/agent.json (Agent Card), and
  GET /health (container orchestration).

- RemoteGraph adapter (remote_graph.py) for invoking actor graphs
  via LangGraph Platform. Each actor graph deploys as a separate
  RemoteGraph enabling independent scaling. Includes health tracking,
  invocation counting, and a RemoteGraphRegistry for managing
  multiple graph deployments.

- Database configuration (database.py) supporting PostgreSQL for
  production and SQLite for development. Config-driven via
  CLEVERAGENTS_DATABASE_URL and CLEVERAGENTS_SERVER_ENV environment
  variables with validated Pydantic settings model.

- Docker deployment (docker/Dockerfile + docker-compose.yml) with
  multi-stage build, non-root user, health checks, and PostgreSQL
  service.

- FastAPI dependency added to pyproject.toml.

- 26 Behave BDD scenarios covering app factory, A2A dispatch, Agent
  Card, health endpoint, RemoteGraph config/adapter/registry, and
  database configuration.

- 10 Robot Framework integration tests with helper script verifying
  end-to-end server functionality.

ISSUES CLOSED: #693
freemo added this to the v3.8.0 milestone 2026-03-12 03:05:30 +00:00
freemo self-assigned this 2026-03-12 20:33:30 +00:00
Author
Owner

PM Status — Day 32

State: CONFLICTED — needs rebase onto master.

Priority: Low — M9 (v3.8.0), no deadline. Current focus should be M3-M6.

Dependencies: This is the final PR in the M9 A2A/Server chain. Depends on:

  1. #708 (JSON-RPC wire format)
  2. #713 (stdio transport)
  3. #720 (HTTP transport)

All three must be merged before this PR can be rebased.

Scope: This is the largest PR in the series — introduces src/cleveragents/server/ package (FastAPI app, RemoteGraph integration, PostgreSQL support) plus Docker deployment files.

Missing labels: Adding Priority/Low, MoSCoW/Could have, Points/21, State/In Progress.

@freemo — No immediate action needed. This is last in the M9 merge chain (#708#713#720#722). Focus on M3-M6 priorities first.

### PM Status — Day 32 **State:** CONFLICTED — needs rebase onto master. **Priority:** Low — M9 (v3.8.0), no deadline. Current focus should be M3-M6. **Dependencies:** This is the final PR in the M9 A2A/Server chain. Depends on: 1. #708 (JSON-RPC wire format) 2. #713 (stdio transport) 3. #720 (HTTP transport) All three must be merged before this PR can be rebased. **Scope:** This is the largest PR in the series — introduces `src/cleveragents/server/` package (FastAPI app, RemoteGraph integration, PostgreSQL support) plus Docker deployment files. **Missing labels:** Adding Priority/Low, MoSCoW/Could have, Points/21, State/In Progress. @freemo — No immediate action needed. This is last in the M9 merge chain (#708 → #713 → #720 → #722). Focus on M3-M6 priorities first.
Author
Owner

Rebase Required

@freemo — This PR has merge conflicts with master. Please rebase onto the latest master and force-push. See also: #668, #669, #703, #708, #713, #720 (all need rebase).

## Rebase Required @freemo — This PR has merge conflicts with `master`. Please rebase onto the latest `master` and force-push. See also: #668, #669, #703, #708, #713, #720 (all need rebase).
Author
Owner

PM Review — Day 34

Status: NOT mergeable (conflicts), 0 reviews, M9 (v3.8.0), Priority/Low, Points/21
Author: @freemo

LangGraph Platform integration with RemoteGraph. M9 — lowest urgency. Largest M9 PR at 21 points. Rebase deferred.

Action Items

Who Action Deadline
@freemo Rebase when M9 sprint begins M9 sprint
## PM Review — Day 34 **Status**: NOT mergeable (conflicts), 0 reviews, M9 (v3.8.0), Priority/Low, Points/21 **Author**: @freemo LangGraph Platform integration with RemoteGraph. M9 — lowest urgency. Largest M9 PR at 21 points. Rebase deferred. ### Action Items | Who | Action | Deadline | |-----|--------|----------| | @freemo | Rebase when M9 sprint begins | M9 sprint |
Author
Owner

PM Status — Day 36 (2026-03-16)

Confirmed deferred status. M8/M9 rebase and review deferred until M3-M6 queue clears. No action required at this time.

Next check: Day 40 or when M6 work is substantially complete.

## PM Status — Day 36 (2026-03-16) Confirmed deferred status. M8/M9 rebase and review deferred until M3-M6 queue clears. No action required at this time. **Next check**: Day 40 or when M6 work is substantially complete.
freemo left a comment

PM Day 36: LangGraph Platform RemoteGraph integration. M9 scope (deferred). Merge conflict. @freemo rebase needed when ready.

PM Day 36: LangGraph Platform RemoteGraph integration. M9 scope (deferred). Merge conflict. @freemo rebase needed when ready.
Author
Owner

This feature is for a later version, so closing it and will do it at the appropriate time.

This feature is for a later version, so closing it and will do it at the appropriate time.
freemo closed this pull request 2026-03-16 22:35:48 +00:00
All checks were successful
CI / benchmark-publish (pull_request) Has been skipped
CI / lint (pull_request) Successful in 14s
Required
Details
CI / quality (pull_request) Successful in 18s
Required
Details
CI / build (pull_request) Successful in 18s
Required
Details
CI / security (pull_request) Successful in 35s
Required
Details
CI / typecheck (pull_request) Successful in 38s
Required
Details
CI / unit_tests (pull_request) Successful in 4m48s
Required
Details
CI / integration_tests (pull_request) Successful in 5m28s
Required
Details
CI / docker (pull_request) Successful in 54s
Required
Details
CI / coverage (pull_request) Successful in 5m35s
Required
Details
CI / benchmark-regression (pull_request) Successful in 35m5s

Pull request closed

Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Reference
cleveragents/cleveragents-core!722
No description provided.