ericchansen · ericchansen · Mar 24, 2026 · Mar 24, 2026 · Mar 24, 2026
diff --git a/docs-site/architecture.md b/docs-site/architecture.md
@@ -17,13 +17,13 @@ no rollback capability. The SDK is the only path to automation.
 
 ---
 
-## Decision 2: Delete + Recreate (Not Update)
+## Decision 2: Versioned Agents (Not Delete + Recreate)
 
-**Decision:** Each deployment deletes the old agent and creates a fresh one.
+**Decision:** Each deployment creates a new **version** of the agent using `agents.create_version()`.
 
-**Why:** Guarantees the deployed agent matches code exactly. No drift.
+**Why:** Guarantees the deployed agent matches code exactly. No downtime — old version stays active until the new one is ready. Agent ID is stable across versions.
 
-**Trade-off:** Agent ID changes. Use names, not IDs, for all integrations.
+**Trade-off:** Versions accumulate (use the teardown script to clean up old agents).
 
 ---
 

diff --git a/docs-site/concepts/agent-definition.md b/docs-site/concepts/agent-definition.md
@@ -11,7 +11,7 @@ This is the most important file in the repository. It:
 1. Loads a per-environment JSON config file
 2. Reads the system prompt from a markdown file
 3. Resolves tool definitions from Python code
-4. Produces the exact parameters for `client.agents.create()`
+4. Produces the exact parameters for `agents.create_version()`
 
 ```python title="src/agent/agent_definition.py" linenums="1"
 @dataclass
@@ -24,7 +24,7 @@ class AgentConfig:
     metadata: dict
 
     def to_sdk_params(self) -> dict:
-        """Convert to the dict that agents.create() expects (SDK v2)."""
+        """Convert to the dict that agents.create_version() expects (SDK v2)."""
         from azure.ai.projects.models import PromptAgentDefinition
 
         # Filter to SDK-compatible built-in tools
@@ -48,7 +48,7 @@ class AgentConfig:
 !!! info "SDK v2 — `PromptAgentDefinition`"
     The `azure-ai-projects` SDK v2 wraps model, instructions, and tools into a
     `PromptAgentDefinition` object. This is passed as the `definition` parameter
-    to `agents.create()`. The old v1 flat-parameter style (`create_agent(model=..., instructions=...)`)
+    to `agents.create_version()`. The old v1 flat-parameter style (`create_agent(model=..., instructions=...)`)
     no longer works.
 
 ## Config File → AgentConfig → SDK Call
@@ -60,7 +60,7 @@ graph LR
     D[tools/*.py] --> B
     B --> E[AgentConfig]
     E --> F[to_sdk_params]
-    F --> G[agents.create]
+    F --> G[agents.create_version]
     style E fill:#9f6,stroke:#333
 ```
 

diff --git a/docs-site/concepts/mental-model.md b/docs-site/concepts/mental-model.md
@@ -38,7 +38,7 @@ but with different config.
 !!! info "Key Insight"
     There is no export/import or artifact promotion mechanism.
     Your code and config **are** the deployment unit. The SDK
-    recreates the agent fresh in each environment.
+    creates a new versioned agent in each environment.
 
 ## What Makes Up an Agent?
 
@@ -66,8 +66,8 @@ client = AIProjectClient(
     credential=DefaultAzureCredential()
 )
 
-agent = client.agents.create(
-    name="my-agent-dev",
+agent = client.agents.create_version(
+    agent_name="my-agent-dev",
     definition=PromptAgentDefinition(
         model="gpt-4o-mini",
         instructions="You are a helpful assistant...",
@@ -77,27 +77,26 @@ agent = client.agents.create(
 )
 ```
 
-That's it. **Everything else in this repo is plumbing around this call.**
+That's it. **Everything else in this repo is plumbing around this call.** If the agent name already exists, it creates a new version; if not, it creates the agent.
 
 - Config files → decide what parameters to pass
 - Deploy scripts → wrap this call with error handling and logging
 - CI/CD pipelines → run this call in the right environment with the right auth
 - Evaluation → validate the agent works after this call
 
-## Why Delete + Recreate?
+## Why Versioned Agents?
 
-We delete the old agent and create a fresh one on each deployment.
-When delete fails (e.g., RBAC restrictions), the script falls back to updating the existing agent.
+We create a new **version** of the agent on each deployment using `agents.create_version()`.
+If the agent name doesn't exist yet, it creates the agent. If it already exists, it adds a new version with the updated config.
 
-**Why not just update in place?**
+**Why not delete and recreate?**
 
-1. **Guarantees consistency** — the agent matches the code exactly
-2. **No drift risk** — partial updates can leave agents in inconsistent states
-3. **Simpler logic** — create is idempotent, update has edge cases
-4. **Audit trail** — metadata tracks which git commit is deployed
+1. **No downtime** — old version stays active until the new one is ready
+2. **Stable identity** — agent name persists across deployments
+3. **Audit trail** — metadata tracks which git commit is deployed per version
+4. **Simpler logic** — `create_version()` handles both new and existing agents
 
 **The trade-off:**
 
-- Agent ID changes each deployment (use names, not IDs)
-- Milliseconds of "downtime" during delete → create
-- Conversation threads don't carry over (by design — new deploy, fresh start)
+- Agent versions accumulate (use the teardown script to clean up)
+- Must ensure consumers reference the correct version or latest
diff --git a/docs-site/faq.md b/docs-site/faq.md
@@ -34,8 +34,9 @@ pip install -e ".[dev]"
 ### What API does the SDK call?
 
 The Azure AI Agents API (based on the OpenAI Assistants API).
-The key method is `client.agents.create()` (SDK v2). Model, instructions,
-and tools are wrapped in a `PromptAgentDefinition` object.
+The key method is `agents.create_version()` (SDK v2). Model, instructions,
+and tools are wrapped in a `PromptAgentDefinition` object. The call creates
+the agent if new, or adds a new version if it already exists.
 
 ### Does the SDK support other languages?
 

diff --git a/docs-site/index.md b/docs-site/index.md
@@ -41,10 +41,10 @@
 
 !!! warning "There is no artifact to promote"
     Unlike containers or binaries, Foundry agents can't be exported and imported.
-    **CI/CD = recreate the agent from code** in each environment using the SDK.
+    **CI/CD = deploy the agent from code** in each environment using the SDK.
 
     This is by design. There is no export/import mechanism — your code and config
-    **are** the deployment artifact. The SDK recreates the agent fresh each time.
+    **are** the deployment artifact. The SDK creates a new versioned agent each time.
 
 ## Before You Start
 

diff --git a/docs/how-it-works.md b/docs/how-it-works.md
@@ -129,8 +129,7 @@ This script:
 3. Resolves tool definitions from Python code
 4. Builds a `PromptAgentDefinition` (SDK v2) with model, instructions, tools
 5. Connects to the DEV Foundry project
-6. Checks if the agent exists → deletes old version (or updates if delete fails)
-7. Creates a new agent via `agents.create()`
+6. Calls `agents.create_version()` — creates the agent if new, or adds a new version if it already exists
 
 ### 4c. Evaluate the Agent
 ```bash

diff --git a/src/agent/agent_definition.py b/src/agent/agent_definition.py
@@ -49,7 +49,7 @@ class AgentConfig:
     def to_sdk_params(self) -> dict:
         """
         Convert this config into the parameters that the
-        azure-ai-projects SDK v2 expects for agents.create().
+        azure-ai-projects SDK v2 expects for agents.create_version().
 
         SDK v2 uses a PromptAgentDefinition object instead of flat params.
         """