V tomto rychlém průvodci začnete používat modely a agenty v Foundry.
Budete:
- Vygenerování odpovědi z modelu
- Vytvoření agenta s definovanou výzvou
- Vést víceetapovou konverzaci s agentem
Požadavky
Model nasazený v Microsoft Foundry Pokud model nemáte, nejprve dokončete Quickstart: Nastavení prostředků Microsoft Foundry.
Tip
Nebo přeskočte krok nasazení a zkuste místo toho okamžitý model (Preview). Vytvořte projekt v oblasti USA – západ 3 pro použití modelů okamžitého přístupu. Okamžité modely nemají žádné nasazení, proto použijte název gpt-5-mini modelu všude, kde ukázky požádají o název nasazení.
Požadované jazykové runtime, globální nástroje a rozšíření Visual Studio Code, jak je popsáno v Připravení vývojového prostředí.
Získání kódu a nastavení hodnot
Ukázky Python nečtou proměnné prostředí. V každém souboru nahraďte tyto zástupné hodnoty:
-
your_project_endpoint: Koncový bod projektu ve formátu https://<resource-name>.services.ai.azure.com/api/projects/<project-name>.
-
your_agent_name: Název vašeho agenta, například MyAgent.
Ukázky používají nasazení gpt-5-mini, které jste vytvořili v části Nastavení prostředků Microsoft Foundry. Pokud jste model nasadili pod jiným názvem, aktualizujte název modelu v ukázkovém kódu.
Postupujte podle následujících pokynů nebo získejte kód:
Ukázky jazyka C# nečtou proměnné prostředí. V každém souboru nahraďte tyto zástupné hodnoty:
-
your_project_endpoint: Koncový bod projektu ve formátu https://<resource-name>.services.ai.azure.com/api/projects/<project-name>.
-
your_agent_name: Název vašeho agenta, například MyAgent.
Ukázky používají nasazení gpt-5-mini, které jste vytvořili v části Nastavení prostředků Microsoft Foundry. Pokud jste model nasadili pod jiným názvem, aktualizujte název modelu v ukázkovém kódu.
Postupujte podle následujících pokynů nebo získejte kód:
Ukázky TypeScriptu nečtou proměnné prostředí. V každém souboru nahraďte tyto hodnoty koncovým bodem projektu a názvem agenta, například MyAgent:
const FOUNDRY_PROJECT_ENDPOINT = "https://<resource-name>.services.ai.azure.com/api/projects/<project-name>";
const FOUNDRY_AGENT_NAME = "MyAgent";
Ukázky používají nasazení gpt-5-mini, které jste vytvořili v části Nastavení prostředků Microsoft Foundry. Pokud jste model nasadili pod jiným názvem, aktualizujte název modelu v ukázkovém kódu.
Postupujte podle následujících pokynů nebo získejte kód:
Ukázky v Javě nečtou proměnné prostředí. V každém souboru nahraďte tyto hodnoty koncovým bodem projektu a názvem agenta, například MyAgent:
String foundryProjectEndpoint = "https://<resource-name>.services.ai.azure.com/api/projects/<project-name>";
String foundryAgentName = "MyAgent";
Ukázky používají nasazení gpt-5-mini, které jste vytvořili v části Nastavení prostředků Microsoft Foundry. Pokud jste model nasadili pod jiným názvem, aktualizujte název modelu v ukázkovém kódu.
Postupujte podle následujících pokynů nebo získejte kód:
V každé adrese URL požadavku nahraďte YOUR-FOUNDRY-RESOURCE-NAME a YOUR-PROJECT-NAMEnahraďte hodnotami z koncového bodu projektu, který má formulář https://<resource-name>.services.ai.azure.com/api/projects/<project-name>.
Požadavek chatu s agentem přečte název agenta z proměnné prostředí:
FOUNDRY_AGENT_NAME=MyAgent
Ukázky používají nasazení gpt-5-mini, které jste vytvořili v části Nastavení prostředků Microsoft Foundry. Pokud jste model nasadili pod jiným názvem, aktualizujte model hodnotu v textu požadavku.
Postupujte podle následujících pokynů nebo získejte kód:
Při použití portálu Foundry není nutný žádný kód.
Instalace a ověření
Ujistěte se, že jste nainstalovali správnou verzi balíčků, jak je znázorněno zde.
Nainstalujte aktuální verzi souboru azure-ai-projects. Tato verze používá API Foundry projects (new). Ukázky se ověřují pomocí DefaultAzureCredential, který pochází z azure-identity.
pip install "azure-ai-projects>=2.3.0" azure-identity
Před spuštěním skriptů Python se přihlaste pomocí příkazu CLI az login.
Instalační balíčky:
Přidejte balíčky NuGet pomocí rozhraní příkazového řádku .NET v integrovaném terminálu: Tyto balíčky používají rozhraní API projektů Foundry (nové).
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
Přihlaste se pomocí příkazu rozhraní příkazového řádku az login k ověření před spuštěním skriptů jazyka C#.
Nainstalujte aktuální verzi souboru @azure/ai-projects. Tato verze používá rozhraní API pro projekty Foundry (nové).
npm install @azure/ai-projects @azure/identity
Před spuštěním skriptů TypeScript se přihlaste pomocí příkazu rozhraní příkazového řádku az login k ověření.
<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>
- Před spuštěním skriptů Java se přihlaste pomocí příkazu CLI
az login.
Před spuštěním dalšího příkazu se přihlaste pomocí příkazu rozhraní příkazového řádku az login .
Získejte dočasný přístupový token. Platnost vyprší za 60 až 90 minut, budete po ní muset provést aktualizaci.
az account get-access-token --scope https://ai.azure.com/.default
Uložte výsledky jako proměnnou AZURE_AI_AUTH_TOKENprostředí .
K používání portálu Foundry není nutná žádná instalace.
Chatování s modelem
Interakce s modelem je základní stavební blok aplikací AI. Odeslání vstupu a přijetí odpovědi z modelu:
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());
}
}
Nahraďte YOUR-FOUNDRY-RESOURCE-NAME hodnotami:
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?"
}'
Po nasazení modelu se automaticky přesunete z domovské stránky do části Sestavení . Váš nový model je vybraný a připravený k vyzkoušení.
Tip
Pokud jste nasazení vynechali, na domovské stránce vyberte Test v dětském prostředí . Vyberte model okamžitého přístupu, který chcete použít, například gpt-5-mini. (Ve verzi Preview jsou tyto modely okamžitého přístupu dostupné jenom pro projekty v oblasti USA – západ 3.)
Začněte chatovat s vaším modelem, například "Napište mi báseň o květinách".
Po spuštění kódu se v konzole zobrazí odpověď vygenerovaná modelem (například krátká báseň nebo odpověď na vaši výzvu). Tím potvrdíte, že koncový bod projektu, ověřování a nasazení modelu fungují správně.
Vytvoření agenta
Vytvořte agenta pomocí nasazeného modelu.
Agent definuje základní chování. Po vytvoření zajišťuje konzistentní odpovědi v interakcích uživatelů bez opakování pokynů pokaždé. Agenty můžete kdykoli aktualizovat nebo odstranit.
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());
}
}
Nahraďte YOUR-FOUNDRY-RESOURCE-NAME hodnotami:
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"
}
}'
Teď vytvořte agenta a interagujte s ním.
- V části Sestavení v levém podokně vyberte Agenti.
- Vyberte Vytvořit agenta a pojmenujte ho, například MyAgent.
Výstup potvrzuje, že agent byl vytvořen. Na kartách SDK se zobrazí název a ID agenta vytištěné do konzoly.
Chat s agentem
Pomocí dříve vytvořeného agenta s názvem MyAgent můžete interagovat tak, že položíte otázku a související následnou akci. Konverzace udržuje historii napříč těmito interakcemi.
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())))));
}
}
Nahraďte YOUR-FOUNDRY-RESOURCE-NAME hodnotami:
# 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?"}]
}'
Interakce s vaším agentem
- Přidejte pokyny, například "Jste užitečný pomocník pro psaní".
- Začněte chatovat s vaším agentem, například "Napsat báseň o slunci".
- Sledujte "Jak to s haiku?"
Zobrazí se odpovědi agenta na obě výzvy. Následná odpověď ukazuje, že agent udržuje historii konverzací napříč jednotlivými kroky.
Vyčištění prostředků
Pokud už žádné prostředky, které jste vytvořili, nepotřebujete, odstraňte skupinu prostředků přidruženou k vašemu projektu.
- Na portálu Azure vyberte skupinu prostředků a pak vyberte Delete. Potvrďte, že chcete odstranit skupinu prostředků.
Další krok