Agent Developer Portal

The complete guide for building enterprise-governed AI agents on the Azure Foundry Enterprise Kit. This portal covers every phase — from agent design through production observability — and clarifies exactly what you configure vs what the platform handles automatically.

The Core Principle

Developers declare. The platform enforces. You define your agent's identity, tools, policies, and quality gates in a YAML manifest. The Runtime Interceptor (ZT-05), APIM Gateway, CI/CD pipeline, and Decision Ledger enforce those rules — automatically and unavoidably. You never write governance code.

Developer Configures	Platform Enforces Automatically
Agent manifest (YAML)	Schema validation + deployment gating
System prompt with data policies	Runtime Interceptor checks every action
Guardrail thresholds	Azure Content Safety + Prompt Shield scanning
Toolbox allowlist	Per-step tool authorization (ZT-12)
Evaluation datasets	CI pipeline runs 14 evaluators, blocks on failure
Data boundary categories	Sensitive data pattern detection + ledger logging
Certification level target	Bronze → Silver → Gold automated gates
Telemetry tags	OpenTelemetry + App Insights + Decision Ledger capture

Phase 1: Design Your Agent

Step 1.1 — Scaffold from Template

Use the onboarding CLI to create your agent skeleton. This generates all required files with secure defaults, correct schema, and proper cross-references.

# Scaffold a new agent
python scripts/new_agent.py \
  --name hr-benefits \
  --class knowledge \
  --domain "HR / Employee Benefits" \
  --owner benefits-team@contoso.com

# Creates:
#   agent-templates/hr-benefits-agent/
#     agent-manifest.yaml         ← Your agent's complete definition
#     prompts/system-prompt.md    ← Your agent's instructions
#   toolbox-configs/hr-benefits-agent-toolbox.yaml
#   eval-packs/datasets/hr-benefits-agent-eval.json

Step 1.2 — Configure the Agent Manifest

The manifest is your agent's single source of truth. Every governance control, observability setting, and quality gate is declared here. The platform reads this manifest at deploy time and enforces it at runtime.

# agent-manifest.yaml — Key sections you MUST configure
metadata:
  name: enterprise-hr-benefits-agent
  version: 1.0.0
  agentClass: knowledge           # knowledge | analyst | operations | policy | workflow
  owner: benefits-team@contoso.com
  businessDomain: "HR / Employee Benefits"

model:
  deploymentName: gpt-4o-2025-03  # Your Azure OpenAI deployment
  temperature: 0.3                # Lower = more deterministic
  maxTokens: 8192

# Identity — HOW your agent authenticates
identity:
  type: managed                    # managed (recommended) | service-principal
  mcpAuthMethod: entra-agent       # Agent Identity for MCP calls
  mcpAuthScope: api://foundry-toolbox-prod/.default

# Toolbox — WHAT tools your agent can use
toolbox:
  toolboxName: hr-benefits-agent-toolbox
  approvalPolicy: auto             # auto | require (human approval per tool call)

# Grounding — WHERE your agent finds knowledge
grounding:
  provider: hybrid                 # azure-ai-search | cosmos-db-vector | hybrid
  indexName: hr-benefits-index
  queryType: hybrid                # semantic | vector | hybrid

# Guardrails — SAFETY thresholds (platform enforces these)
guardrails:
  pack: standard
  thresholds:
    groundedness: 0.80             # Response must be 80% grounded in sources
    safety: 0.95                   # Safety score must exceed 95%
    taskAdherence: 0.75            # Must stay on-task 75% of the time
  enablePiiDetection: true         # Auto-detect PII in responses
  enablePromptAttackDetection: true
  enableToolCallScanning: true     # Scan every tool input/output

# Data Access Policy — sensitive data categories
dataAccessPolicy:
  restrictedCategories:
    - compensation                 # Salary, wages, bonuses
    - government_id                # SSN, passport, tax IDs
    - health_data                  # Medical records, diagnoses
  bulkDataPolicy: deny             # Block "all employees" type queries

# CI/CD — quality gates for deployment
cicd:
  evaluationSuite: hr-benefits-eval-suite
  releaseGates:
    groundedness_min: 0.78
    safety_min: 0.93
    task_adherence_min: 0.72

# Compliance mapping
compliance:
  riskClassification: high
  zeroTrustControls: [ZT-01, ZT-05, ZT-06, ZT-08, ZT-12, ZT-17]

# Telemetry — business outcome tracking
telemetry:
  samplingRate: 1.0
  businessOutcomeTags:
    - agent.query.topic
    - agent.response.answered
    - agent.escalation.triggered

Step 1.3 — Write Your System Prompt

The system prompt defines your agent's personality, data access policies, and escalation behavior. The Data Access Policy section is critical — it's what makes the agent refuse sensitive data requests at the model level.

# prompts/system-prompt.md

You are a helpful HR Benefits assistant.

## Data Access Policy (MANDATORY)

### Restricted Data Categories
- **Compensation & Payroll**: NEVER return salary data. Direct to HR Self-Service.
- **Government Identifiers**: NEVER surface SSN, tax IDs, passport numbers.
- **Health & Medical**: Redirect to Benefits team.

### Bulk Data Restrictions
- NEVER return data for "all employees" or "entire department".
- Aggregate statistics allowed ONLY from published reports.

### Policy Trigger Response
When a query matches a restricted category:
1. Acknowledge the request professionally
2. Explain which data access policy applies
3. Provide the correct escalation path
4. Do NOT attempt to answer with any data

Design Checklist

Agent manifest created with all required sections
System prompt includes Data Access Policy
Guardrail thresholds set based on risk classification
Toolbox allowlist defined (principle of least privilege)
Evaluation dataset created (minimum 5 test queries)
Business outcome telemetry tags defined
Owner and escalation contacts specified

Quick Reference: Agent Developer Checklist

Files You Create

agent-manifest.yaml — Agent definition (identity, tools, guardrails, policies)
prompts/system-prompt.md — Agent instructions + data access policy
eval-packs/datasets/<name>-eval.json — Test queries + expected outcomes
toolbox-configs/<name>-toolbox.yaml — Tool definitions (if custom)

Platform Creates For You

Managed identity (Entra Agent Identity)
APIM API endpoint with JWT validation
Content Safety + Prompt Shield scanning
Runtime Interceptor policy enforcement
Decision Ledger in Cosmos DB
App Insights telemetry pipeline
Continuous evaluation schedule
Alert rules + remediation workflows

You Never Write

Content Safety API calls
Token validation / JWT verification code
Decision Ledger write logic
Observability instrumentation
Tool authorization middleware
Kill switch implementation
Policy evaluation engine
Compliance report generation

Full Architecture — 17 Zero Trust Modules

ZT-01 Identity Foundation — Entra ID + Agent Identity + managed credentials

ZT-02 API Gateway — APIM with JWT, rate limiting, IP filtering

ZT-03 AI Gateway — APIM AI policies (content safety, token limits, semantic cache)

ZT-04 Agent Registration — Certification pipeline (Bronze/Silver/Gold)

ZT-05 Runtime Interceptor — Per-step policy enforcement (the core innovation)

ZT-06 Content Safety — Azure Content Safety + Prompt Shield

ZT-07 MCP Gateway — MCP server auth, versioning, catalog

ZT-08 Observability — App Insights + Decision Ledger + KQL library

ZT-09 Compliance Mapping — NIST, EU AI Act, CAF, WAF alignment

ZT-10 Agent Publishing — Immutable release versioning

ZT-11 Agent-to-Agent — Authenticated inter-agent calls

ZT-12 Toolbox Governance — Tool allowlists + approval tiers

ZT-13 Distributed Tracing — OpenTelemetry + W3C trace context

ZT-14 Continuous Evaluation — Scheduled eval runs + drift detection

ZT-15 MCP Security — MCP server authentication + scanning

ZT-16 Compliance Automation — Automated compliance reporting

ZT-17 Data Residency — Data boundary enforcement + PII controls