Agent Reflection

There are four client approaches. Normal RPC is the non-reflective baseline; the other three are reflection approaches that can be composed:

Client approach	Choose it when	Identity and lifecycle	Validation
Normal RPC	Producer and caller share a source definition through the SDK's ordinary RPC mechanism	The shared definition owns durable, phantom, and ephemeral factories allowed by its mode	Its static codecs validate typed inputs and decode declared outputs
Caller-defined static clients	The caller owns compile-time schemas and codecs without deployment discovery	Method-only agent clients bind an existing durable identity; full agent clients own lifecycle factories; typed tool definitions select commands	Local codecs validate calls and outputs; full clients also check the declared type name, constructor shape, and configuration
Discovered clients	The deployed agent type, method, tool, or command is selected from the current environment	Discovery returns immutable, snapshot-backed Reflected* clients and factories for the discovered mode	The retained snapshot automatically validates inputs and declared outputs
Fully dynamic clients	Infrastructure transports already packed schema-native values without retaining a schema authority	DynamicAgentClient binds an existing durable canonical or phantom identity; DynamicToolClient invokes an explicit tool name and command path	The caller owns packing and validation policy; the host still performs authorization and target-side validation

Caller-defined static agent clients have two deliberately different options: method-only and full. Caller-defined static tool clients use caller-owned typed definitions.

Agent identity strings are environment-scoped. Reflection identities do not include a component ID: the runtime resolves the agent type's implementing component within the caller's environment. Component-bearing IDs belong to lower-level host-management APIs, not reflection clients.

Constructor identity values contain only caller-supplied fields. The host injects principal fields separately, so a principal-scoped agent can be reconstructed from an identity returned by invocation metadata. A known ephemeral phantom can be constructed once; use the invocation metadata for its final identity. A final ephemeral identity cannot be bound for another call.

Discovery lookups are optional: a name or identity lookup returns no type when the deployment is missing, the identity is malformed, or the caller cannot view it. Parsing an identity is strict and reports malformed input. Identity discovery never creates the target agent.

Reflected schema graphs and invocation metadata are immutable snapshots. Validate or pack JSON through the reflected constructor or method schema, and treat a missing, extra, graph-incompatible, or malformed declared output as a remote output error. Rediscover explicitly when a fresh deployment snapshot is required; a client never refreshes itself automatically.

Creation-time configuration overrides are optional because component defaults may satisfy required local declarations. Reflected and full clients validate known declaration paths, values, and secret restrictions locally before opening RPC. Method-only clients may carry raw typed entries without claiming declaration-aware validation. The host validates the effective configuration when creating the worker, provisions secrets, authorizes the call, and validates the target-side input. An existing durable worker keeps its persisted initial configuration; supplying overrides when binding its ID does not reconfigure it.

Validation boundaries

• Definition and metadata construction reject malformed schema graphs, duplicate command surfaces, invalid defaults, unresolved references, incompatible ValueIs literals, and impossible command restrictions.
• Normal RPC and caller-defined static clients encode through their local schemas before opening RPC. Full-client binding also checks the declared type name and constructor value. Method-only binding cannot make either claim.
• Reflected clients validate all discovered numeric, text, binary, path, URL, quantity, collection, discriminator, optional, default, and command-constraint rules before opening RPC. Namespace tool nodes stay discoverable but have no callable body.
• The host remains authoritative for visibility, authorization, effective configuration, durable identity resolution, and the deployed target schema.
• Awaited calls validate output cardinality and shape. Structured remote agent/tool errors and custom payloads stay structured rather than being reduced to messages.

Optional values and canonical JSON

Normal RPC and caller-defined static clients use the language's normal optional-field syntax. In reflected JSON, an omitted option<T> record field and an explicit null both decode as absent; re-encoding may include the field with null. Reflection JSON Schema therefore omits optional fields from required. Tool defaults do not turn Present into a key-existence check; constraints evaluate the effective optional/default carrier, and nested ValueIs comparisons use the declared nested schema.

Canonical invocation JSON uses JSON numbers for integers through 32 bits. Signed and unsigned 64-bit integers are canonical base-10 strings, as are duration nanoseconds and quantity mantissas. A duration is { "nanoseconds": "..." }; a quantity is { "mantissa": "...", "scale": number, "unit": string }. Leading zeroes, +, and -0 are invalid. JSON Schema projections use the same string patterns and carry the exact range as metadata.

Streams, futures, and opaque capabilities have no canonical JSON representation. Their reflection JSON Schema projection is unsatisfiable. Use the schema-native *Value APIs, transfer each owned handle once, consume returned streams, and cancel or close started operations according to the language-specific API.

Mixing client approaches

The approaches are surfaces that compose around schema snapshots and durable identities:

shared source definition ──Normal RPC──────────────┐
full caller-defined client ──factory───────────────┼─> ParsedAgentId
environment discovery ──snapshot─> Reflected* ─────┘       │
          │                                                 ├─> method-only binding
          ├─> select schema → pack → Dynamic* → validate ───┼─> reflected binding
          └─> rediscover later from invocation metadata ────└─> dynamic binding

• Discovery to a reflected client retains automatic snapshot-based input and output validation.
• Discovery to a fully dynamic client is explicit: select the input/output schemas, pack and validate the input, invoke through Dynamic*, then validate and decode the result with the saved snapshot.
• Normal RPC and full caller-defined or discovered factories can produce a durable ParsedAgentId. That identity can later bind a method-only, reflected, or fully dynamic client.
• Invocation metadata can be parsed and rediscovered later, then rebound as a reflected client when the identity is durable and reusable.
• Tool discovery can feed DynamicToolClient: preserve the discovered tool name, canonical command path, input graph, and result graph; pack and validate around the dynamic call yourself.

Moving values or schemas obtained from discovery into a fully dynamic client does not transfer the reflected client's automatic validation policy. Method-only and fully dynamic agent clients expose no lifecycle factories. A final ephemeral identity cannot be rebound. Packed streams and owned handles still follow the SDK's transfer, consumption, cancellation, and cleanup rules.

Load the language-specific reflection skill for concrete SDK APIs and examples.