template-agentic-ai-apps-azure

Reference for using and extending agentkit — YAML-driven agent specification loading and validation. Use when defining agent specs, loading YAML configs, extending AgentSpec with custom fields, or managing multiple agent configurations.

Validates the entire template stack works end-to-end — tests, Docker, infra, health checks. Use after making cross-layer changes, before PRs, or when verifying template integrity.

Reference for using and extending evalkit — evaluation framework with protocol-based evaluators, weighted rubric scoring, quality gates, and coaching moments. Use when creating custom evaluators, configuring rubrics, understanding scoring, or extending the evaluation framework.

Reference for using and extending foundrykit — Azure AI Foundry client, AgentManager, ToolRegistry, and FoundrySettings. Use when working with Azure AI credentials, creating/running agents, registering tools, or extending foundrykit for custom needs.

Validates performance and concurrency behavior of backend endpoints. Use when preparing for production, checking latency under load, or verifying system stability.

Confirms deployability and basic system health after deployment or container start. Use after azd deploy, docker compose up, or any deployment to verify the system is alive.

Reference for using and extending synthetickit — 3-stage synthetic data generation with scenarios, quality gates, and provenance tracking. Use when generating evaluation datasets, defining scenarios, writing custom generators/classifiers, or extending the pipeline.

Reference for using and extending testkit — shared test fakes for Cosmos DB, LLM, Foundry, MCP, SSE, and storage. Use when writing tests, creating custom fakes, understanding assertion helpers, or extending testkit for new infrastructure.

Creates a domain evaluation pipeline using evalkit. Use when setting up evaluations, defining quality metrics, creating evaluators, or building eval rubrics for an agentic app.

Creates a synthetic data generation pipeline using synthetickit. Use when generating test data, creating golden evaluation sets, building demo datasets, or defining edge-case scenarios.

Sets up test infrastructure using testkit shared fakes. Use when writing tests, creating test fixtures, setting up FakeCosmosContainer, FakeLLMClient, or testing SSE streams.

Guides adding a new FastAPI endpoint with Pydantic models, routing, and tests. Use when creating a new API route, adding a REST endpoint, or extending the backend API surface.

Adds a new Azure resource to the Terraform infrastructure. Use when provisioning a new Azure service, adding a resource to Terraform, or extending cloud infrastructure.

Adds a new feature to the React chat UI — new event types, components, or interactions. Use when extending the chat interface, adding new SSE event rendering, or building new UI components.

Creates a new AI agent using YAML specs, foundrykit AgentManager, and ToolRegistry. Use when building a new agent, defining agent behavior, writing agent specs, or configuring agent tools and prompts. Covers which library to use for each concern: agentkit for spec/config, foundrykit for runtime/credentials/tools.

Deploys the application to Azure using azd and Terraform. Use when deploying, provisioning cloud resources, running azd provision, azd deploy, or setting up Azure infrastructure.

Works with Azure Cosmos DB — containers, partition keys, queries, and storage integration. Use when working with Cosmos DB, designing partition keys, adding containers, or optimizing queries.

Runs the full stack locally with Docker Compose. Use when starting local development, running docker compose, debugging containers, or testing the full application locally.

Guides forking and customizing this template for a new project. Use when starting a new project from this template, cloning the template, or adapting it for a specific domain.

Builds or extends an MCP (Model Context Protocol) server with new tools. Use when creating MCP tools, adding MCP endpoints, building an MCP server, or extending mcp-server-template.

Configures OpenTelemetry tracing, structured logging, and Azure Application Insights. Use when setting up observability, adding custom spans, configuring tracing exporters, connecting to App Insights, or debugging performance issues.

Adds a new storage backend implementing the Storage protocol. Use when adding a database, cache, or persistence layer beyond InMemory and Cosmos DB.

Registers a new agent tool via ToolRegistry with OpenTelemetry tracing. Use when creating a new tool function, adding a tool to an agent, or extending the tool surface.

Diagnoses and fixes common errors in the agentic app template. Use when debugging failures, fixing broken agent flows, resolving SSE streaming issues, troubleshooting Cosmos DB connections, or diagnosing deployment errors.

Writes pytest tests for backend endpoints, services, and tools. Use when adding tests, writing test fixtures, testing API endpoints, testing streaming, or improving test coverage.