Chapter 2 of 6
Architecture at a glance#
The flow starts with the Foundry agent already created by the governed agent baseline. The product owner completes the system record and the responsible-AI records. The runtime owner deploys the approval gate beside the agent application and binds one write or irreversible tool to it.
The gate has two phases. First, the agent proposes a tool call and the gate returns an awaiting_approval state with a correlation ID and an argument hash. The HTTP endpoint stores the pending call in memory for this nonproduction module. Then a different authenticated approver resumes the same task with approved or rejected. The gate reads the requester and approver from App Service authentication headers, decodes X-MS-CLIENT-PRINCIPAL, and requires the configured role or group claim before approval. Approval executes the original pending arguments against the configured tool route. Rejection returns without tool execution.
ai-system-inventory-entry.json is the machine record. impact-assessment.md and transparency-note.md are the human records. oversight-decision.json ties the approver role, action class, retention, and stop mechanism to the runtime code.
Design choices and tradeoffs#
| Decision | Chosen approach | Benefit | Cost or limit |
|---|---|---|---|
| System record | One schema-checked JSON inventory entry | The responsible-AI owner can enforce enum values before handoff | Legal still reviews the classification |
| Impact and transparency records | Markdown records with required decisions | Product, risk, and communications reviewers can read them without tooling | They are pointers to the approved customer record system, not a full archive |
| Oversight pattern | Foundry hosted-agent pause and resume | The agent can wait for a human decision without keeping one request open | The Learn page marks long-running agents as preview |
| Tool boundary | One write or irreversible tool uses always_require approval | The consequential action never runs on a rejected path | The runtime owner must bind every future consequential tool separately |
| Approver identity | App Service authentication headers identify the requester and approver | The app does not trust self-asserted approver values and blocks self-approval | The gate must run behind Microsoft Entra authentication with an approver role or group claim |
| Pending state | In-memory task store for nonproduction delivery | Keeps the module small and easy to inspect | Production use needs the approved durable store in oversight-decision.json |
| Preview | No platform what-if for the approval code | Preflight catches unresolved decisions before deployment | The deployed approved and rejected checks are still required |
Architecture guidance#
Use Transparency Note for Foundry Agent Service to frame agent capabilities, limits, and human-oversight cautions for the system note.
Use Add a human-in-the-loop approval step for the Foundry hosted-agent pause-and-resume pattern. The page marks long-running agents as preview, so keep this in a nonproduction path until the customer approves preview use.
Use Work with user identities in Azure App Service authentication for the platform-injected identity headers. The approval gate requires X-MS-CLIENT-PRINCIPAL, X-MS-CLIENT-PRINCIPAL-ID, and X-MS-CLIENT-PRINCIPAL-NAME on start and resume.