Routing metadata is request-associated key-value information that tells an API gateway which backend service should receive a call. In a gRPC-based SDK, the client attaches metadata such as x-target-service: sessions or x-target-service: models while sending a Protocol Buffer request. The gateway reads this metadata and routes the request without deserializing the binary payload. section 2.5.2 section 3.9.4
A service client applies routing metadata as part of a repeatable request path:
- Establish a secure gRPC channel to the gateway. section 2.5.2
- Construct a Protocol Buffer request from ordinary Python objects. section 3.9.2
- Attach service-specific metadata to the gRPC invocation. section 2.5.2 section 3.9.2
- Let the gateway forward the request to the identified backend, then convert the response back into a Python object. section 3.9.4
Session service metadata
A SessionClient prepares its routing metadata during initialization: self._metadata = (('x-target-service', 'sessions'),). Its get_or_create method passes metadata=self._metadata to the stub call, so the gateway can route the request to the Sessions Service while the caller uses a local-looking Python method. section 2.5.2
Figure 2.7 When Sarah's workflow calls a platform service, the SDK lazily initializes the appropriate client on first access, establishes a gRPC channel to the gateway with service-specific metadata, constructs Protocol Buffer requests, and converts responses back to Python objects. The gateway reads the x-target-service metadata to route requests to the correct service without deserializing the binary data

Trace lazy client creation, secure channel establishment, metadata attachment, gateway routing, Protocol Buffer transport, and response conversion in one sequence. section 2.5.2
