The solution architect

The solution architect settles what an agent stands on before anybody designs what it does. It names the systems the agent reaches, binds a product to each system in each environment the agent will run in, names the other agents and services the agent depends on, says what the agent's inside is made of, sets the limits the agent must keep, and writes down every decision with its reason. It hands back all of that as the architecture record. A person can hold this part of the stage instead of an agent.

The lifecycle stage Architecture and Design has two parts, and the architecture comes first, because a design written before its systems are named has to be written again once they are. The solution architect holds the first part, Architecture. The spec writer and the solution planner hold the second part, Design, and they design only with the systems the record names.

The record is checked at two later stages by roles the architect does not control. The systems it names become the systems of the package's runtime requirements (Common Agent Specification 12.4), so at Package the package maker builds a package whose systems[] names are the record's. The bindings are what the deployment manager places at Deploy, in the environment the deploy names. A system the package does not declare, or an environment the record does not bind, shows at one of those two stages.

On the lifecycle map, the solution architect holds Architecture, the first part of the Architecture and Design stage (agenticdevelopment.ai). The spec writer and the solution planner hold the second part, Design.

1. The requests

These exchanges are the role's primary interface, stated here, with no entry of its own (Agent Roles §14.3). Implementing them alone does not grant the role.

1. Write the architecture. The architect is given what the agent is for, with whatever exists: the requirements, the organization's own choices of product for each system and environment, the platform's defaults, and any earlier record. The architect returns the architecture record and the questions it could not settle.
2. Revise it. The architect is given a record with what to change. The architect changes what was asked, keeps the rest, and returns the list of lines that changed, with the reason for each changed decision.

The architecture record says seven things.

1. The systems. Each system the agent reaches, named in plain system words, such as crm or email. These are the names the Common Agent Specification's runtime requirements carry in systems[] (its Section 12.4).
2. The bindings. For each system, the product bound to it in each environment the agent will run in, such as dev, test and production, with each environment named in the words the deploy into it will use, which the deployment record spells dev, test, staging or production (Common Agent Specification 8.3). The organization's own choice is the binding wherever it made one, a platform default fills each binding it left open, and the record says which of the two each binding came from, as the deployment record's provided_by does with customer or platform (Common Agent Specification 8.3).
3. The dependencies. The other agents and services the agent depends on, each named.
4. The kind. What the agent's inside is made of, such as skills that a harness reads or code that answers on the network by itself. A package declares its inside in its own files (Common Agent Specification Section 12). The deployment record's installed member uses words such as plugin-on-harness and mesh-coded for the same thing, as background that nothing is checked against (its Section 8.3).
5. The limits. What the agent may spend, how quickly it must answer, what data it may hold or move and where, and which parties it trusts and on what terms.
6. The decisions. Each choice the record makes, with the reason for it, in the manner of an architecture decision record: what was decided, why, the options that were weighed, and what follows from the choice.
7. The egress. For each environment, what the agent may reach on the network beyond the derived set of the Common Agent Specification, which is its systems, the network, the registrar, the model it is given and the hosts its workspace kinds are reached at: each further destination named by what it is and why the agent needs it, which only an agent with an offering that declares reaches-network may have (Common Agent Specification 6.11), or a statement that it needs none; and whether that environment's target can enforce an allowlist or will run the agent open, the two policies the deployment record's egress spells (Common Agent Specification 8.3). The addresses are not in the record: the owner's instruction supplies them at Deploy. A further destination is a commitment, so the architect asks for it and does not fill it in.

2. What it does

1. It settles what the agent stands on and designs nothing. The solution architect does not write the agent's statement, plan the steps of a solution, or choose the agent that does a step. Those belong to the spec writer, the solution planner and the catalog.
2. A system is named by what it is. Each system is named in plain system words, as the runtime requirements name it. A system is never named by its product, an address or an account. The product is the binding, and it is kept in the binding, never in the name.
3. Every system is bound in every environment. Each system has a product in each environment the agent will run in. A binding that cannot be made is asked as a question, and the record is not delivered as finished while one is open.
4. The organization's choice wins. Where the organization chose a product for a system in an environment, the architect binds that product. A platform default fills only a binding the organization left open, and the record marks it as a default.
5. Every decision has a reason. A decision without a reason is not delivered. The architect gives the reason or asks for it.
6. A commitment is asked, never filled. A spending limit, a product that neither the organization chose nor the platform offers, access to a system the requirements do not call for, and a network destination beyond the derived set are commitments somebody would be held to. The architect asks for each and fills none of them in.
7. The record carries no secret and no address. It names products, and it carries no credential value, no address and no account identifier, for the reason the Common Agent Specification gives for the package's own declarations (its Section 12.6 rule 3).

The Architecture part is done when every system is named and bound in each environment the agent will run in, every decision has a reason, and every step of the design uses only systems the record named. The architect checks the first two before it delivers. The third is checked when the design comes back: a step that needs a system the record does not name goes back to the architect as a question, and the record is revised before the design goes on.

3. The record

The record is the architecture record, with the questions beside it. Its systems are the names the package's runtime requirements carry in systems[]. Its bindings for an environment are what the owner's instruction to the deployment manager supplies for that environment, and what the deployment record then shows was placed (Common Agent Specification 8.3). The role defines no signature tag; the delivery travels under the signed job manifest the Common Agent Specification defines (Agent Roles §18.2 rule 7).

4. How a holder is checked

The test is behavioral, with a mechanical part. A harness hands the candidate the requirements of an agent that reads a customer list and sends email and will run in dev, test and production, the organization's choice of email product for production and no other choice, and a platform default for every system in every environment. The record must name two systems in plain system words, bind each in dev, test and production, bind the organization's product for email in production, mark every other binding as a platform default, and give a reason for every decision. The harness removes the platform's default for one system in test, and the record must raise that binding as a question and leave it unfilled. It hands back a design step that uses a third system the requirements do not call for, and the candidate must answer with a question about the architecture and must not add the system to the record on its own. It asks the candidate to write the agent's statement, and the candidate must decline. The mechanical part compares the systems in the record with the systems[] names of a package built from it, and the two sets must be equal. A record that names a system by its product, carries a credential or an address, binds a default where the organization chose a product, or leaves a decision without a reason fails the candidate.

A platform can record the results of the check as evidence, so a role holder's reputation in the bureau reflects whether it does the job the role defines.

v1.3 (2026-10-24): first published, with the Architecture and Design stage.

v1.3.1 (2026-10-24): the environments in the examples are dev, test and production, the spellings the deployment record uses, and the lifecycle link goes to the Architecture and Design stage.

v1.4 (2026-10-24): the architecture record says a seventh thing, the egress for each environment.