An AI prototype can hide enormous architectural differences behind a few successful requests. One developer may call a model endpoint directly, another may use a Foundry project client, and a third may invoke an agent through a framework that manages conversation state and tools. All three can produce plausible answers. Only one may fit the application’s required identity boundaries, tracing model, lifecycle controls and future deployment path. The SDK is not a cosmetic choice; it shapes which platform contracts the application takes responsibility for.
A Foundry application needs to know which endpoint owns a capability before choosing a client library. The SDK integration objective in Microsoft AI-103 spans project resources, model inference, tools, agents and multistep application state; no single package removes the need to validate authorization and response contracts. Choose the client by the operations required, pin the version actually tested and check that a sample uses the current Foundry rather than a classic project API.
Choose the client from the responsibility
Start with a sequence diagram, not a package installation command. If an application only needs a model-generated answer for a bounded task, it may use a suitable model inference client. If it needs access to project assets, managed tools, agents and platform configuration, the Foundry project SDK is a more natural integration boundary. Higher-level agent frameworks can organize runtime orchestration while relying on underlying platform clients for resources and services.
Microsoft’s current Foundry documentation distinguishes a project endpoint from service-specific model endpoints. The exact host and path matter because authentication scope, available operations and API compatibility follow the endpoint. A project endpoint is not interchangeable with an Azure OpenAI endpoint simply because both ultimately use a generative model. Store validated endpoint configuration by environment, and reject configuration that attempts to route credentials or requests to an unexpected host.
Before committing to an SDK, document the capabilities actually needed: model inference, file or knowledge tools, agent state, tracing, structured output, model deployment management and access to external APIs. A package’s existence does not guarantee every feature is available in every region, model or API version. Complete Foundry service selection first, then verify that the SDK, endpoint, model and region support the required operations.
Keep credentials and environments separated
Developer workstations, automated tests and production services should not share a long-lived unrestricted credential. Managed identity is preferable to long-lived application secrets where the Azure runtime and supported SDK permit it. Give the runtime only the roles it needs to use its project, model or data service; reserve resource creation and role assignments for deployment automation. Test the identity with a deliberately forbidden action, not merely a successful read.
Configuration should identify a project, deployment and related data services without embedding secrets in source code. A simple validation layer can fail early when a required environment variable is missing, a project points to the wrong subscription, or the expected resource name does not match the release manifest. This catches a common class of failures where code is correct but traffic silently reaches a test model or an obsolete index.
For a support assistant connected to account data, the model must not receive the caller’s full backend privileges by default. The application or tool adapter should resolve the caller’s authorization and enforce it before retrieving records or executing changes. Proper AI workload security keeps business authorization in the application or tool adapter; an SDK can simplify connectivity but cannot authorize a user to retrieve another customer’s records.
Treat tool schemas as executable contracts
An agent tool has a name, description, argument schema and implementation. The schema should make the permitted action narrow and unambiguous. An instruction such as “update customer details” is dangerous if the tool can also change payment destinations or approve account closures. Prefer distinct tools with explicit required fields, constrained values and clear error responses. Validate incoming arguments on the server regardless of what the model generated.
Separate the tool’s public contract from its downstream transport. A pricing tool might accept a product ID and region even if its implementation joins several services. This keeps the agent from depending on internal database details that may change. When the transport fails, return a typed result indicating whether the request was rejected, retried safely, partially accepted or completed. Avoid translating every failure into empty text, which invites the agent to improvise.
Use test fixtures for valid and invalid tool calls. Check missing arguments, unexpected properties, oversized input, unauthorized data selection and an expired user session. A tool result that contains outside text should be treated as data, not as a trusted instruction to ignore policy. Use Building agents in Foundry to constrain the agent role and tool schema; the implementation layer must make those boundaries enforceable.
Conversation state is not an unlimited transcript
Agents need enough state to continue a task, but copying the whole conversation into every request is rarely a durable design. Decide what belongs in short-lived context, what can be summarized, which facts require authoritative retrieval and what must never be persisted. The model’s generated summary may be useful context, but it should not replace an actual transaction record or an approval event.
A booking assistant illustrates the distinction. It may remember that the user prefers morning flights, but a selected fare, passenger identity and payment authorization should be represented as validated application state. If the model proposes a purchase twice after a network timeout, the application must recognize the same operation ID and reconcile whether the first request completed. Without that contract, an otherwise eloquent assistant can create duplicate side effects.
Multi-agent orchestration adds more state owners. A delegated worker should receive the information needed for its task rather than the supervisor’s entire context, especially when the worker can call a narrower set of tools. Handoff messages should identify the requested result, relevant evidence, allowed actions and outcome status. That makes the interactions in Multi-agent orchestration traceable and testable.
Handle streaming and asynchronous work deliberately
Streaming a model response can improve perceived responsiveness, but the stream is not a commitment that every subsequent token will be valid or that a tool action has completed. Design the client to distinguish partial text, final structured output, cancellations and errors. If a safety or authorization decision is still pending, do not surface an irreversible action simply because the model began generating a convincing explanation.
Some platform operations are better represented as background jobs or long-running workflows than as one synchronous HTTP request. A document ingestion or media generation task may require the application to submit work, record an operation identifier and later retrieve a terminal result. Use bounded polling or event-driven completion where supported, and handle expiration and cancellation explicitly. The UI should not keep showing an indefinite spinner when the job has entered a failed state.
Timeout boundaries are also part of correctness. If an agent times out while an external system is executing a write, a retry should first determine the previous outcome. Provide a correlation ID through the request path and retain only the minimum necessary operational data for audit. These contracts become especially valuable during deployment changes when the app and a tool service are temporarily at different versions.
Version SDKs and tests with the platform
The new Microsoft Foundry experience uses the 2.x generation of the azure-ai-projects Python SDK against a Foundry project endpoint; the 1.x line targets Foundry (classic). Microsoft’s SDK documentation distinguishes the unified project client from an OpenAI-compatible inference endpoint and separate Foundry Tools endpoints. Pin a tested package version and match code examples to the resource type and API generation actually deployed. A working classic-agent sample is not a safe migration plan merely because its imports still resolve.
Wrap platform calls behind small interfaces that express application needs rather than spreading SDK objects through business logic. One adapter can translate a typed request into model inference, another can retrieve permitted evidence and another can submit an authorized business action. This separation makes it possible to test error behavior without calling the live model for every unit test, while integration tests still exercise the actual supported SDK.
Run contract tests across supported environments. They should verify authentication scope, expected response structure, tool invocation semantics, structured output validity and trace correlation. When a model or SDK update alters behavior, failures should identify the changed boundary. Deploying Foundry projects demands tests for permissions, quotas and dependencies before moving a Foundry project from local validation to production.
Build a test pyramid around real decisions
Unit tests should cover argument validation, authorization checks, idempotency and deterministic adapters. Integration tests should prove the correct project and model deployment can be reached with production-like identity. Behavioral tests need representative prompts, document evidence and expected tool trajectories. A model answer that reads well can still be wrong if it used a forbidden data source or skipped the required approval step.
Keep evaluation cases specific. Ask a retrieval assistant a question whose answer is missing from the approved corpus and confirm that it expresses uncertainty; ask an account agent to perform a prohibited modification and verify that the tool layer rejects it. Include a stale index, an injected instruction in a document, an unavailable backend and a long multi-turn conversation. These cases test the whole system rather than a single happy-path chat request.
The quality signals collected in AI observability and evaluation belong in CI and later production monitoring. Compare a candidate release with a baseline on successful task completion, grounded evidence, forbidden actions, tool failures, latency and operational cost. Don’t accept a model change only because it produces more polished prose in a few demonstrations.
Keep the application contract understandable
As the stack grows, the temptation is to bury every decision inside agent instructions. Resist it. Authentication, authorization, payment limits, data retention and API-side validation are engineering controls. The model should decide among permitted task strategies and tools, not whether the application still needs those controls. A clear separation makes code reviews, threat modeling and incident analysis possible.
Document which component owns each failure. An invalid model parameter belongs at the client/deployment boundary; stale retrieved facts belong in ingestion and retrieval; an unauthorized tool call belongs in the tool authorization layer; an unsafe generated answer belongs in safety and evaluation. Treating all four as “bad prompting” wastes time and can produce fragile fixes.
Stable application design makes the SDK an implementation detail rather than the owner of business policy. Keep model calls, evidence retrieval and side-effecting tools behind narrow tested interfaces. Then an SDK upgrade or Foundry API transition can be reviewed against explicit response, identity, version and tracing contracts without silently changing what the agent is allowed to do.