Python is often the shortest path from an Azure AI prototype to maintainable application code, but SDK choice and client structure matter once the project grows. Microsoft Foundry exposes project-scoped APIs, model inference, agents, evaluations, and platform tools through several Python surfaces. The most useful pattern is to choose one abstraction deliberately instead of mixing portal-generated snippets, low-level HTTP calls, and several SDK generations in the same application.<\/p>\n
Current Microsoft documentation identifies That makes SDK design part of Azure AI engineering<\/a>, not merely a question of which import statement works.<\/p>\n A Foundry project is a useful application boundary because it collects models, agents, connections, evaluation assets, and observability under one context. Configure the project endpoint outside the code and create clients from environment or deployment configuration instead of hardcoding resource names.<\/p>\n One process should normally reuse a client rather than recreate authentication and transport state for every request. Reuse improves connection efficiency and gives the application one place to configure logging, timeouts, and correlation metadata.<\/p>\n If the application needs only Azure OpenAI inference, a direct OpenAI-compatible client may be simpler than a broader project client. The right abstraction is the smallest one that still matches the system’s actual responsibilities.<\/p>\n Use Azure Identity credentials such as The broader managed identity<\/a> pattern removes reusable secrets from service-to-service calls, but it does not remove the need for narrow RBAC roles. Give the runtime only the data-plane operations it requires.<\/p>\n Separate developer, deployment, and runtime identities so a production service does not inherit the permissions of the engineer who created it.<\/p>\n Application code should not expose SDK objects everywhere. Wrap model, agent, evaluation, or search calls behind small interfaces that express the application’s own operations.<\/p>\n A thin wrapper makes upgrades easier because SDK-specific request objects remain at the boundary. It also makes tests easier because the business logic can substitute a fake implementation without importing the cloud client.<\/p>\n Do not build a large internal framework that merely renames every SDK method. The wrapper should add domain value such as validation, retries, telemetry, or policy.<\/p>\n Transient network and service errors happen. SDKs often provide retry behavior, but application code still needs to understand whether repeating an operation is safe.<\/p>\n A read or stateless inference request can often be retried more safely than a request that creates a durable agent version, writes business data, or triggers a side effect. Attach a client correlation identifier and log the service request identifier so the retry chain can be reconstructed.<\/p>\n The REST guidance in REST API patterns<\/a> applies equally to SDK clients: retry only when the operation and error class justify it.<\/p>\n Async Python can improve throughput when the application spends significant time waiting on network calls and can process many independent requests concurrently. It is not automatically faster for every workload.<\/p>\n Use async when the application naturally performs parallel retrieval, tool calls, or many independent model requests. Keep concurrency bounded by model quota and downstream service limits.<\/p>\n Latency tuning<\/a> should confirm that concurrency reduces wall-clock time rather than merely increasing throttling.<\/p>\n Model deployment name, prompt version, tool definitions, retrieval index, evaluator configuration, and feature flags all affect behavior even if Python code is unchanged.<\/p>\n Keep those values explicit and versioned. A Python client should receive them as configuration rather than discovering them implicitly from mutable portal state.<\/p>\n Prompt versioning<\/a> becomes more useful when the application trace can identify which prompt and model configuration produced a response.<\/p>\n A model or agent should not become the only place where business control flow exists. Deterministic branching, approval, retries, and side-effect ordering belong in code or a durable workflow where the organization needs auditability.<\/p>\n Agent workflows<\/a> work best when Python code defines the boundaries around open-ended reasoning instead of asking the model to own every control decision.<\/p>\n This also makes unit testing practical because the deterministic orchestration can be tested without calling a model.<\/p>\n Log duration, deployment, token usage where available, retry count, status, and correlation identifiers around model and agent calls. Avoid logging sensitive prompt content by default.<\/p>\n AI observability<\/a> is strongest when the Python boundary contributes spans that connect application work to retrieval, model calls, tools, and downstream results.<\/p>\n Use the same telemetry vocabulary across synchronous and asynchronous code so production dashboards are not split by implementation detail.<\/p>\n The Foundry and Azure SDK surface will continue to evolve. Good Python architecture does not attempt to hide that evolution completely; it limits how far provider-specific details spread into the application.<\/p>\nazure-ai-projects<\/code> as the Python package for Foundry project operations and supports OpenAI-compatible access through the Foundry project endpoint. For new agent code, Microsoft recommends Agent Framework when its higher-level orchestration fits the workload; the OpenAI SDK remains useful when an application already follows OpenAI-compatible request and response patterns or needs lower-level control.<\/p>\nBuild clients around a project boundary<\/h3>\n
Prefer Microsoft Entra authentication<\/h3>\n
DefaultAzureCredential<\/code> for local development and managed identity in Azure-hosted environments. This avoids embedding API keys in code or configuration files.<\/p>\nKeep SDK wrappers thin<\/h3>\n
Make retries aware of operation semantics<\/h3>\n
Use async clients only when the workload benefits<\/h3>\n
Version configuration that changes behavior<\/h3>\n
Separate model calls from workflow control<\/h3>\n
Instrument the SDK boundary<\/h3>\n
Choose a durable abstraction and keep it replaceable<\/h3>\n