> ## Documentation Index
> Fetch the complete documentation index at: https://hobbyist-e43fa225.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Migrate to the new Foundry Agent Service
> Learn how to migrate from the Assistants API and classic agents to the new Foundry Agent Service, including threads to conversations, runs to responses, and updated SDK patterns.
A [migration tool](https://aka.ms/agent/migrate/tool) is available to help automate migration from the Assistants API to Agents.
Foundry Agent Service provides an upgraded developer experience for building intelligent agents that are easy to build, version, operate, and observe. The new agents API introduces a modernized SDK, new enterprise-grade capabilities, and preserves the identity, governance, and observability features you rely on today.
## Prerequisites
* An Azure subscription. [Create one for free](https://azure.microsoft.com/pricing/purchase-options/azure-account?cid=msft_learn).
* A [Microsoft Foundry project](../../how-to/create-projects).
* The Foundry Agent Service SDK for your language, and corresponding identity package for authentication. Install the packages for your language and sign in with `az login` or use `DefaultAzureCredential`:
```bash Python theme={null}
pip install "azure-ai-projects>=2.3.0"
```
```bash C# theme={null}
dotnet add package Azure.AI.Projects
dotnet add package Azure.AI.Projects.Agents
dotnet add package Azure.AI.Extensions.OpenAI
dotnet add package Azure.Identity
```
```bash JavaScript theme={null}
npm install @azure/ai-projects@2.3.0
npm install @azure/identity
```
```xml Java theme={null}
com.azure
azure-ai-agents
2.2.0
com.azure
azure-identity
1.18.4
```
* Existing agents or assistants code that you want to migrate.
The following code initializes the clients used throughout this guide:
```python Python theme={null}
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
# Format: "https://resource_name.services.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"
project = AIProjectClient(
endpoint=PROJECT_ENDPOINT,
credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()
```
```csharp C# theme={null}
using Azure.AI.Projects;
using Azure.AI.Extensions.OpenAI;
using Azure.Identity;
AIProjectClient projectClient = new(
new Uri(Environment.GetEnvironmentVariable(
"PROJECT_ENDPOINT")!),
new DefaultAzureCredential());
```
```javascript JavaScript theme={null}
import { AIProjectClient } from "@azure/ai-projects";
import { DefaultAzureCredential }
from "@azure/identity";
const projectClient = new AIProjectClient(
process.env["PROJECT_ENDPOINT"],
new DefaultAzureCredential()
);
const openAIClient = await projectClient
.getOpenAIClient();
```
```java Java theme={null}
import com.azure.ai.agents.AgentsClient;
import com.azure.ai.agents.AgentsClientBuilder;
import com.azure.identity.DefaultAzureCredentialBuilder;
AgentsClient agentsClient =
new AgentsClientBuilder()
.credential(
new DefaultAzureCredentialBuilder()
.build())
.endpoint(System.getenv(
"PROJECT_ENDPOINT"))
.buildAgentsClient();
```
Use `project` for agent creation and versioning. Use `openai` (or the equivalent in your language) for conversations and responses.
### Key benefits
The new agents provide the following benefits:
**Developer productivity**
* ⭐ **More models.** Generate responses by using any Foundry model either in your agent or directly as a response generation call.
* **More features.** Web Search, File Search, Code Interpreter, MCP tool calling, image generation, and reasoning summaries.
* **Modern API primitive.** Built on the Responses API instead of the older Assistants API.
* **Background mode**. Support for long-running tools (like image-generation), and durable streams (supports disconnect/reconnect scenarios)
* **Future-proof.** New features and model support are only added to the new agents.
* **New agent types.** Create prompt-based agents and Hosted agents.
**Enterprise readiness**
* ⭐ **Single-tenant storage.** Use single-tenant storage, with the option to bring your own Azure Cosmos DB to store state and keep your data secure.
* **Enhanced security.** Control who can run or modify agent definitions.
* **Separation of duties.** Define agents once and execute them with various inputs.
* **Deployable agents.** Agents can be exposed as individual endpoints.
**API modernization**
* **Improved state management.** Uses conversations instead of threads and messages.
* **Stateful context.** Automatically retains context across calls.
* **Superset of Responses API.** Builds on the Responses API and adds more capabilities.
* **Single or multi-agent workflows.** Easily chain agents for complex workflows.
## Key changes
The following table summarizes the main API changes between the previous and current agent experience.
| Before | After | Details |
| ------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------- |
| Threads | Conversations | Supports streams of items, not just messages. |
| Runs | Responses | Responses send input items or use a conversation object and receive output items. Tool call loops are explicitly managed. |
| Assistants / agents | Agents (new) | Support for enterprise-ready prompt and Hosted agents with stateful context by default for any Foundry model. |
## Agent tool availability
The following table compares agent tools available in classic agents and the new Foundry Agent Service. Use it to identify which tools carry over directly, which have changed, and which are exclusive to the new experience.
| Tool | Foundry (classic) | Foundry (new) |
| --------------------------------- | -------------------- | ------------------------------------------------------------- |
| Agent to Agent (A2A) | No | Yes (Public Preview) |
| Azure AI Search | Yes (GA) | Yes (GA) |
| Azure Functions | Yes (GA) | No |
| Browser Automation | Yes (Public Preview) | Yes (Public Preview) |
| Code Interpreter | Yes (GA) | Yes (GA) |
| Computer Use | Yes (Public Preview) | Yes (Public Preview) |
| Connected Agents | Yes (Public Preview) | No (Recommendation: A2A tool) |
| Deep Research | Yes (Public Preview) | No (Recommendation: Deep Research model with Web Search tool) |
| Fabric Data Agent | Yes (Public Preview) | Yes (Public Preview) |
| File Search | Yes (GA) | Yes (GA) |
| Function | Yes (GA) | Yes (GA) |
| Grounding with Bing Search | Yes (GA) | Yes (GA) |
| Grounding with Bing Custom Search | Yes (Public Preview) | Yes (Public Preview) |
| Image Generation | No | Yes (Public Preview) |
| MCP | Yes (Public Preview) | Yes (GA) |
| OpenAPI | Yes (GA) | Yes (GA) |
| SharePoint Grounding | Yes (Public Preview) | Yes (Public Preview) |
| Web Search | No | Yes (GA) |
In the new API, the conversations and responses APIs use the **OpenAI client** (or its language equivalent). In Python, call `project.get_openai_client()`. In C#, use `projectClient.ProjectOpenAIClient.GetProjectResponsesClientForAgent()`. In JavaScript, call `projectClient.getOpenAIClient()`. In Java, use `AgentsClientBuilder` to build a `ResponsesClient`. Agent creation and versioning remain on the **project client**. The examples in each section show which client to use.
## Migrate threads to conversations
Threads stored messages on the server side. A conversation can store items, including messages, tool calls, tool outputs, and other data.
### Requests
The following examples compare thread creation (previous) with conversation creation (current). The current approach uses the OpenAI client obtained from `project.get_openai_client()`.
**Previous - threads**
```python Python theme={null}
thread = client.agents.threads.create(
messages=[{"role": "user", "content": "Tell me a one line funny story about unicorns"}],
metadata={"agent": "my-awesome-agent"},
)
```
```csharp C# theme={null}
AgentThread thread =
await agentsClient.CreateThreadAsync(
messages: new[]
{
new ThreadMessageOptions(
MessageRole.User,
"Tell me a one line funny "
+ "story about unicorns")
},
metadata:
new Dictionary
{
["agent"] = "my-awesome-agent"
});
```
```javascript JavaScript theme={null}
const thread =
await client.agents.createThread({
messages: [
{
role: "user",
content:
"Tell me a one line funny "
+ "story about unicorns",
},
],
metadata: {
agent: "my-awesome-agent",
},
});
```
```java Java theme={null}
AgentThread thread =
agentsClient.createThread(
new CreateThreadOptions()
.setMessages(Arrays.asList(
new ThreadMessageOptions(
MessageRole.USER,
"Tell me a one line "
+ "funny story about "
+ "unicorns")))
.setMetadata(Map.of(
"agent",
"my-awesome-agent")));
```
**Current - conversations**
```python Python theme={null}
conversation = openai.conversations.create(
items=[
{
"type": "message",
"role": "user",
"content": "Tell me a one line funny "
"story about unicorns",
}
],
metadata={"agent": "my-awesome-agent"},
)
```
```csharp C# theme={null}
ProjectResponsesClient responsesClient =
projectClient.OpenAI
.GetProjectResponsesClientForAgent(
"my-awesome-agent");
var result = responsesClient.CreateResponse(
"Tell me a one line funny story "
+ "about unicorns");
```
```javascript JavaScript theme={null}
const conversation =
await openAIClient.conversations.create({
items: [
{
type: "message",
role: "user",
content:
"Tell me a one line funny "
+ "story about unicorns",
},
],
metadata: { agent: "my-awesome-agent" },
});
```
```java Java theme={null}
ResponsesClient responsesClient =
new AgentsClientBuilder()
.credential(
new DefaultAzureCredentialBuilder()
.build())
.endpoint(System.getenv(
"PROJECT_ENDPOINT"))
.buildResponsesClient();
AgentReference agentRef = new AgentReference("my-agent");
Response result = responsesClient.createAzureResponse(
new AzureCreateResponseOptions()
.setAgentReference(agentRef),
ResponseCreateParams.builder()
.input("Tell me a one line funny story about unicorns"));
```
### Responses
The JSON responses show the structural differences between thread objects and conversation objects.
**Previous - threads**
```json theme={null}
{
"id": "thread_1234abcd",
"object": "thread",
"created_at": 1762217858,
"metadata": {"agent": "my-awesome-agent"},
"tool_resources": {}
}
```
**Current - conversations**
```json theme={null}
{
"id":"conv_1234abcd",
"created_at":1762217961,
"metadata":{"agent":"my-awesome-agent"},
"object":"conversation"
}
```
### Add items to an existing conversation
After you create a conversation, use `conversations.items.create()` to add subsequent messages. This pattern replaces adding messages to threads with `client.agents.messages.create()`.
**Previous - add a message to a thread**
```python Python theme={null}
message = client.agents.messages.create(
thread_id=thread.id,
role="user",
content="Follow-up question about the same topic",
)
```
```csharp C# theme={null}
ThreadMessage message =
await agentsClient.CreateMessageAsync(
thread.Id,
MessageRole.User,
"Follow-up question about "
+ "the same topic");
```
```javascript JavaScript theme={null}
const message =
await client.agents.createMessage(
thread.id,
{
role: "user",
content:
"Follow-up question about "
+ "the same topic",
}
);
```
```java Java theme={null}
ThreadMessage message =
agentsClient.createMessage(
thread.getId(),
new CreateMessageOptions(
MessageRole.USER,
"Follow-up question about "
+ "the same topic"));
```
**Current - add items to a conversation**
```python Python theme={null}
openai.conversations.items.create(
conversation_id=conversation.id,
items=[
{
"type": "message",
"role": "user",
"content": "Follow-up question "
"about the same topic",
}
],
)
```
```csharp C# theme={null}
// In C#, send follow-up input directly
// through the responses client.
var followUp = responsesClient.CreateResponse(
"Follow-up question about the same topic");
```
```javascript JavaScript theme={null}
await openAIClient.conversations.items.create(
conversation.id,
{
items: [
{
type: "message",
role: "user",
content:
"Follow-up question "
+ "about the same topic",
},
],
}
);
```
```java Java theme={null}
// In Java, send follow-up input directly
AgentReference agentRef = new AgentReference("my-agent");
Response result = responsesClient.createAzureResponse(
new AzureCreateResponseOptions()
.setAgentReference(agentRef),
ResponseCreateParams.builder()
.input("Follow-up question "
+ "about the same topic"));
```
## Migrate runs to responses
Runs were asynchronous processes that executed against threads. Responses are simpler: provide a set of input items to execute and get a list of output items back. Responses can be used alone, or with conversation objects for storing context. The responses API uses the OpenAI client.
### Requests
The following examples compare how you invoke agent logic. The previous approach used asynchronous runs with polling. The current approach calls `responses.create()` on the OpenAI client.
**Previous - runs**
```python Python theme={null}
thread_id = "thread_abcd1234"
assistant_id = "asst_efgh5678"
run = project_client.agents.runs.create(
thread_id=thread_id,
agent_id=assistant_id,
additional_instructions="Please address the user as Jane Doe. The user has a premium account"
)
while run.status in ("queued", "in_progress"):
time.sleep(1)
run = project_client.agents.runs.get(thread_id=thread_id, run_id=run.id)
```
```csharp C# theme={null}
string threadId = "thread_abcd1234";
string assistantId = "asst_efgh5678";
ThreadRun run =
await agentsClient.CreateRunAsync(
threadId,
assistantId,
additionalInstructions:
"Please address the user as "
+ "Jane Doe. The user has a "
+ "premium account");
while (run.Status == RunStatus.Queued
|| run.Status ==
RunStatus.InProgress)
{
await Task.Delay(1000);
run = await agentsClient.GetRunAsync(
threadId, run.Id);
}
```
```javascript JavaScript theme={null}
const threadId = "thread_abcd1234";
const assistantId = "asst_efgh5678";
let run = await client.agents.createRun(
threadId,
assistantId,
{
additionalInstructions:
"Please address the user as "
+ "Jane Doe. The user has a "
+ "premium account",
});
while (run.status === "queued"
|| run.status === "in_progress") {
await new Promise(
(r) => setTimeout(r, 1000));
run = await client.agents.getRun(
threadId, run.id);
}
```
```java Java theme={null}
String threadId = "thread_abcd1234";
String assistantId = "asst_efgh5678";
ThreadRun run =
agentsClient.createRun(
threadId,
assistantId,
new CreateRunOptions()
.setAdditionalInstructions(
"Please address the user "
+ "as Jane Doe. The user "
+ "has a premium account"));
while (RunStatus.QUEUED
.equals(run.getStatus())
|| RunStatus.IN_PROGRESS
.equals(run.getStatus())) {
Thread.sleep(1000);
run = agentsClient.getRun(
threadId, run.getId());
}
```
**Current - responses**
```python Python theme={null}
conversation_id = "conv_11112222AAAABBBB"
response = openai.responses.create(
input="Hi, Agent! Draw a graph for a line "
"with a slope of 4 and "
"y-intercept of 9.",
conversation=conversation_id,
extra_body={
"agent_reference": {
"name": "my-agent",
"type": "agent_reference",
}
},
)
```
```csharp C# theme={null}
ProjectResponsesClient responsesClient =
projectClient.OpenAI
.GetProjectResponsesClientForAgent(
"my-agent");
var result = responsesClient.CreateResponse(
"Hi, Agent! Draw a graph for a line "
+ "with a slope of 4 and "
+ "y-intercept of 9.");
```
```javascript JavaScript theme={null}
const conversationId =
"conv_11112222AAAABBBB";
const response =
await openAIClient.responses.create({
input:
"Hi, Agent! Draw a graph for a "
+ "line with a slope of 4 and "
+ "y-intercept of 9.",
conversation: conversationId,
agent_reference: {
name: "my-agent",
type: "agent_reference",
},
});
```
```java Java theme={null}
AgentReference agentRef = new AgentReference("my-agent");
Response result = responsesClient.createAzureResponse(
new AzureCreateResponseOptions()
.setAgentReference(agentRef),
ResponseCreateParams.builder()
.input("Hi, Agent! Draw a graph for a line "
+ "with a slope of 4 and "
+ "y-intercept of 9."));
```
### Responses
**Previous - runs**
```json theme={null}
{
"id": "run_xyz",
"object": "thread.run",
"created_at": 1762218810,
"assistant_id": "asst_efgh5678",
"thread_id": "thread_abcd1234",
"status": "completed",
"started_at": 1762218810,
"expires_at": null,
"cancelled_at": null,
"failed_at": null,
"completed_at": 1762218812,
"required_action": null,
"last_error": null,
"model": "gpt-4.1",
"instructions": "You politely help with math questions. Use the Code Interpreter tool when asked to visualize numbers. Please address the user as Jane Doe. The user has a premium account",
"tools": [
{
"type": "code_interpreter"
}
],
"tool_resources": {},
"metadata": {},
"temperature": 1.0,
"top_p": 1.0,
"max_completion_tokens": null,
"max_prompt_tokens": null,
"truncation_strategy": {
"type": "auto",
"last_messages": null
},
"incomplete_details": null,
"usage": {
"prompt_tokens": 1216,
"completion_tokens": 76,
"total_tokens": 1292,
"prompt_token_details": {
"cached_tokens": 0
}
},
"response_format": "auto",
"tool_choice": "auto",
"parallel_tool_calls": true
}
```
**Current - responses**
````json theme={null}
{
"id": "resp_3483e9c8dda4f165006909550333588190afc76a645a0e877a",
"created_at": 1762219267.0,
"error": null,
"incomplete_details": null,
"instructions": null,
"metadata": {
"x-ms-telemetry-agent-kind": "",
"x-ms-telemetry-user-agent": "OpenAI/Python 2.4.0",
"x-ms-telemetry-response-start-time": "2025-11-04T01:21:06.5346780+00:00"
},
"model": "gpt-4.1",
"object": "response",
"output": [
{
"id": "msg_3483e9c8dda4f1650069095503abf881909917865574cddf2c",
"content": [
{
"annotations": [],
"text": "Of course! Here's a simple plot for the line with a rate of change of 4 and a y-intercept of 9.\\n\\nThe equation of the line is:\\n\\n\\\\[ y = 4x + 9 \\\\]\\n\\nLet's draw a graph for it:\\n\\n---\\n\\n```plaintext\\n |\\n20| *\\n | *\\n | *\\n | *\\n10| *\\n | *\\n | *\\n |*\\n +---------------------------\\n -2 -1 0 1 2 3\\n```\\n\\n**Key points:**\\n- The y-intercept is **9**, so at \\\\(x = 0\\\\), \\\\(y = 9\\\\) (point: (0,9))\\n- For each step right (increase in x), y goes up 4 units (rate of change \\\\(m = 4\\\\))\\n - For \\\\(x = 1\\\\): \\\\(y = 4(1) + 9 = 13\\\\) (point: (1,13))\\n - For \\\\(x = -1\\\\): \\\\(y = 4(-1) + 9 = 5\\\\) (point: (-1,5))\\n\\nIf you'd like a precise graph or want to visualize it interactively, let me know!",
"type": "output_text",
"logprobs": []
}
],
"role": "assistant",
"status": "completed",
"type": "message"
}
],
"parallel_tool_calls": true,
"temperature": 1.0,
"tool_choice": "auto",
"tools": [],
"top_p": 1.0,
"background": false,
"conversation": {
"id": "conv_3483e9c8dda4f16500GwcAgtdWlSmbMPzYLjWvDjiSe6LSFcC6"
},
"max_output_tokens": null,
"max_tool_calls": null,
"previous_response_id": null,
"prompt": null,
"prompt_cache_key": null,
"reasoning": {
"effort": null,
"generate_summary": null,
"summary": null
},
"safety_identifier": null,
"service_tier": "default",
"status": "completed",
"text": {
"format": {
"type": "text"
},
"verbosity": "medium"
},
"top_logprobs": 0,
"truncation": "disabled",
"usage": {
"input_tokens": 45,
"input_tokens_details": {
"cached_tokens": 0
},
"output_tokens": 264,
"output_tokens_details": {
"reasoning_tokens": 0
},
"total_tokens": 309
},
"user": null,
"content_filters": null,
"store": true
}
````
## Migrate classic agents to new agents
If you use the `client.agents.create_agent()` method from earlier SDK versions, migrate to `client.agents.create_version()`. The new method introduces structured agent definitions with explicit `kind`, `model`, and `instructions` fields.
### Requests
**Previous**
```python Python theme={null}
agent = client.agents.create_agent(
model="gpt-4.1",
name="my-agent", # Name of the agent
instructions="You politely help with math questions. Use the Code Interpreter tool when asked to visualize numbers.", # Instructions for the agent
tools=code_interpreter.definitions, # Attach the tool
)
```
```csharp C# theme={null}
Agent agent =
await agentsClient.CreateAgentAsync(
model: "gpt-4.1",
name: "my-agent",
instructions:
"You politely help with "
+ "math questions. Use the "
+ "Code Interpreter tool "
+ "when asked to visualize "
+ "numbers.",
tools: new List
{
new CodeInterpreterToolDefinition()
});
```
```javascript JavaScript theme={null}
const agent =
await client.agents.createAgent(
"gpt-4.1",
{
name: "my-agent",
instructions:
"You politely help with "
+ "math questions. Use "
+ "the Code Interpreter "
+ "tool when asked to "
+ "visualize numbers.",
tools: [
{ type: "code_interpreter" },
],
}
);
```
```java Java theme={null}
Agent agent =
agentsClient.createAgent("gpt-4.1",
new CreateAgentOptions()
.setName("my-agent")
.setInstructions(
"You politely help with "
+ "math questions. Use the "
+ "Code Interpreter tool "
+ "when asked to visualize "
+ "numbers.")
.setTools(Arrays.asList(
new CodeInterpreterToolDefinition())));
```
**Current**
```python Python theme={null}
from azure.ai.projects.models import (
CodeInterpreterTool,
PromptAgentDefinition,
)
agent = project.agents.create_version(
agent_name="my-agent",
definition=PromptAgentDefinition(
model="gpt-4.1",
instructions=(
"You politely help with math "
"questions. Use the Code "
"Interpreter tool when asked to "
"visualize numbers."
),
tools=[CodeInterpreterTool()],
),
)
```
```csharp C# theme={null}
var agent = await projectClient.Agents
.CreateAgentVersionAsync(
agentName: "my-agent",
options: new(
new DeclarativeAgentDefinition("gpt-4.1")
{
Instructions =
"You politely help with math "
+ "questions. Use the Code "
+ "Interpreter tool when asked "
+ "to visualize numbers.",
Tools =
{
new CodeInterpreterToolDefinition()
},
}));
```
```javascript JavaScript theme={null}
const agent =
await projectClient.AgentAdministrationClient.createVersion(
"my-agent",
{
kind: "prompt",
model: "gpt-4.1",
instructions:
"You politely help with math "
+ "questions. Use the Code "
+ "Interpreter tool when asked "
+ "to visualize numbers.",
tools: [
{ type: "code_interpreter" },
],
}
);
```
```java Java theme={null}
import com.azure.ai.agents.models.PromptAgentDefinition;
import com.azure.ai.agents.models.CodeInterpreterTool;
PromptAgentDefinition definition =
new PromptAgentDefinition("gpt-4.1");
definition.setInstructions(
"You politely help with math questions. "
+ "Use the Code Interpreter tool when "
+ "asked to visualize numbers.");
definition.setTools(Arrays.asList(
new CodeInterpreterTool()));
var agent = agentsClient.createAgentVersion(
"my-agent", definition);
```
### Responses
The following JSON examples compare the response objects returned by the previous and current agent creation methods.
**Previous**
```python theme={null}
{
'id': 'asst_AVKrdr2KJthDnZiJ51nca1jy',
'object': 'assistant',
'created_at': 1762218496,
'name': 'my-agent',
'description': None,
'model': 'gpt-4.1',
'instructions': 'You politely help with math questions. Use the Code Interpreter tool when asked to visualize numbers.',
'tools': [
{
'type': 'code_interpreter'
}
],
'top_p': 1.0,
'temperature': 1.0,
'tool_resources': {
'code_interpreter': {
'file_ids': [
]
}
},
'metadata': {
},
'response_format': 'auto'
}
```
**Current**
```json theme={null}
{
"metadata": {},
"object": "agent.version",
"id": "code-agent:1",
"name": "code-agent",
"version": "1",
"description": "Agent with code interpreter",
"created_at": 1772045947,
"definition": {
"kind": "prompt",
"model": "gpt-4.1",
"instructions": "You politely help with math questions. Use the Code Interpreter tool when asked to visualize numbers.",
"tools": [
{
"type": "code_interpreter"
}
]
}
}
```
## Migrate assistants to new agents
If your code uses the OpenAI Assistants API (`client.beta.assistants.create()`), migrate to the Foundry Agent Service by using `client.agents.create_version()`. The following examples show the structural differences.
**Previous - assistants**
```python Python theme={null}
assistant = client.beta.assistants.create(
model="gpt-4.1",
name="my-assistant",
instructions="You politely help with math questions. Use the Code Interpreter tool when asked to visualize numbers.", # Instructions for the agent
tools=[{"type": "code_interpreter"}],
)
```
```csharp C# theme={null}
// Using the OpenAI Assistants API
AzureOpenAIClient azureClient = new(
new Uri(Environment.GetEnvironmentVariable(
"AZURE_OPENAI_ENDPOINT")!),
new DefaultAzureCredential());
AssistantClient assistantClient =
azureClient.GetAssistantClient();
Assistant assistant =
await assistantClient
.CreateAssistantAsync(
"gpt-4.1",
new AssistantCreationOptions
{
Name = "my-assistant",
Instructions =
"You politely help "
+ "with math questions. "
+ "Use the Code "
+ "Interpreter tool "
+ "when asked to "
+ "visualize numbers.",
Tools =
{
new CodeInterpreterToolDefinition()
},
});
```
```javascript JavaScript theme={null}
// Using the OpenAI Assistants API
const assistant =
await client.beta.assistants.create({
model: "gpt-4.1",
name: "my-assistant",
instructions:
"You politely help with math "
+ "questions. Use the Code "
+ "Interpreter tool when "
+ "asked to visualize numbers.",
tools: [{ type: "code_interpreter" }],
});
```
```java Java theme={null}
// Using the OpenAI Assistants API
AssistantCreationOptions options =
new AssistantCreationOptions("gpt-4.1")
.setName("my-assistant")
.setInstructions(
"You politely help with math "
+ "questions. Use the Code "
+ "Interpreter tool when "
+ "asked to visualize numbers.")
.setTools(Arrays.asList(
new CodeInterpreterToolDefinition()));
Assistant assistant =
agentsClient.createAssistant(options);
```
**Current - new agents**
```python Python theme={null}
from azure.ai.projects.models import (
CodeInterpreterTool,
PromptAgentDefinition,
)
agent = project.agents.create_version(
agent_name="my-agent",
definition=PromptAgentDefinition(
model="gpt-4.1",
instructions=(
"You politely help with math "
"questions. Use the Code "
"Interpreter tool when asked to "
"visualize numbers."
),
tools=[CodeInterpreterTool()],
),
)
```
```csharp C# theme={null}
var agent = await projectClient.Agents
.CreateAgentVersionAsync(
agentName: "my-agent",
options: new(
new DeclarativeAgentDefinition("gpt-4.1")
{
Instructions =
"You politely help with math "
+ "questions. Use the Code "
+ "Interpreter tool when asked "
+ "to visualize numbers.",
Tools =
{
new CodeInterpreterToolDefinition()
},
}));
```
```javascript JavaScript theme={null}
const agent =
await projectClient.AgentAdministrationClient.createVersion(
"my-agent",
{
kind: "prompt",
model: "gpt-4.1",
instructions:
"You politely help with math "
+ "questions. Use the Code "
+ "Interpreter tool when asked "
+ "to visualize numbers.",
tools: [
{ type: "code_interpreter" },
],
}
);
```
```java Java theme={null}
import com.azure.ai.agents.models.PromptAgentDefinition;
import com.azure.ai.agents.models.CodeInterpreterTool;
PromptAgentDefinition definition =
new PromptAgentDefinition("gpt-4.1");
definition.setInstructions(
"You politely help with math questions. "
+ "Use the Code Interpreter tool when "
+ "asked to visualize numbers.");
definition.setTools(Arrays.asList(
new CodeInterpreterTool()));
var agent = agentsClient.createAgentVersion(
"my-agent", definition);
```
## Run the migration tool
A [migration tool](https://aka.ms/agent/migrate/tool) is available on GitHub to help automate the migration of your agents and assistants. The tool migrates code constructs such as agent definitions, thread creation, message creation, and run creation. It doesn't migrate state data like past runs, threads, or messages. After migration, you can run the new code, and any new state data is created in the updated format.
The following example shows a complete before-and-after comparison. Notice that the current code uses both `project` for agent creation and `openai` for conversations and responses.
**Previous**
```python Python theme={null}
agent = project_client.agents.create_agent(
model="gpt-4.1",
name="my-agent",
instructions="You politely help with math questions. Use the Code Interpreter tool when asked to visualize numbers.", # Instructions for the agent
tools=[{"type": "code_interpreter"}]
)
thread = project_client.agents.threads.create()
message = project_client.agents.messages.create(
thread_id=thread.id,
role="user", # Role of the message sender
content="Hi, Agent! Draw a graph for a line with a rate of change of 4 and y-intercept of 9.", # Message content
)
run = project_client.agents.runs.create_and_process(
thread_id=thread.id,
agent_id=agent.id,
additional_instructions="Please address the user as Jane Doe. The user has a premium account",
)
messages = project_client.agents.messages.list(thread_id=thread.id)
for message in messages:
print(f"Role: {message.role}, Content: {message.content}")
```
```csharp C# theme={null}
// Create agent
Agent agent =
await agentsClient.CreateAgentAsync(
model: "gpt-4.1",
name: "my-agent",
instructions:
"You politely help with "
+ "math questions. Use the "
+ "Code Interpreter tool "
+ "when asked to visualize "
+ "numbers.",
tools: new List
{
new CodeInterpreterToolDefinition()
});
// Create thread
AgentThread thread =
await agentsClient.CreateThreadAsync();
// Create message
await agentsClient.CreateMessageAsync(
thread.Id,
MessageRole.User,
"Hi, Agent! Draw a graph for a "
+ "line with a rate of change "
+ "of 4 and y-intercept of 9.");
// Create run and poll
ThreadRun run =
await agentsClient.CreateRunAsync(
thread.Id,
agent.Id,
additionalInstructions:
"Please address the user as "
+ "Jane Doe. The user has a "
+ "premium account");
while (run.Status ==
RunStatus.Queued
|| run.Status ==
RunStatus.InProgress)
{
await Task.Delay(1000);
run = await agentsClient.GetRunAsync(
thread.Id,
run.Id);
}
// Get messages
var messages = agentsClient.GetMessages(
thread.Id);
foreach (var msg in messages)
{
Console.WriteLine(
$"Role: {msg.Role}, "
+ $"Content: {msg.Content}");
}
```
```javascript JavaScript theme={null}
// Create agent
const agent =
await client.agents.createAgent(
"gpt-4.1",
{
name: "my-agent",
instructions:
"You politely help with "
+ "math questions. Use "
+ "the Code Interpreter "
+ "tool when asked to "
+ "visualize numbers.",
tools: [
{ type: "code_interpreter" },
],
}
);
// Create thread
const thread =
await client.agents.createThread();
// Create message
await client.agents.createMessage(
thread.id,
{
role: "user",
content:
"Hi, Agent! Draw a graph "
+ "for a line with a rate "
+ "of change of 4 and "
+ "y-intercept of 9.",
}
);
// Create run and poll
let run = await client.agents.createRun(
thread.id,
agent.id,
{
additionalInstructions:
"Please address the user as "
+ "Jane Doe. The user has a "
+ "premium account",
});
while (run.status === "queued"
|| run.status === "in_progress") {
await new Promise(
(r) => setTimeout(r, 1000));
run = await client.agents.getRun(
thread.id, run.id);
}
// Get messages
const messages =
await client.agents.listMessages(
thread.id);
for (const msg of messages.data) {
console.log(
`Role: ${msg.role}, `
+ `Content: ${msg.content}`);
}
```
```java Java theme={null}
// Create agent
Agent agent =
agentsClient.createAgent("gpt-4.1",
new CreateAgentOptions()
.setName("my-agent")
.setInstructions(
"You politely help with "
+ "math questions. Use the "
+ "Code Interpreter tool "
+ "when asked to visualize "
+ "numbers.")
.setTools(Arrays.asList(
new CodeInterpreterToolDefinition())));
// Create thread
AgentThread thread =
agentsClient.createThread();
// Create message
agentsClient.createMessage(
thread.getId(),
new CreateMessageOptions(
MessageRole.USER,
"Hi, Agent! Draw a graph for "
+ "a line with a rate of change "
+ "of 4 and y-intercept of 9."));
// Create run and poll
ThreadRun run =
agentsClient.createRun(
thread.getId(),
agent.getId(),
new CreateRunOptions()
.setAdditionalInstructions(
"Please address the user "
+ "as Jane Doe. The user "
+ "has a premium account"));
while (RunStatus.QUEUED
.equals(run.getStatus())
|| RunStatus.IN_PROGRESS
.equals(run.getStatus())) {
Thread.sleep(1000);
run = agentsClient.getRun(
thread.getId(),
run.getId());
}
// Get messages
PageableList messages =
agentsClient.listMessages(
thread.getId());
for (ThreadMessage msg : messages) {
System.out.printf(
"Role: %s, Content: %s%n",
msg.getRole(),
msg.getContent());
}
```
**Current**
```python Python theme={null}
from azure.ai.projects.models import (
CodeInterpreterTool,
PromptAgentDefinition,
)
# Create the agent
agent = project.agents.create_version(
agent_name="my-agent",
definition=PromptAgentDefinition(
model="gpt-4.1",
instructions=(
"You politely help with math "
"questions. Use the Code "
"Interpreter tool when asked "
"to visualize numbers."
),
tools=[CodeInterpreterTool()],
),
)
# Create a conversation with initial message
conversation = openai.conversations.create(
items=[
{
"type": "message",
"role": "user",
"content": (
"Hi, Agent! Draw a graph "
"for a line with a rate "
"of change of 4 and "
"y-intercept of 9."
),
}
],
)
# Send a response with the agent
response = openai.responses.create(
conversation=conversation.id,
extra_body={
"agent_reference": {
"name": agent.name,
"type": "agent_reference",
}
},
input=(
"Please address the user as "
"Jane Doe. The user has a "
"premium account"
),
)
# Print the response output
for item in response.output:
if item.type == "message":
for block in item.content:
print(block.text)
```
```csharp C# theme={null}
var agent = await projectClient.Agents
.CreateAgentVersionAsync(
agentName: "my-agent",
options: new(
new DeclarativeAgentDefinition("gpt-4.1")
{
Instructions =
"You politely help with math "
+ "questions. Use the Code "
+ "Interpreter tool when asked "
+ "to visualize numbers.",
Tools =
{
new CodeInterpreterToolDefinition()
},
}));
ProjectResponsesClient responsesClient =
projectClient.OpenAI
.GetProjectResponsesClientForAgent(
"my-agent");
var result = responsesClient.CreateResponse(
"Hi, Agent! Draw a graph for a line "
+ "with a rate of change of 4 and "
+ "y-intercept of 9. Please address the "
+ "user as Jane Doe. The user has a "
+ "premium account");
// Print the response output
foreach (var item in result.OutputItems)
{
if (item is ResponseMessageItem msg)
{
foreach (var block in msg.Content)
{
Console.WriteLine(block.Text);
}
}
}
```
```javascript JavaScript theme={null}
const agent =
await projectClient.AgentAdministrationClient.createVersion(
"my-agent",
{
kind: "prompt",
model: "gpt-4.1",
instructions:
"You politely help with math "
+ "questions. Use the Code "
+ "Interpreter tool when asked "
+ "to visualize numbers.",
tools: [
{ type: "code_interpreter" },
],
}
);
const openAIClient =
await projectClient.getOpenAIClient();
const conversation =
await openAIClient.conversations.create({
items: [
{
type: "message",
role: "user",
content:
"Hi, Agent! Draw a graph "
+ "for a line with a rate "
+ "of change of 4 and "
+ "y-intercept of 9.",
},
],
});
const response =
await openAIClient.responses.create({
input:
"Please address the user as "
+ "Jane Doe. The user has a "
+ "premium account",
conversation: conversation.id,
agent_reference: {
name: agent.name,
type: "agent_reference",
},
});
// Print the response output
for (const item of response.output) {
if (item.type === "message") {
for (const block of item.content) {
console.log(block.text);
}
}
}
```
```java Java theme={null}
import com.azure.ai.agents.models.PromptAgentDefinition;
import com.azure.ai.agents.models.CodeInterpreterTool;
PromptAgentDefinition definition =
new PromptAgentDefinition("gpt-4.1");
definition.setInstructions(
"You politely help with math questions. "
+ "Use the Code Interpreter tool when "
+ "asked to visualize numbers.");
definition.setTools(Arrays.asList(
new CodeInterpreterTool()));
var agent = agentsClient.createAgentVersion(
"my-agent", definition);
ResponsesClient responsesClient =
new AgentsClientBuilder()
.credential(
new DefaultAzureCredentialBuilder()
.build())
.endpoint(System.getenv(
"PROJECT_ENDPOINT"))
.buildResponsesClient();
AgentReference agentRef = new AgentReference("my-agent");
Response result = responsesClient.createAzureResponse(
new AzureCreateResponseOptions()
.setAgentReference(agentRef),
ResponseCreateParams.builder()
.input("Hi, Agent! Draw a graph for a line "
+ "with a rate of change of 4 and "
+ "y-intercept of 9. Please address "
+ "the user as Jane Doe. The user "
+ "has a premium account"));
// Print the response output
for (ResponseItem item : result.getOutput()) {
if (item instanceof ResponseMessageItem) {
ResponseMessageItem msg =
(ResponseMessageItem) item;
for (ContentBlock block
: msg.getContent()) {
System.out.println(
block.getText());
}
}
}
```
## Verify your migration
After you migrate your code, confirm that everything works correctly:
1. **Run the updated code** and verify that it executes without errors.
2. **Check agent creation** by confirming that `create_version()` returns an object with an `id` and `version` field.
3. **Test a conversation** by creating a conversation, sending a response, and verifying that output items are returned.
4. **Confirm context retention** by sending multiple responses to the same conversation and checking that the agent remembers earlier messages.
## Troubleshoot common issues
| Symptom | Cause | Resolution |
| -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Python**: `AttributeError: 'AIProjectClient' has no attribute 'conversations'` | You called `conversations.create()` on the project client instead of the OpenAI client. | Use `project.get_openai_client()` to obtain the OpenAI client, then call `openai.conversations.create()`. |
| **C#**: `Azure.AI.Extensions.OpenAI` namespace not found | The `Azure.AI.Extensions.OpenAI` NuGet package is missing. | Install `Azure.AI.Projects` (which brings in `Azure.AI.Extensions.OpenAI` and `Azure.AI.Projects.Agents` as dependencies). |
| **JavaScript**: `getOpenAIClient is not a function` | You're using an older version of `@azure/ai-projects`. | Update to `@azure/ai-projects@2.3.0` or later: `npm install @azure/ai-projects`. |
| **Java**: `AgentsClientBuilder` can't resolve | The `azure-ai-agents` Maven dependency is missing or outdated. | Add `com.azure:azure-ai-agents:2.2.0` to your `pom.xml` dependencies. |
| `create_agent()` is removed | Earlier SDK versions used `create_agent()`, which was removed in v2.0.0. | Replace with `create_version()` (Python/JS) or `CreateAgentVersionAsync()` (C#) or `createAgentVersion()` (Java) and pass a `PromptAgentDefinition` object. |
| Old thread data isn't available | The migration tool doesn't migrate state data (past runs, threads, or messages). | Start new conversations after migration. Historical data remains accessible through the previous API until it's deprecated. |
| `responses.create()` raises a model error | The model name might be incorrect or unavailable in your region. | Verify the model name in your Foundry project and check [model region availability](/agents/limits-quotas-regions). |
## Related content
* [Agent runtime components](/agents/runtime-components)
* [Quickstart: Create a Hosted agent](/agents/quickstart-hosted-agent)
* [Deploy a Hosted agent](/agents/deploy-hosted-agent)