gRPC

The planner reads three cards and finds only JSONRPC and HTTP+JSON interfaces, so no call in 19-planner.http uses gRPC. The kit is standard library only, and the standard library has no gRPC, so no capture in this manual shows a gRPC call. The reference SDK's sample agent lists a third interface, protocol_binding='GRPC' at a plain host and port.

When you finish this section, you can read a GRPC interface, call A2AService from a generated stub, and read its errors and streams.

The service

The binding has four requirements: "gRPC over HTTP/2 with TLS", the normative definition in specification/a2a.proto, "Protocol Buffers version 3", and the A2AService service. The file declares package lf.a2a.v1, so the full service name is lf.a2a.v1.A2AService. Its eleven rpcs carry the same PascalCase names as the JSON-RPC methods, and operations by binding lists them with their messages.

Two rpcs return stream StreamResponse: SendStreamingMessage and SubscribeToTask. The other nine are unary, and none takes a client stream. Each rpc also carries the google.api.http annotation that defines its HTTP+JSON route, as HTTP+JSON shows:

  // Sends a streaming message to an agent, allowing for real-time interaction and status updates.
  // Streaming version of `SendMessage`
  rpc SendStreamingMessage(SendMessageRequest) returns (stream StreamResponse) {
    option (google.api.http) = {
      post: "/message:stream"
      body: "*"
      additional_bindings: {
        post: "/{tenant}/message:stream"
        body: "*"
      }
    };
  }

A card names this binding with protocolBinding set to GRPC. At the tag the proto wants an absolute HTTPS URL for every interface, while a gRPC client dials a host and port (conflict D34). AgentCard fields notes the same gap. PR #1997 changed the comment on main to the form hostname:port, the one change queued for release 1.0.2, not yet released.

Metadata, errors, and streams

The two service parameters must travel as gRPC metadata. gRPC lowercases metadata keys, so the keys are a2a-version and a2a-extensions. A server should validate required service parameters, such as A2A-Version, from the metadata. The §10.2 sample sends a2a-version with the old example value 0.3, so send 1.0 from a 1.0 client, as A2A-Version and A2A-Extensions explains.

An error is a google.rpc.Status with status.code, status.message, and status.details. For an A2A error, the details must include a google.rpc.ErrorInfo message. Its reason is the error name in upper snake case without Error, such as TASK_NOT_FOUND, and its domain is a2a-protocol.org. The table in errors gives the status of each error, and FAILED_PRECONDITION covers six of the nine, so read the reason.

A stream is a server-streaming rpc, and each message is one StreamResponse with one of task, message, status_update, or artifact_update. The stream ends when the rpc completes with its status, and the Go server returns OK when its event sequence ends. Figure 5.2 follows one streaming call from the request to that end.

SDK support

The servers differ on the version check: the Python, Go, and Rust gRPC servers never read a2a-version, as the table in A2A-Version and A2A-Extensions shows.

One custom binding exists in the project today, SLIMRPC: Protocol Buffers RPC over SLIM instead of HTTP/2. A card names it https://a2a-protocol.org/bindings/experimental-slimrpc/v1, and its repository marks it experimental. A custom binding should have a URI as its identifier, and the project's guide gives the rules for one.