Build AI Apps with Azure AI Projects SDK

Azure AI Projects Python SDK provides guidance for Microsoft Foundry project connections, model deployments, versioned agents, evaluation datasets, and cloud evaluation workflows. It begins by identifying the installed SDK generation so examples match the actual client. The checked 2.0.0b4 snapshot uses versioned agents, OpenAI conversations and responses, and beta namespaces for evaluators, memory, and schedules. Classic thread/run recipes belong to azure-ai-agents rather than a v2 project client.

The workflow establishes the tenant, project, installed versions, requested resources, and data classification before selecting a deployment. Connection and deployment metadata inform that choice; listing metadata does not require retrieving connection secrets. The project endpoint must be the exact authorized HTTPS URL, and the deployment value must name a real deployment rather than an assumed model alias.

Use the skill for an explicitly scoped Foundry project task involving connections, agents, datasets, or evaluations. Work in an isolated environment with reviewed, locked compatible versions of azure-ai-projects, azure-identity, and openai. Later SDK versions can differ from the documented snapshot, so installed APIs and the migration guidance remain relevant.

Documentation review is not authorization to run cloud evaluations. Local checks cannot prove live Azure availability, model quality, legal compliance, or safe autonomous tool use. Evaluation scores are sampled judgments tied to service versions and judge configuration. Reports should include missing scores, failures, sample counts, and the judge configuration; keyword checks do not establish compliance, and JSON output still needs parsing and schema validation.

Inputs include the authorized endpoint, tenant identity, deployment, selected files, compatible package versions, and bounded resource requirements. A Python configuration uses this project client import:

from azure.ai.projects import AIProjectClient

Its complete example creates an explicitly requested agent version and references that version in a response request. Creation, upload, and cleanup remain scoped to the task. A timeout during creation requires reconciling the result before retrying, and deletion is limited to task-created resources specifically intended for cleanup.

The batch evaluation helper uploads the entire selected JSONL file and creates an evaluation and run. It can incur cloud and model charges. Its allow-paid option is an execution opt-in after authorization of the exact file, endpoint, evaluators, deployment, and budget; it neither estimates nor enforces spending. Consistent schemas and required mapped fields are checked before upload. Local output is new-only with mode 0600. Polling timeout does not cancel remote execution, so evaluation and run IDs are needed for reconciliation or documented cancellation.

Use the intended least-privilege credential chain without exposing credentials or private traces. Enable only necessary tools and validate proposed tool arguments, destinations, permissions, and effects before execution. Remote MCP endpoints must be reachable from the cloud; localhost does not refer to the user's machine. Selected uploads require approval beyond file-extension filtering. Persistent memory needs tenant and user isolation plus retention and deletion rules. Timeouts, polling, concurrency, row counts, and spending all require explicit bounds.