Szybki start: wprowadzenie do zestawu SDK usługi Microsoft Foundry

Przykłady Python nie odczytują zmiennych środowiskowych. W każdym pliku zastąp następujące wartości zastępcze:

• your_project_endpoint: Punkt końcowy projektu w formacie https://<resource-name>.services.ai.azure.com/api/projects/<project-name>.
• your_agent_name: nazwa agenta, na przykład MyAgent.

W przykładach użyto wdrożenia utworzonego gpt-5-mini w temacie Konfigurowanie zasobów Microsoft Foundry. Jeśli model został wdrożony pod inną nazwą, zaktualizuj nazwę modelu w przykładowym kodzie.

Postępuj zgodnie z poniższymi instrukcjami lub pobierz kod:

Przykłady języka C# nie odczytują zmiennych środowiskowych. W każdym pliku zastąp następujące wartości zastępcze:

• your_project_endpoint: Punkt końcowy projektu w formacie https://<resource-name>.services.ai.azure.com/api/projects/<project-name>.
• your_agent_name: nazwa agenta, na przykład MyAgent.

W przykładach użyto wdrożenia utworzonego gpt-5-mini w temacie Konfigurowanie zasobów Microsoft Foundry. Jeśli model został wdrożony pod inną nazwą, zaktualizuj nazwę modelu w przykładowym kodzie.

Postępuj zgodnie z poniższymi instrukcjami lub pobierz kod:

Przykłady języka TypeScript nie odczytują zmiennych środowiskowych. W każdym pliku zastąp te wartości punktem końcowym projektu i nazwą agenta, taką jak MyAgent:

const FOUNDRY_PROJECT_ENDPOINT = "https://<resource-name>.services.ai.azure.com/api/projects/<project-name>";
const FOUNDRY_AGENT_NAME = "MyAgent";

W przykładach użyto wdrożenia utworzonego gpt-5-mini w temacie Konfigurowanie zasobów Microsoft Foundry. Jeśli model został wdrożony pod inną nazwą, zaktualizuj nazwę modelu w przykładowym kodzie.

Postępuj zgodnie z poniższymi instrukcjami lub pobierz kod:

Przykłady Java nie odczytują zmiennych środowiskowych. W każdym pliku zastąp te wartości punktem końcowym projektu i nazwą agenta, taką jak MyAgent:

String foundryProjectEndpoint = "https://<resource-name>.services.ai.azure.com/api/projects/<project-name>";
String foundryAgentName = "MyAgent";

W przykładach użyto wdrożenia utworzonego gpt-5-mini w temacie Konfigurowanie zasobów Microsoft Foundry. Jeśli model został wdrożony pod inną nazwą, zaktualizuj nazwę modelu w przykładowym kodzie.

Postępuj zgodnie z poniższymi instrukcjami lub pobierz kod:

1. W każdym adresie URL żądania zastąp YOUR-FOUNDRY-RESOURCE-NAME wartościami YOUR-PROJECT-NAME z punktu końcowego projektu, które mają postać https://<resource-name>.services.ai.azure.com/api/projects/<project-name>.

2. Żądanie „chat-with-agent” odczytuje nazwę agenta ze zmiennej środowiskowej:

   FOUNDRY_AGENT_NAME=MyAgent
   

W przykładach użyto wdrożenia utworzonego gpt-5-mini w temacie Konfigurowanie zasobów Microsoft Foundry. Jeśli model został wdrożony pod inną nazwą, zaktualizuj model wartość w treści żądania.

Postępuj zgodnie z poniższymi instrukcjami lub pobierz kod:

W przypadku korzystania z portalu Foundry nie jest wymagany żaden kod.

1. Zainstaluj bieżącą wersję programu azure-ai-projects. Ta wersja korzysta z API projektów Foundry (nowe). Przykłady uwierzytelniają się przy użyciu elementu DefaultAzureCredential, który pochodzi z elementu azure-identity.

   pip install "azure-ai-projects>=2.3.0" azure-identity
   

2. Zaloguj się przy użyciu polecenia CLI az login w celu uwierzytelnienia się przed uruchomieniem skryptów Pythona.

1. Instalowanie pakietów:

   Dodaj pakiety NuGet przy użyciu .NET CLI w zintegrowanym terminalu: te pakiety korzystają z interfejsu API nowych projektów Foundry.

   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
   

2. Zaloguj się za pomocą polecenia CLI az login, aby zweryfikować tożsamość przed uruchomieniem skryptów C#.

1. Zainstaluj bieżącą wersję programu @azure/ai-projects. Ta wersja używa nowego interfejsu API projektów Foundry.

   npm install @azure/ai-projects @azure/identity
   

2. Zaloguj się przy użyciu polecenia CLI az login , aby uwierzytelnić się przed uruchomieniem skryptów TypeScript.

<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>

1. Zaloguj się przy użyciu polecenia CLI az login w celu uwierzytelnienia, zanim uruchomisz swoje skrypty Java.

1. Zaloguj się komendą CLI az login, aby uwierzytelnić się przed uruchomieniem następnego polecenia.

2. Uzyskiwanie tymczasowego tokenu dostępu. Wygaśnie on w ciągu 60–90 minut. Po tym czasie trzeba będzie odświeżyć.

   az account get-access-token --scope https://ai.azure.com/.default
   

3. Zapisz wyniki jako zmienną środowiskową AZURE_AI_AUTH_TOKEN.

Do korzystania z portalu Foundry nie jest konieczna instalacja.

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);

Zastąp YOUR-FOUNDRY-RESOURCE-NAME wartościami:

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?"
}'

1. Po wdrożeniu modelu zostaniesz automatycznie przeniesiony ze strony głównej do sekcji Budowanie. Nowy model jest wybrany i gotowy do wypróbowania.

   Wskazówka

   Jeśli pominięto wdrożenie, wybierz pozycję Testuj na placu zabaw ze strony głównej. Wybierz model natychmiastowego dostępu, którego chcesz użyć, na przykład gpt-5-mini. (W wersji zapoznawczej te modele dostępu błyskawicznego są dostępne tylko dla projektów w regionie Zachodnie stany USA 3).

2. Zacznij rozmawiać z modelem, na przykład "Napisz mi wiersz o kwiatach".

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);

Zastąp YOUR-FOUNDRY-RESOURCE-NAME wartościami:

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"
    }
  }'

Teraz utwórz agenta i wejdź z nim w interakcję.

1. W sekcji Build wybierz Agentów z okienka z lewej.
2. Wybierz pozycję Utwórz agenta i nadaj mu nazwę, taką jak "MyAgent".

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 and openai clients to call Foundry API
project = AIProjectClient(
    endpoint=FOUNDRY_PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)

# Create the agent (or a new version, if it already exists)
project.agents.create_version(
    agent_name=FOUNDRY_AGENT_NAME,
    definition=PromptAgentDefinition(
        model="gpt-5-mini",
        instructions="You are a helpful assistant that answers general questions",
    ),
)

# 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.Projects.Agents;
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 the agent (or a new version, if it already exists)
ProjectsAgentDefinition agentDefinition = new DeclarativeAgentDefinition("gpt-5-mini") // supports all Foundry direct models
{
    Instructions = "You are a helpful assistant that answers general questions",
};
projectClient.AgentAdministrationClient.CreateAgentVersion(
    foundryAgentName,
    options: new(agentDefinition));

// 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 createAgentVersion(projectEndpoint: string, agentName: string): Promise<void> {
    const credential = new DefaultAzureCredential();
    const token = await credential.getToken("https://ai.azure.com/.default");
    if (!token) {
        throw new Error("Failed to acquire a Foundry access token");
    }

    const response = await fetch(
        `${projectEndpoint.replace(/\/$/, "")}/agents/${encodeURIComponent(agentName)}/versions?api-version=v1`,
        {
            method: "POST",
            headers: {
                "Authorization": ["Bearer", token.token].join(" "),
                "Content-Type": "application/json",
            },
            body: JSON.stringify({
                definition: {
                    kind: "prompt",
                    model: "gpt-5-mini", //supports all Foundry direct models
                    instructions: "You are a helpful assistant that answers general questions",
                },
            }),
        },
    );
    if (!response.ok) {
        throw new Error(`Failed to create agent version: ${response.status} ${await response.text()}`);
    }
}

async function main(): Promise<void> {
    // Create project and openai clients to call Foundry API
    const project = new AIProjectClient(FOUNDRY_PROJECT_ENDPOINT, new DefaultAzureCredential());

    // Create the agent (or a new version, if it already exists)
    await createAgentVersion(FOUNDRY_PROJECT_ENDPOINT, FOUNDRY_AGENT_NAME);

    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((error) => {
    console.error(error);
    process.exitCode = 1;
});

Zastąp YOUR-FOUNDRY-RESOURCE-NAME wartościami:

# 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?"}]
  }'

Interakcja z agentem.

1. Dodaj instrukcje, takie jak "Jesteś pomocnym asystentem pisania".
2. Zacznij rozmawiać z agentem, na przykład "Napisz wiersz o słońcu".
3. W odpowiedzi zapytaj: "Może haiku?"