Dalam panduan cepat ini, Anda akan memulai penggunaan model dan agen di Foundry.
Anda akan:
- Membuat respons dari model
- Membuat agen dengan perintah yang ditentukan
- Mengadakan percakapan bergiliran dengan agen
Prasyarat
- Model yang diterapkan di Microsoft Foundry. Jika Anda tidak memiliki model, selesaikan Quickstart: Siapkan sumber daya Microsoft Foundry terlebih dahulu.
- Runtime bahasa yang diperlukan, alat global, dan ekstensi Visual Studio Code seperti yang dijelaskan dalam Menyiapkan lingkungan pengembangan Anda.
Mengatur variabel lingkungan dan mendapatkan kode
Simpan titik akhir proyek Anda sebagai variabel lingkungan. Atur juga nilai-nilai ini untuk digunakan dalam skrip Anda.
- Python and JavaScript
PROJECT_ENDPOINT=<endpoint copied from welcome screen>
AGENT_NAME="MyAgent"
- C# and Java
ProjectEndpoint = <endpoint copied from welcome screen>
AgentName = "MyAgent"
Ikuti di bawah ini atau dapatkan kode:
Masuk menggunakan perintah CLI az login untuk mengautentikasi sebelum menjalankan skrip Python Anda.
Ikuti di bawah ini atau dapatkan kode:
Masuk menggunakan perintah CLI untuk mengautentikasi sebelum menjalankan skrip C# Anda.
Ikuti di bawah ini atau dapatkan kode:
Masuk menggunakan perintah CLI untuk mengautentikasi sebelum menjalankan skrip TypeScript Anda.
Ikuti di bawah ini atau dapatkan kode:
Masuk menggunakan perintah CLI az login untuk mengautentikasi sebelum menjalankan skrip Java Anda.
Ikuti di bawah ini atau dapatkan kode:
Masuk menggunakan perintah CLI untuk mengautentikasi sebelum menjalankan perintah berikutnya.
Dapatkan token akses sementara. Ini akan kedaluwarsa dalam 60-90 menit, Anda perlu menyegarkannya setelah itu.
az account get-access-token --scope https://ai.azure.com/.default
Simpan hasilnya sebagai variabel lingkungan .
Tidak ada kode yang diperlukan saat menggunakan portal Foundry.
Menginstal dan mengautentikasi
Pastikan Anda menginstal versi paket yang benar seperti yang ditunjukkan di sini.
Instal versi saat ini dari . Versi ini menggunakan API proyek Foundry (baru).
pip install azure-ai-projects>=2.0.0
Masuk menggunakan perintah CLI az login untuk mengautentikasi sebelum menjalankan skrip Python Anda.
Instal paket:
Tambahkan paket NuGet menggunakan .NET CLI di terminal terintegrasi: Paket ini menggunakan API proyek Foundry (baru).
dotnet add package Azure.AI.Projects --prerelease
dotnet add package Azure.AI.Projects.OpenAI --prerelease
dotnet add package Azure.Identity
Masuk menggunakan perintah CLI untuk mengautentikasi sebelum menjalankan skrip C# Anda.
Instal versi saat ini dari . Versi ini menggunakan API proyek Foundry (baru).
npm install @azure/ai-projects
Masuk menggunakan perintah CLI untuk mengautentikasi sebelum menjalankan skrip TypeScript Anda.
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-ai-agents</artifactId>
<version>2.0.0-beta.2</version>
</dependency>
- Masuk menggunakan perintah CLI
az login untuk mengautentikasi sebelum menjalankan skrip Java Anda.
Masuk menggunakan perintah CLI untuk mengautentikasi sebelum menjalankan perintah berikutnya.
Dapatkan token akses sementara. Ini akan kedaluwarsa dalam 60-90 menit, Anda perlu menyegarkannya setelah itu.
az account get-access-token --scope https://ai.azure.com/.default
Simpan hasilnya sebagai variabel lingkungan .
Tidak ada penginstalan yang diperlukan untuk menggunakan portal Foundry.
Petunjuk / Saran
Kode menggunakan Azure Proyek AI 2.x dan tidak kompatibel dengan Proyek AI Azure 1.x.
Lihat dokumentasi Foundry (klasik) untuk versi Azure AI Projects 1.x.
Mengobrol dengan model
Berinteraksi dengan model adalah blok penyusun dasar aplikasi AI. Kirim input dan terima respons dari model:
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
# Format: "https://resource_name.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"
# Create project and openai clients to call Foundry API
project = AIProjectClient(
endpoint=PROJECT_ENDPOINT,
credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()
# Run a responses API call
response = openai.responses.create(
model="gpt-5-mini", # supports all Foundry direct models
input="What is the size of France in square miles?",
)
print(f"Response output: {response.output_text}")
using Azure.Identity;
using Azure.AI.Projects;
using Azure.AI.Projects.OpenAI;
using OpenAI.Responses;
#pragma warning disable OPENAI001
// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
var ProjectEndpoint = "your_project_endpoint";
// Create project client to call Foundry API
AIProjectClient projectClient = new(
endpoint: new Uri(ProjectEndpoint),
tokenProvider: new DefaultAzureCredential());
// Run a responses API call
ProjectResponsesClient responseClient = projectClient.OpenAI.GetProjectResponsesClientForModel("gpt-5-mini"); // supports all Foundry direct models
ResponseResult response = await responseClient.CreateResponseAsync(
"What is the size of France in square miles?");
Console.WriteLine(response.GetOutputText());
import { DefaultAzureCredential } from "@azure/identity";
import { AIProjectClient } from "@azure/ai-projects";
// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
const PROJECT_ENDPOINT = "your_project_endpoint";
async function main(): Promise<void> {
// Create project and openai clients to call Foundry API
const project = new AIProjectClient(PROJECT_ENDPOINT, new DefaultAzureCredential());
const openai = await project.getOpenAIClient();
// Run a responses API call
const response = await openai.responses.create({
model: "gpt-5-mini", // supports all Foundry direct models
input: "What is the size of France in square miles?",
});
console.log(`Response output: ${response.output_text}`);
}
main().catch(console.error);
package com.azure.ai.agents;
import com.azure.ai.agents.models.AgentDetails;
import com.azure.ai.agents.models.AgentReference;
import com.azure.ai.agents.models.AgentVersionDetails;
import com.azure.ai.agents.models.PromptAgentDefinition;
import com.azure.identity.AuthenticationUtil;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.openai.azure.AzureOpenAIServiceVersion;
import com.openai.azure.AzureUrlPathMode;
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.credential.BearerTokenCredential;
import com.openai.models.conversations.Conversation;
import com.openai.models.conversations.items.ItemCreateParams;
import com.openai.models.responses.EasyInputMessage;
import com.openai.models.responses.Response;
import com.openai.models.responses.ResponseCreateParams;
public class ChatWithAgent {
public static void main(String[] args) {
// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
String ProjectEndpoint = "your_project_endpoint";
String AgentName = "your_agent_name";
AgentsClient agentsClient = new AgentsClientBuilder()
.credential(new DefaultAzureCredentialBuilder().build())
.endpoint(ProjectEndpoint)
.buildAgentsClient();
AgentDetails agent = agentsClient.getAgent(AgentName);
Conversation conversation = conversationsClient.getConversationService().create();
conversationsClient.getConversationService().items().create(
ItemCreateParams.builder()
.conversationId(conversation.id())
.addItem(EasyInputMessage.builder()
.role(EasyInputMessage.Role.SYSTEM)
.content("You are a helpful assistant that speaks like a pirate.")
.build()
).addItem(EasyInputMessage.builder()
.role(EasyInputMessage.Role.USER)
.content("Hello, agent!")
.build()
).build()
);
AgentReference agentReference = new AgentReference(agent.getName()).setVersion(agent.getVersion());
Response response = responsesClient.createWithAgentConversation(agentReference, conversation.id());
OpenAIClient client = OpenAIOkHttpClient.builder()
.baseUrl(ProjectEndpoint.endsWith("/") ? ProjectEndpoint + "openai" : ProjectEndpoint + "/openai")
.azureUrlPathMode(AzureUrlPathMode.UNIFIED)
.credential(BearerTokenCredential.create(AuthenticationUtil.getBearerTokenSupplier(
new DefaultAzureCredentialBuilder().build(), "https://ai.azure.com/.default")))
.azureServiceVersion(AzureOpenAIServiceVersion.fromString("2025-11-15-preview"))
.build();
ResponseCreateParams responseRequest = new ResponseCreateParams.Builder()
.input("Hello, how can you help me?")
.model("gpt-5-mini") //supports all Foundry direct models
.build();
Response result = client.responses().create(responseRequest);
}
}
Ganti dengan nilai Anda:
curl -X POST https://YOUR-FOUNDRY-RESOURCE-NAME.services.ai.azure.com/api/projects/YOUR-PROJECT-NAME/openai/responses?api-version=2025-11-15-preview \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $AZURE_AI_AUTH_TOKEN" \
-d '{
"model": "gpt-4.1-mini",
"input": "What is the size of France in square miles?"
}'
Setelah model disebarkan, Anda secara otomatis dipindahkan dari Beranda ke bagian Build . Model baru Anda dipilih dan siap untuk Anda coba.
Mulailah mengobrol dengan model Anda, misalnya, "Tuliskan saya puisi tentang bunga."
Setelah menjalankan kode, Anda akan melihat respons yang dihasilkan model di konsol (misalnya, puisi singkat atau jawaban atas perintah Anda). Ini mengonfirmasi titik akhir proyek, autentikasi, dan penyebaran model Anda berfungsi dengan benar.
Petunjuk / Saran
Kode menggunakan Azure Proyek AI 2.x dan tidak kompatibel dengan Proyek AI Azure 1.x.
Lihat dokumentasi Foundry (klasik) untuk versi Azure AI Projects 1.x.
Membuat agen
Buat agen menggunakan model yang Anda sebarkan.
Agen mendefinisikan perilaku inti. Setelah dibuat, ini memastikan respons yang konsisten dalam interaksi pengguna tanpa mengulangi instruksi setiap kali. Anda dapat memperbarui atau menghapus agen kapan saja.
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition
# Format: "https://resource_name.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"
AGENT_NAME = "your_agent_name"
# Create project client to call Foundry API
project = AIProjectClient(
endpoint=PROJECT_ENDPOINT,
credential=DefaultAzureCredential(),
)
# Create an agent with a model and instructions
agent = project.agents.create_version(
agent_name=AGENT_NAME,
definition=PromptAgentDefinition(
model="gpt-5-mini", # supports all Foundry direct models"
instructions="You are a helpful assistant that answers general questions",
),
)
print(f"Agent created (id: {agent.id}, name: {agent.name}, version: {agent.version})")
using Azure.Identity;
using Azure.AI.Projects;
using Azure.AI.Projects.OpenAI;
// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
var ProjectEndpoint = "your_project_endpoint";
var AgentName = "your_agent_name";
// Create project client to call Foundry API
AIProjectClient projectClient = new(
endpoint: new Uri(ProjectEndpoint),
tokenProvider: new DefaultAzureCredential());
// Create an agent with a model and instructions
AgentDefinition agentDefinition = new PromptAgentDefinition("gpt-5-mini") // supports all Foundry direct models
{
Instructions = "You are a helpful assistant that answers general questions",
};
AgentVersion agent = projectClient.Agents.CreateAgentVersion(
AgentName,
options: new(agentDefinition));
Console.WriteLine($"Agent created (id: {agent.Id}, name: {agent.Name}, version: {agent.Version})");
import { DefaultAzureCredential } from "@azure/identity";
import { AIProjectClient } from "@azure/ai-projects";
// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
const PROJECT_ENDPOINT = "your_project_endpoint";
const AGENT_NAME = "your_agent_name";
async function main(): Promise<void> {
// Create project client to call Foundry API
const project = new AIProjectClient(PROJECT_ENDPOINT, new DefaultAzureCredential());
// Create an agent with a model and instructions
const agent = await project.agents.createVersion(AGENT_NAME, {
kind: "prompt",
model: "gpt-5-mini", //supports all Foundry direct models
instructions: "You are a helpful assistant that answers general questions",
});
console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);
}
main().catch(console.error);
package com.azure.ai.agents;
import com.azure.ai.agents.models.AgentVersionDetails;
import com.azure.ai.agents.models.PromptAgentDefinition;
import com.azure.identity.DefaultAzureCredentialBuilder;
public class CreateAgent {
public static void main(String[] args) {
// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
String ProjectEndpoint = "your_project_endpoint";
String AgentName = "your_agent_name";
// Create agents client to call Foundry API
AgentsClient agentsClient = new AgentsClientBuilder()
.credential(new DefaultAzureCredentialBuilder().build())
.endpoint(ProjectEndpoint)
.buildAgentsClient();
// Create an agent with a model and instructions
PromptAgentDefinition request = new PromptAgentDefinition("gpt-5-mini") // supports all Foundry direct models
.setInstructions("You are a helpful assistant that answers general questions");
AgentVersionDetails agent = agentsClient.createAgentVersion(AgentName, request);
System.out.println("Agent ID: " + agent.getId());
System.out.println("Agent Name: " + agent.getName());
System.out.println("Agent Version: " + agent.getVersion());
}
}
Ganti dengan nilai Anda:
curl -X POST https://YOUR-FOUNDRY-RESOURCE-NAME.services.ai.azure.com/api/projects/YOUR-PROJECT-NAME/agents?api-version=2025-11-15-preview \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $AZURE_AI_AUTH_TOKEN" \
-d '{
"name": "MyAgent",
"definition": {
"kind": "prompt",
"model": "gpt-4.1-mini",
"instructions": "You are a helpful assistant that answers general questions"
}
}'
Sekarang buat agen dan berinteraksi dengannya.
- Masih di bagian Build , pilih Agen di panel kiri.
- Pilih Buat agen dan beri nama.
Output mengonfirmasi bahwa agen telah dibuat. Untuk tab SDK, Anda akan melihat nama agen dan ID yang dicetak ke konsol.
Petunjuk / Saran
Kode menggunakan Azure Proyek AI 2.x dan tidak kompatibel dengan Proyek AI Azure 1.x.
Lihat dokumentasi Foundry (klasik) untuk versi Azure AI Projects 1.x.
Mengobrol dengan agen
Gunakan agen yang dibuat sebelumnya bernama "MyAgent" untuk berinteraksi dengan mengajukan pertanyaan dan tindak lanjut terkait. Percakapan menyimpan riwayat dari semua interaksi ini.
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
# Format: "https://resource_name.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"
AGENT_NAME = "your_agent_name"
# Create project and openai clients to call Foundry API
project = AIProjectClient(
endpoint=FOUNDRY_PROJECT_ENDPOINT,
credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()
# Create a conversation for multi-turn chat
conversation = openai.conversations.create()
# Chat with the agent to answer questions
response = openai.responses.create(
conversation=conversation.id,
extra_body={"agent_reference": {"name": FOUNDRY_AGENT_NAME, "type": "agent_reference"}},
input="What is the size of France in square miles?",
)
print(response.output_text)
# Ask a follow-up question in the same conversation
response = openai.responses.create(
conversation=conversation.id,
extra_body={"agent_reference": {"name": FOUNDRY_AGENT_NAME, "type": "agent_reference"}},
input="And what is the capital city?",
)
print(response.output_text)
using Azure.Identity;
using Azure.AI.Projects;
using Azure.AI.Projects.OpenAI;
using OpenAI.Responses;
#pragma warning disable OPENAI001
// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
var ProjectEndpoint = "your_project_endpoint";
var AgentName = "your_agent_name";
// Create project client to call Foundry API
AIProjectClient projectClient = new(
endpoint: new Uri(ProjectEndpoint),
tokenProvider: new DefaultAzureCredential());
// Create a conversation for multi-turn chat
ProjectConversation conversation = projectClient.OpenAI.Conversations.CreateProjectConversation();
// Chat with the agent to answer questions
ProjectResponsesClient responsesClient = projectClient.OpenAI.GetProjectResponsesClientForAgent(
defaultAgent: AgentName,
defaultConversationId: conversation.Id);
ResponseResult response = responsesClient.CreateResponse("What is the size of France in square miles?");
Console.WriteLine(response.GetOutputText());
// Ask a follow-up question in the same conversation
response = responsesClient.CreateResponse("And what is the capital city?");
Console.WriteLine(response.GetOutputText());
import { DefaultAzureCredential } from "@azure/identity";
import { AIProjectClient } from "@azure/ai-projects";
// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
const PROJECT_ENDPOINT = "your_project_endpoint";
const AGENT_NAME = "your_agent_name";
async function main(): Promise<void> {
// Create project and openai clients to call Foundry API
const project = new AIProjectClient(PROJECT_ENDPOINT, new DefaultAzureCredential());
const openai = await project.getOpenAIClient();
// Create a conversation for multi-turn chat
const conversation = await openai.conversations.create();
// Chat with the agent to answer questions
const response = await openai.responses.create(
{
conversation: conversation.id,
input: "What is the size of France in square miles?",
},
{
body: { agent: { name: AGENT_NAME, type: "agent_reference" } },
},
);
console.log(response.output_text);
// Ask a follow-up question in the same conversation
const response2 = await openai.responses.create(
{
conversation: conversation.id,
input: "And what is the capital city?",
},
{
body: { agent: { name: FOUNDRY_AGENT_NAME, type: "agent_reference" } },
},
);
console.log(response2.output_text);
}
main().catch(console.error);
package com.azure.ai.agents;
import com.azure.ai.agents.models.AgentDetails;
import com.azure.ai.agents.models.AgentReference;
import com.azure.ai.agents.models.AgentVersionDetails;
import com.azure.ai.agents.models.PromptAgentDefinition;
import com.azure.identity.AuthenticationUtil;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.openai.azure.AzureOpenAIServiceVersion;
import com.openai.azure.AzureUrlPathMode;
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.credential.BearerTokenCredential;
import com.openai.models.conversations.Conversation;
import com.openai.models.conversations.items.ItemCreateParams;
import com.openai.models.responses.EasyInputMessage;
import com.openai.models.responses.Response;
import com.openai.models.responses.ResponseCreateParams;
public class ChatWithAgent {
public static void main(String[] args) {
// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
String ProjectEndpoint = "your_project_endpoint";
String AgentName = "your_agent_name";
AgentsClient agentsClient = new AgentsClientBuilder()
.credential(new DefaultAzureCredentialBuilder().build())
.endpoint(ProjectEndpoint)
.buildAgentsClient();
AgentDetails agent = agentsClient.getAgent(AgentName);
Conversation conversation = conversationsClient.getConversationService().create();
conversationsClient.getConversationService().items().create(
ItemCreateParams.builder()
.conversationId(conversation.id())
.addItem(EasyInputMessage.builder()
.role(EasyInputMessage.Role.SYSTEM)
.content("You are a helpful assistant that speaks like a pirate.")
.build()
).addItem(EasyInputMessage.builder()
.role(EasyInputMessage.Role.USER)
.content("Hello, agent!")
.build()
).build()
);
AgentReference agentReference = new AgentReference(agent.getName()).setVersion(agent.getVersion());
Response response = responsesClient.createWithAgentConversation(agentReference, conversation.id());
OpenAIClient client = OpenAIOkHttpClient.builder()
.baseUrl(ProjectEndpoint.endsWith("/") ? ProjectEndpoint + "openai" : ProjectEndpoint + "/openai")
.azureUrlPathMode(AzureUrlPathMode.UNIFIED)
.credential(BearerTokenCredential.create(AuthenticationUtil.getBearerTokenSupplier(
new DefaultAzureCredentialBuilder().build(), "https://ai.azure.com/.default")))
.azureServiceVersion(AzureOpenAIServiceVersion.fromString("2025-11-15-preview"))
.build();
ResponseCreateParams responseRequest = new ResponseCreateParams.Builder()
.input("Hello, how can you help me?")
.model("gpt-5-mini") //supports all Foundry direct models
.build();
Response result = client.responses().create(responseRequest);
}
}
Ganti dengan nilai Anda:
# Optional Step: Create a conversation to use with the agent
curl -X POST https://YOUR-FOUNDRY-RESOURCE-NAME.services.ai.azure.com/api/projects/YOUR-PROJECT-NAME/openai/conversations?api-version=2025-11-15-preview \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $AZURE_AI_AUTH_TOKEN" \
-d '{}'
# Lets say Conversation ID created is conv_123456789. Use this in the next step
#Chat with the agent to answer questions
curl -X POST https://YOUR-FOUNDRY-RESOURCE-NAME.services.ai.azure.com/api/projects/YOUR-PROJECT-NAME/openai/responses?api-version=2025-11-15-preview \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $AZURE_AI_AUTH_TOKEN" \
-d '{
"agent": {"type": "agent_reference", "name": "MyAgent"},
"conversation" : "<YOUR_CONVERSATION_ID>",
"input" : "What is the size of France in square miles?"
}'
#Optional Step: Ask a follow-up question in the same conversation
curl -X POST https://YOUR-FOUNDRY-RESOURCE-NAME.services.ai.azure.com/api/projects/YOUR-PROJECT-NAME/openai/responses?api-version=2025-11-15-preview \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $AZURE_AI_AUTH_TOKEN" \
-d '{
"agent": {"type": "agent_reference", "name": "MyAgent"},
"conversation" : "<YOUR_CONVERSATION_ID>",
"input" : "And what is the capital city?"
}'
Berinteraksi dengan agen Anda.
- Tambahkan instruksi, seperti, "Anda adalah asisten penulisan yang bermanfaat."
- Mulailah mengobrol dengan agen Anda, misalnya, "Tulis puisi tentang matahari."
- Menindaklanjuti dengan "Bagaimana dengan haiku?"
Anda melihat respons agen terhadap kedua perintah. Respons tindak lanjut menunjukkan bahwa agen mempertahankan riwayat percakapan secara bergiliran.
Petunjuk / Saran
Kode menggunakan Azure Proyek AI 2.x dan tidak kompatibel dengan Proyek AI Azure 1.x.
Lihat dokumentasi Foundry (klasik) untuk versi Azure AI Projects 1.x.
Membersihkan sumber daya
Jika Anda tidak lagi memerlukan sumber daya yang Anda buat, hapus grup sumber daya yang terkait dengan proyek Anda.
- Di portal Azure, pilih grup sumber daya, lalu pilih Delete. Konfirmasikan bahwa Anda ingin menghapus grup sumber daya.
Langkah selanjutnya
Ide untuk prototipe - Membangun serta mengevaluasi agen bisnis