Identity

Primitives covers the eight-primitive overview.

Identity is the bridge between your application's notion of who a participant is and the model's notion of who is speaking. It carries something the model is meant to read — a name, a label, the thing the model uses to tell one voice apart from another in a multi-party turn — but it does so in a shape that stays linked, on the application side, to the row, account, or principal the participant actually corresponds to. Two views of one entity, kept on the same record so they cannot drift.

Identity.identifier is the application-side correlation key: database id, account id, principal id, internal username. It is the thing your system uses to find the participant again. It is not the display name unless your system key really is the display name. Identity.representation is the model-facing label, as a Tokenizable so the ADK can budget for it. The split exists so an executor that opts into multi-identity rendering has a clear answer to "what does the model see for this participant?" (the representation) and a separate clear answer to "what does my system call this participant?" (the identifier). Which of those ends up in the prompt — both, one, or neither — is the executor's call; the ADK only guarantees that the two views are kept on the same record so they cannot drift apart.

Don't collapse the two fields into one

Setting identifier and representation to the same string defeats the entire reason Identity is a separate primitive. The split is what lets your application correlate a participant by a stable key while the model sees a label that makes sense to a model — change one without the other and that contract holds. The moment they are the same string you have built a brittle one-channel identity wearing a two-channel costume: rename the user and the row key changes; pick a row key the model can read and you have leaked your internal naming scheme into a prompt. The primitive exists because those two things are not the same thing. Treat them as not the same thing.