User Guide

Overview

This guide covers day-to-day operations for teams working with the Azure Foundry Enterprise Kit — from creating agents on Azure AI Foundry Agent Service to monitoring via Azure Monitor and managing lifecycle through the Foundry Control Plane.

Creating an Agent

Choose a blueprint from agent-templates/ that matches your use case
Copy and customize the agent manifest
Configure system prompts in the prompts/ directory
Set up toolbox config in toolbox-configs/
Run initial evaluation
Deploy via SDK client or CI/CD pipeline

Using the Python SDK

The Python SDK wraps the azure-ai-projects SDK 2.0 (AIProjectClient) with agent manifest resolution and Foundry Toolbox integration:

from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential

# Initialize Azure AI Foundry client
client = AIProjectClient(
    endpoint="https://your-project.services.ai.azure.com",
    credential=DefaultAzureCredential()
)

# Create agent with Foundry Agent Service
agent = client.agents.create_agent(
    model="gpt-4o",
    name="knowledge-agent",
    instructions=open("prompts/system-prompt.md").read(),
    tools=[{"type": "azure_ai_search", "connection": "ai-search-connection"}]
)

# Create thread and run
thread = client.agents.create_thread()
client.agents.create_message(thread.id, role="user", content="What is our refund policy?")
run = client.agents.create_and_process_run(thread.id, agent_id=agent.id)

Using the TypeScript SDK

The TypeScript SDK uses the @azure/ai-projects package for Azure AI Foundry integration with Entra ID authentication:

import AIProjectClient from '@azure/ai-projects';
import { DefaultAzureCredential } from '@azure/identity';

const client = new AIProjectClient(
  'https://your-project.services.ai.azure.com',
  new DefaultAzureCredential()
);

const agent = await client.agents.createAgent({
  model: 'gpt-4o',
  name: 'knowledge-agent',
  instructions: 'You are a knowledge retrieval agent...',
  tools: [{ type: 'azure_ai_search', connection: 'ai-search-connection' }]
});

const thread = await client.agents.createThread();
await client.agents.createMessage(thread.id, { role: 'user', content: 'What are the top 5 support tickets this week?' });
const run = await client.agents.createAndProcessRun(thread.id, { agentId: agent.id });

Monitoring Agents (Azure Monitor)

Agent telemetry flows through the OpenTelemetry SDK to Azure Application Insights via the azure-monitor-opentelemetry exporter, with structured fields defined in the Telemetry Schema. Use the pre-built KQL queries in observability/kql/ and the Azure Monitor Workbook for:

Agent response latency (P50, P95, P99)
Tool call success/failure rates
Token consumption by agent and model
Policy violation frequency
Trust score trends over time

Agent Lifecycle

Phase	Actions
Create	Define manifest, configure tools, write prompts
Evaluate	Run eval packs, verify trust score meets threshold
Deploy	Provision via Azure Bicep, deploy as Foundry Agent Application (ARM)
Monitor	Track via Azure Monitor + App Insights, run continuous evals
Promote	Certification pipeline gates: sandbox → staging → production
Update	Version bump, re-evaluate, promote through environments
Decommission	Disable agent, archive decision ledger, purge memory

Troubleshooting

Agent not responding — Check Azure AI Foundry project endpoint and model deployment status in the Azure Portal
Tool calls failing — Verify Foundry Toolbox MCP adapter health, check Azure Key Vault access and Redis token cache
Low trust scores — Review eval results in Azure Cosmos DB, check groundedness and policy compliance
Policy violations — Inspect Decision Ledger via Cosmos DB queries, review Foundry Control Plane audit logs
Guardrail triggers — Check Azure AI Content Safety logs, adjust severity thresholds in guardrails config