Implementation walkthrough for the agentic request-response + A2A/Filecoin-style demo in PR #1295

[GautamBytes]

Hi all, opening this discussion to document the implementation details behind PR #1295 from an engineering perspective, as requested in review.

PR: #1295

Context

The goal of this work is to show how py-libp2p’s request/response foundation can support a higher-level agent workflow without changing the core libp2p.request_response library API.

Instead of treating request/response as just transport, this example layers on:

• capability discovery
• task creation
• follow-up input
• task lifecycle state transitions
• payment authorization
• storage receipt artifacts
• streaming-style progress semantics

The example is intentionally structured to be:

• upstream-reviewable
• deterministic by default
• safe to run locally
• extensible toward real Filecoin-backed execution

High-level structure

The implementation is split into three demo layers:

1. Local libp2p demo

   • file: examples/request_response/a2a_payment_demo.py
   • uses the high-level request/response helper over one-shot streams
   • demonstrates the full agentic task flow between two local peers

2. Shared task/service layer

   • file: examples/request_response/a2a_payment_service.py
   • contains the common task model and business logic
   • shared by both the libp2p transport demo and the HTTP A2A facade

3. HTTP A2A facade

   • file: examples/request_response/a2a_http_payment_demo.py
   • exposes the same task workflow through an A2A-shaped HTTP surface
   • supports Agent Card discovery, JSON-RPC methods, and SSE streaming updates

There is also an optional execution backend bridge:

4. Optional Synapse/Filecoin bridge
   • file: examples/request_response/synapse_bridge.py
   • sidecar: examples/request_response/synapse_sidecar/
   • allows the same flow to move from deterministic simulation toward real Synapse-backed execution when explicitly configured

Why this layering

I wanted to keep the py-libp2p transport example useful on its own while also showing how it can map into a more standards-facing agent protocol shape.

That led to this separation:

• transport concern:
  py-libp2p request/response handles peer-to-peer communication

• workflow concern:
  the shared task service handles message validation, task state transitions, quote generation, payment authorization, and artifact assembly

• protocol facade concern:
  the HTTP layer maps the same workflow into an A2A-style interface

This keeps the design modular and avoids pushing protocol-specific logic into the transport helper itself.

Core task lifecycle

The shared task service models the workflow using A2A-style task states.

Typical flow:

1. client sends an initial store_data message
2. server validates input and creates a task
3. task returns TASK_STATE_AUTH_REQUIRED
4. response includes a Filecoin Pay-style quote in task metadata
5. client sends a follow-up authorization message referencing the same task
6. task moves to TASK_STATE_WORKING
7. task completes as TASK_STATE_COMPLETED
8. final artifacts are attached:
   • payment authorization artifact
   • storage receipt artifact

This gives a concrete multi-turn task flow instead of a single request/response blob.

Quote and artifact model

The quote intentionally mirrors Filecoin-style payment concepts, while remaining deterministic and local-first by default.

Quote metadata includes fields such as:

• railId
• depositNeededUsdfc
• streamingLockupUsdfc
• fixedLockupUsdfc
• paymentToken
• operator
• validator

Final task artifacts include:

1. Payment authorization artifact

Contains the approved payment rail context, payer info, and lockup values.

2. Storage receipt artifact

Contains storage execution output such as:

• pieceCid
• requested copies
• successful provider selections
• failed provider attempts
• retrieval URLs
• execution backend label

Deterministic simulation backend

By default the demo uses a simulated execution backend.

This was deliberate for upstream reviewability:

• no external services required
• no funded wallets required
• no Synapse/Filecoin dependency required
• reproducible output for local testing and CI
• degraded-provider behavior can be demonstrated deterministically

The provider catalog includes healthy and unhealthy providers so the example can show both:

• full success with default copies
• partial fulfillment with --copies 3

That degraded path was important because I wanted the example to show realistic workflow handling under imperfect provider conditions, not just the happy path.

HTTP A2A facade

The HTTP demo reuses the same shared task service and exposes it through an A2A-shaped interface.

Main endpoints / behaviors:

• GET /.well-known/agent-card.json
• POST /rpc
• SendMessage
• GetTask
• ListTasks
• CancelTask
• SendStreamingMessage via SSE

This means the exact same workflow can be exercised in two ways:

• native py-libp2p request/response transport
• HTTP JSON-RPC + SSE facade

So the example demonstrates both a transport-level integration path and a standards-facing agent interface path.

Optional Synapse bridge

The Synapse integration is intentionally optional.

The bridge is kept separate because I did not want real network/payment execution to be a hard dependency for:

• running the example
• understanding the architecture
• passing CI
• reviewing the PR

When enabled explicitly, the Synapse sidecar path is intended to:

• prepare a real backend quote
• execute storage-related steps
• optionally perform real approval/funding transactions
• return real backend-derived storage metadata

Guardrails are in place so that no real transaction execution happens unless explicitly enabled via environment configuration.

CI and implementation hygiene

A significant part of the follow-up work on this PR was making the demo robust in normal project CI environments.

That included:

• ensuring the HTTP A2A demo is optional at import/runtime boundaries
• avoiding hard dependency on optional A2A HTTP packages in core environments
• tightening pyrefly/mypy typing around task state and artifact handling
• keeping the request/response library API unchanged
• ensuring full core/lint matrix compatibility

The PR head is now green in CI.

What this PR does not try to do

This PR does not attempt to:

• modify the core request/response API
• embed A2A directly into the py-libp2p core transport library
• require Synapse/Filecoin services for the base demo
• claim a full production A2A implementation over libp2p
• solve persistence, auth, or production-grade storage/payment orchestration end to end

The scope is to provide a concrete, implementation-oriented example that demonstrates how these layers can fit together cleanly.

Why I think this example is useful

I believe this example is useful because it shows a realistic progression:

• from raw request/response transport
• to structured agent workflows
• to task-based interaction semantics
• to standards-facing A2A surfaces
• to optional decentralized payment/storage execution backends

That makes it valuable both as:

• an educational example for py-libp2p users
• and a design reference for more complex agentic/decentralized workflows built on top of py-libp2p

Feedback I would especially value

I’d appreciate feedback on:

1. whether this layering feels appropriate for examples rather than core library code
2. whether the task/service split is the right abstraction boundary
3. whether the HTTP A2A facade adds value as an example surface
4. whether the Synapse bridge should remain in this PR or be split further
5. whether the example documentation should go deeper on protocol semantics or stay more operational

Thanks, happy to revise structure or split pieces differently if that would make the example more maintainable for the project.