Task 6 — Publish and govern a hosted agent and an A2A endpoint

Part of the Govern AI models and agents through an API gateway lab. New here? Start with Getting started.

Starting here on its own? You need the Citadel hub and a sample spoke deployed (the spoke provides the Foundry project and container registry these notebooks deploy into). The hosted-agent notebook uses the BYO Gateway connection Hub-HR-ChatAgent-DEV-LLM created by the access-contracts notebook — if you skipped Task 2, run 3. citadel-access-contracts-tests.ipynb first. From the Labfiles/G-govern-ai-through-a-gateway folder, run python setup/check_env.py --task 6 to confirm the hub and spoke are deployed.

Continuing from a previous task? The BYO Gateway connection and access contracts from Task 2 carry straight over. No new deployment is needed beyond what these two notebooks create.

So far you’ve governed calls. This task governs whole agents: you build a hosted HR agent whose every action is checked against a policy, then you publish an agent through the gateway as a governed Agent-to-Agent (A2A) endpoint that other agents can call with just a subscription key.

What does the Agent Governance Toolkit actually enforce?

The Agent Governance Toolkit (AGT) wraps an agent with middleware that runs on every request: an audit trail of every invocation, a governance policy (a YAML file that can deny actions like SSN disclosure or destructive tool calls and audit sensitive queries), a capability guard that restricts which tools the agent may call, and rogue detection for behavioural anomalies. Its policy and audit decisions are exported to Application Insights, so agent governance is both enforced and observable — the same pattern you applied to model calls, now applied to agent actions.

Build, deploy, and govern a hosted agent

  1. In VS Code, open 7. citadel-hosted-agent-with-agt.ipynb from the workshop folder and select the workshop/.venv kernel.

  2. Run Steps 0–1 to read your azd environment and verify your Azure CLI sign-in.

  3. Run Step 2 – Generate Hosted Agent Source Files. This writes a Contoso HR Assistant into workshop/hosted-agent/: four benign HR tools (get_pto_balance, get_holiday_schedule, get_benefits_summary, get_open_enrollment_window) plus a deliberately destructive delete_user tool used to demonstrate policy blocking. The agent is wired to AGT and reaches the model through the BYO Gateway connection (Hub-HR-ChatAgent-DEV-LLM/gpt-4.1) — it deploys no model of its own.

  4. Run Step 3 – Build & Push Container Image. This uses az acr build to build the image in the cloud and push it to the spoke’s container registry — no local Docker required.

  5. Run Step 4 – Deploy Hosted Agent to Foundry and the remaining test cells. Confirm the governance behavior end-to-end: benign HR queries succeed, while SSN disclosure, third-party salary lookups, and the destructive delete_user call are denied by the policy — including across multi-turn and streaming responses. The AGT policy and audit spans are exported to Application Insights.

Publish a Foundry agent as a governed A2A endpoint

  1. Open 8. publish-and-use-a2a-endpoint.ipynb and select the workshop/.venv kernel.

  2. Run the Configuration, Helpers, and Resolve the Foundry environment cells. Every Azure resource name is resolved from your azd environment — nothing is hardcoded.

  3. Work through the lifecycle cells. The notebook:

    • creates a simple HR prompt agent on gpt-4.1;
    • enables the agent’s incoming A2A endpoint and verifies its agent card;
    • publishes the agent through APIM as a governed access contract (product + subscription);
    • calls the agent through APIM with only a subscription key — proving the gateway reaches the agent over its private endpoint even though the Foundry account has public network access disabled.
What is an Agent-to-Agent (A2A) endpoint, and why govern it through APIM?

Agent-to-Agent (A2A) is a standard way for one agent to call another: the callee publishes an agent card describing its skills, and callers invoke it over a well-known endpoint. Publishing that endpoint through APIM turns it into a governed access contract — callers present a subscription key, and the gateway meters, logs, and rate-limits agent-to-agent traffic exactly like model traffic. It also lets APIM reach a private-only agent on your behalf, so you never have to expose the agent publicly.

Both notebooks re-secure what they touch — the A2A notebook re-disables public network access on the Foundry account after it’s done. Follow each notebook’s own cleanup guidance.

✅ Checkpoint: A hosted agent runs with policy, capability, and audit governance on every action, and a Foundry agent is callable as a governed A2A endpoint through APIM with just a subscription key. Governance now extends from model calls to whole agents.

Next (optional): Task 7 — Publish and govern an HR MCP server through APIM