Dalam panduan kilat ini, Anda akan mulai menggunakan model dan agen di Foundry.
Anda akan:
- Membuat respons dari model
- Membuat agen dengan perintah yang ditentukan
- Melakukan percakapan multi-giliran dengan agen
Prasyarat
Model yang disebarkan di Microsoft Foundry. Jika Anda tidak memiliki model, pertama-tama selesaikan Quickstart: Siapkan sumber daya Microsoft Foundry.
Tips
Atau, lewati langkah penyebaran dan coba model instan (pratinjau) sebagai gantinya. Buat proyek di West US 3 untuk menggunakan model dengan akses instan. Model instan tidak memiliki penyebaran, jadi gunakan nama gpt-5-mini model di mana pun sampel meminta nama penyebaran.
Runtime bahasa yang diperlukan, alat global, dan ekstensi Visual Studio Code seperti yang dijelaskan dalam Siapkan lingkungan pengembangan Anda.
Dapatkan kode dan tetapkan nilai Anda
Sampel Python tidak membaca variabel lingkungan. Di setiap file, ganti nilai placeholder berikut:
-
your_project_endpoint: Titik akhir proyek Anda, dalam format https://<resource-name>.services.ai.azure.com/api/projects/<project-name>.
-
your_agent_name: Nama untuk agen Anda, seperti MyAgent.
Contoh menggunakan gpt-5-mini deployment yang Anda buat dalam Menyiapkan sumber daya Microsoft Foundry. Jika Anda menyebarkan model dengan nama yang berbeda, perbarui nama model dalam kode sampel.
Ikuti di bawah ini atau dapatkan kode:
Sampel C# tidak membaca variabel lingkungan. Di setiap file, ganti nilai pengganti sementara berikut:
-
your_project_endpoint: Titik akhir proyek Anda, dalam format https://<resource-name>.services.ai.azure.com/api/projects/<project-name>.
-
your_agent_name: Nama untuk agen Anda, seperti MyAgent.
Contoh menggunakan gpt-5-mini deployment yang Anda buat dalam Menyiapkan sumber daya Microsoft Foundry. Jika Anda menyebarkan model dengan nama yang berbeda, perbarui nama model dalam kode sampel.
Ikuti di bawah ini atau dapatkan kode:
Sampel TypeScript tidak membaca variabel lingkungan. Di setiap file, ganti nilai-nilai ini dengan titik akhir proyek Anda dan nama agen seperti MyAgent:
const FOUNDRY_PROJECT_ENDPOINT = "https://<resource-name>.services.ai.azure.com/api/projects/<project-name>";
const FOUNDRY_AGENT_NAME = "MyAgent";
Contoh menggunakan gpt-5-mini deployment yang Anda buat dalam Menyiapkan sumber daya Microsoft Foundry. Jika Anda menyebarkan model dengan nama yang berbeda, perbarui nama model dalam kode sampel.
Ikuti di bawah ini atau dapatkan kode:
Sampel Java tidak membaca variabel lingkungan. Di setiap file, ganti nilai-nilai ini dengan titik akhir proyek Anda dan nama agen seperti MyAgent:
String foundryProjectEndpoint = "https://<resource-name>.services.ai.azure.com/api/projects/<project-name>";
String foundryAgentName = "MyAgent";
Contoh menggunakan gpt-5-mini deployment yang Anda buat dalam Menyiapkan sumber daya Microsoft Foundry. Jika Anda menyebarkan model dengan nama yang berbeda, perbarui nama model dalam kode sampel.
Ikuti di bawah ini atau dapatkan kode:
Di setiap URL permintaan, ganti YOUR-FOUNDRY-RESOURCE-NAME dan YOUR-PROJECT-NAME dengan nilai dari titik akhir proyek Anda, yang memiliki formulir https://<resource-name>.services.ai.azure.com/api/projects/<project-name>.
Permintaan chat-with-agent membaca nama agen dari variabel lingkungan:
FOUNDRY_AGENT_NAME=MyAgent
Contoh menggunakan gpt-5-mini deployment yang Anda buat dalam Menyiapkan sumber daya Microsoft Foundry. Jika Anda menerapkan model dengan nama yang berbeda, perbarui nilai model dalam badan permintaan.
Ikuti di bawah ini atau dapatkan kode:
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 azure-ai-projects. Versi ini menggunakan API proyek Foundry (baru). Sampel mengautentikasi dengan menggunakan DefaultAzureCredential, yang berasal dari azure-identity.
pip install "azure-ai-projects>=2.3.0" azure-identity
Masuk menggunakan perintah CLI az login untuk mengautentikasi sebelum menjalankan skrip Python Anda.
Pasang paket:
Tambahkan paket NuGet menggunakan .NET CLI di terminal terintegrasi: Paket ini menggunakan API proyek Foundry (baru).
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
Masuk menggunakan perintah CLI az login untuk mengautentikasi sebelum menjalankan skrip C# Anda.
Instal versi saat ini dari @azure/ai-projects. Versi ini menggunakan API proyek Foundry (baru).
npm install @azure/ai-projects @azure/identity
Masuk menggunakan perintah CLI az login untuk mengautentikasi sebelum menjalankan skrip TypeScript Anda.
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-ai-agents</artifactId>
<version>2.2.0</version>
</dependency>
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-core</artifactId>
<version>1.57.0</version>
</dependency>
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-identity</artifactId>
<version>1.18.1</version>
</dependency>
- Masuk menggunakan perintah CLI
az login untuk mengautentikasi sebelum menjalankan skrip Java Anda.
Masuk menggunakan perintah CLI az login untuk mengautentikasi sebelum menjalankan perintah berikutnya.
Dapatkan token akses sementara. Ini akan kedaluwarsa dalam 60-90 menit, Anda harus menyegarkan setelah itu.
az account get-access-token --scope https://ai.azure.com/.default
Simpan hasilnya sebagai variabel AZURE_AI_AUTH_TOKENlingkungan .
Tidak ada penginstalan yang diperlukan untuk menggunakan portal Foundry.
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.services.ai.azure.com/api/projects/project_name"
FOUNDRY_PROJECT_ENDPOINT = "your_project_endpoint"
# Create project and openai clients to call Foundry API
project = AIProjectClient(
endpoint=FOUNDRY_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?",
)
if not response.output_text or not response.output_text.strip():
raise RuntimeError("Response output text was empty.")
print(f"Response output: {response.output_text}")
using Azure.Identity;
using Azure.AI.Projects;
using Azure.AI.Extensions.OpenAI;
using OpenAI.Responses;
#pragma warning disable OPENAI001
// Format: "https://resource_name.services.ai.azure.com/api/projects/project_name"
var foundryProjectEndpoint = "your_project_endpoint";
// Create project client to call Foundry API
AIProjectClient projectClient = new(
endpoint: new Uri(foundryProjectEndpoint),
tokenProvider: new DefaultAzureCredential());
// Run a responses API call
ProjectResponsesClient responseClient = projectClient.ProjectOpenAIClient.GetProjectResponsesClientForModel(
"gpt-5-mini"); // supports all Foundry direct models
ResponseResult response = await responseClient.CreateResponseAsync(
"What is the size of France in square miles?");
string outputText = response.GetOutputText();
if (string.IsNullOrWhiteSpace(outputText))
{
throw new InvalidOperationException("Response output text was empty.");
}
Console.WriteLine(outputText);
import { DefaultAzureCredential } from "@azure/identity";
import { AIProjectClient } from "@azure/ai-projects";
// Format: "https://resource_name.services.ai.azure.com/api/projects/project_name"
const FOUNDRY_PROJECT_ENDPOINT = "your_project_endpoint";
async function main(): Promise<void> {
// Create project and openai clients to call Foundry API
const project = new AIProjectClient(FOUNDRY_PROJECT_ENDPOINT, new DefaultAzureCredential());
const openai = project.getOpenAIClient();
// Run a responses API call
const response = await openai.responses.create({
model: "gpt-5-mini",
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.identity.DefaultAzureCredentialBuilder;
import com.openai.models.responses.Response;
import com.openai.models.responses.ResponseCreateParams;
public class CreateResponse {
public static void main(String[] args) {
// Format: "https://resource_name.services.ai.azure.com/api/projects/project_name"
String foundryProjectEndpoint = "your_project_endpoint";
// Create responses client to call Foundry API
ResponsesClient responsesClient = new AgentsClientBuilder()
.credential(new DefaultAzureCredentialBuilder().build())
.endpoint(foundryProjectEndpoint)
.buildResponsesClient();
// Run a responses API call
ResponseCreateParams responseRequest = new ResponseCreateParams.Builder()
.input("What is the size of France in square miles?")
.model("gpt-5-mini")
.build();
Response response = responsesClient.getResponseService().create(responseRequest);
System.out.println(response.output());
}
}
Ganti YOUR-FOUNDRY-RESOURCE-NAME dengan nilai Anda:
curl -X POST https://YOUR-FOUNDRY-RESOURCE-NAME.services.ai.azure.com/api/projects/YOUR-PROJECT-NAME/openai/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $AZURE_AI_AUTH_TOKEN" \
-d '{
"model": "gpt-5-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.
Tips
Jika Anda tidak melakukan deployment, pilih Test in playground dari halaman utama. Pilih model akses instan yang ingin Anda gunakan, seperti gpt-5-mini. (Selama pratinjau, model akses instan ini hanya tersedia untuk proyek di US3 Barat.)
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.
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.services.ai.azure.com/api/projects/project_name"
FOUNDRY_PROJECT_ENDPOINT = "your_project_endpoint"
FOUNDRY_AGENT_NAME = "your-agent-name"
# Create project client to call Foundry API
project = AIProjectClient(
endpoint=FOUNDRY_PROJECT_ENDPOINT,
credential=DefaultAzureCredential(),
)
# Create an agent with a model and instructions
agent = project.agents.create_version(
agent_name=FOUNDRY_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.Agents;
using Azure.AI.Extensions.OpenAI;
// Format: "https://resource_name.services.ai.azure.com/api/projects/project_name"
var foundryProjectEndpoint = "your_project_endpoint";
var foundryAgentName = "your_agent_name";
// Create project client to call Foundry API
AIProjectClient projectClient = new(
endpoint: new Uri(foundryProjectEndpoint),
tokenProvider: new DefaultAzureCredential());
// Create an agent with a model and instructions
ProjectsAgentDefinition agentDefinition = new DeclarativeAgentDefinition("gpt-5-mini") // supports all Foundry direct models
{
Instructions = "You are a helpful assistant that answers general questions",
};
ProjectsAgentVersion agent = projectClient.AgentAdministrationClient.CreateAgentVersion(
foundryAgentName,
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.services.ai.azure.com/api/projects/project_name"
const FOUNDRY_PROJECT_ENDPOINT = "your_project_endpoint";
const FOUNDRY_AGENT_NAME = "your_agent_name";
async function main(): Promise<void> {
// Create project client to call Foundry API
const project = new AIProjectClient(FOUNDRY_PROJECT_ENDPOINT, new DefaultAzureCredential());
// Create an agent with a model and instructions
const agent = await project.agents.createVersion(FOUNDRY_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.services.ai.azure.com/api/projects/project_name"
String foundryProjectEndpoint = "your_project_endpoint";
String foundryAgentName = "your_agent_name";
// Create agents client to call Foundry API
AgentsClient agentsClient = new AgentsClientBuilder()
.credential(new DefaultAzureCredentialBuilder().build())
.endpoint(foundryProjectEndpoint)
.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(foundryAgentName, request);
System.out.println("Agent ID: " + agent.getId());
System.out.println("Agent Name: " + agent.getName());
System.out.println("Agent Version: " + agent.getVersion());
}
}
Ganti YOUR-FOUNDRY-RESOURCE-NAME dengan nilai Anda:
curl -X POST https://YOUR-FOUNDRY-RESOURCE-NAME.services.ai.azure.com/api/projects/YOUR-PROJECT-NAME/agents?api-version=v1 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $AZURE_AI_AUTH_TOKEN" \
-d '{
"name": "MyAgent",
"definition": {
"kind": "prompt",
"model": "gpt-5-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, seperti "MyAgent".
Output mengonfirmasi bahwa agen berhasil dibuat. Untuk tab SDK, Anda akan melihat nama agen dan ID yang dicetak ke konsol.
Mengobrol dengan agen
Gunakan agen yang dibuat sebelumnya bernama "MyAgent" untuk berinteraksi dengan mengajukan pertanyaan dan tindak lanjut terkait. Percakapan mempertahankan riwayat selama interaksi ini.
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
# Format: "https://resource_name.services.ai.azure.com/api/projects/project_name"
FOUNDRY_PROJECT_ENDPOINT = "your_project_endpoint"
FOUNDRY_AGENT_NAME = "your_agent_name"
# Create project and openai clients to call Foundry API
project = AIProjectClient(
endpoint=FOUNDRY_PROJECT_ENDPOINT,
credential=DefaultAzureCredential(),
)
# Get an OpenAI client pre-bound to the specified agent
openai = project.get_openai_client(agent_name=FOUNDRY_AGENT_NAME)
# 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,
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,
input="And what is the capital city?",
)
print(response.output_text)
using Azure.Identity;
using Azure.AI.Projects;
using Azure.AI.Extensions.OpenAI;
using OpenAI.Responses;
#pragma warning disable OPENAI001
// Format: "https://resource_name.services.ai.azure.com/api/projects/project_name"
var foundryProjectEndpoint = "your_project_endpoint";
var foundryAgentName = "your_agent_name";
// Create project client to call Foundry API
AIProjectClient projectClient = new(
endpoint: new Uri(foundryProjectEndpoint),
tokenProvider: new DefaultAzureCredential());
// Create a conversation for multi-turn chat
ProjectConversation conversation = projectClient.ProjectOpenAIClient.GetProjectConversationsClient().CreateProjectConversation();
// Chat with the agent to answer questions
ProjectResponsesClient responsesClient = projectClient.ProjectOpenAIClient.GetProjectResponsesClientForAgent(
defaultAgent: foundryAgentName,
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.services.ai.azure.com/api/projects/project_name"
const FOUNDRY_PROJECT_ENDPOINT = "your_project_endpoint";
const FOUNDRY_AGENT_NAME = "your_agent_name";
async function main(): Promise<void> {
// Create project and openai clients to call Foundry API
const project = new AIProjectClient(FOUNDRY_PROJECT_ENDPOINT, new DefaultAzureCredential());
const openai = project.getOpenAIClient({
azureConfig: { allowPreview: true, agentName: FOUNDRY_AGENT_NAME },
});
// 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?",
});
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?",
});
console.log(response2.output_text);
}
main().catch(console.error);
package com.azure.ai.agents;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.openai.client.OpenAIClient;
import com.openai.models.conversations.Conversation;
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.services.ai.azure.com/api/projects/project_name"
String foundryProjectEndpoint = "your_project_endpoint";
String foundryAgentName = "your_agent_name";
AgentsClientBuilder builder = new AgentsClientBuilder()
.credential(new DefaultAzureCredentialBuilder().build())
.endpoint(foundryProjectEndpoint);
// Create an OpenAI client bound to the agent endpoint
OpenAIClient openai = builder.buildAgentScopedOpenAIClient(foundryAgentName);
// Create a conversation for multi-turn chat
Conversation conversation = openai.conversations().create();
// Chat with the agent to answer questions
Response response = openai.responses().create(
ResponseCreateParams.builder()
.conversation(conversation.id())
.input("What is the size of France in square miles?")
.build());
printResponse(response);
// Ask a follow-up question in the same conversation
Response followUp = openai.responses().create(
ResponseCreateParams.builder()
.conversation(conversation.id())
.input("And what is the capital city?")
.build());
printResponse(followUp);
}
private static void printResponse(Response response) {
response.output().forEach(item -> item.message().ifPresent(message ->
message.content().forEach(content -> content.outputText().ifPresent(
text -> System.out.println(text.text())))));
}
}
Ganti YOUR-FOUNDRY-RESOURCE-NAME dengan nilai Anda:
# Generate a response using the agent
curl -X POST "https://YOUR-FOUNDRY-RESOURCE-NAME.services.ai.azure.com/api/projects/YOUR-PROJECT-NAME/agents/${FOUNDRY_AGENT_NAME}/endpoint/protocols/openai/responses?api-version=v1" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $AZURE_AI_AUTH_TOKEN" \
-d '{
"input": [{"role": "user", "content": "What is the size of France in square miles?"}]
}'
# 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/agents/${FOUNDRY_AGENT_NAME}/endpoint/protocols/openai/conversations?api-version=v1" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $AZURE_AI_AUTH_TOKEN" \
-d '{
"items": [
{
"type": "message",
"role": "user",
"content": [
{
"type": "input_text",
"text": "What is the size of France in square miles?"
}
]
}
]
}'
# Lets say Conversation ID created is conv_123456789. Use this in the next step
#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/agents/${FOUNDRY_AGENT_NAME}/endpoint/protocols/openai/responses?api-version=v1" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $AZURE_AI_AUTH_TOKEN" \
-d '{
"conversation": "<CONVERSATION_ID>",
"input": [{"role": "user", "content": "And what is the capital?"}]
}'
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.
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 berikutnya