Aracılığıyla paylaş

Hızlı Başlangıç: Yeni aracı oluşturma

Note

Bu belge , Microsoft Foundry (klasik) portalını ifade eder.

🔍Yeni portal hakkında bilgi edinmek için Microsoft Foundry (yeni) belgelerini görüntüleyin.

Note

Bu hızlı başlangıç kılavuzu, ajanların önceki sürümüne yöneliktir. API'nin yeni sürümünü kullanmak için Microsoft Foundry'nin hızlı başlangıç kılavuzuna bakın.

Foundry Agent Service, özel yönergelerle ihtiyaçlarınıza göre uyarlanmış ve kod yorumlayıcı ve özel işlevler gibi gelişmiş araçlarla geliştirilmiş yapay zeka aracıları oluşturmanıza olanak tanır.

Prerequisites

  • Azure aboneliği - Ücretsiz bir abonelik oluşturun.
  • Hesabı ve projeyi oluşturan kişinin abonelik kapsamında Azure AI Hesabı Sahibi rolüne sahip olduğundan emin olun; bu rol projeyi oluşturmak için gerekli izinleri verir
    • Alternatif olarak, Abonelik düzeyinde Katkıda Bulunan veya Bilişsel Hizmetler Katkıda Bulunanı rolüne sahip olmak projenin oluşturulmasına izin verir
  • Proje oluşturulduktan sonra, proje içinde aracıyı oluşturan kişinin proje düzeyinde Azure AI Kullanıcısı rolüne sahip olduğundan emin olun

Important

Microsoft Foundry portalı şu anda yalnızca temel aracı kurulumunu destekler. Standart aracı kurulumu gerçekleştirmek istiyorsanız daha fazla bilgi edinmek için Ortam kurulumu makalesine bakın.

Dökümhane portalında bir dökümhane hesabı ve projesi oluşturun.

Foundry'de hesap ve proje oluşturmak için şu adımları izleyin:

  1. Foundry'ye gidin. Bir projedeyseniz, Giriş sayfasına gitmek için sayfanın sol üst kısmındaki Dökümhane'yi seçin.

  2. En hızlı deneyim için Başlangıç Aracı oluşturma akışını kullanın. Aracı oluştur'a tıklayın.

    Dökümhane portalının ekran görüntüsü.

  3. Proje için bir ad girin. Varsayılan değerleri özelleştirmek istiyorsanız Gelişmiş seçenekler'i seçin.

    Proje oluşturmaya yönelik gelişmiş seçeneklerin ekran görüntüsü.

  4. Oluştur'i seçin.

  5. Kaynaklarınızın sağlanmasını bekleyin.

    1. Bir hesap ve proje (hesabınızın alt kaynağı) oluşturulur.
    2. gpt-4o modeli otomatik olarak dağıtılacak
    3. Varsayılan aracı oluşturulacak

  6. İşlem tamamlandıktan sonra doğrudan ajan çalışma alanınıza ulaşırsınız ve ajan oluşturmaya başlayabilirsiniz. Temsilcinize ne yapması ve nasıl yapması gerektiği konusunda yönergeler verebilirsiniz. Örneğin: "Coğrafya hakkındaki soruları yanıtlayan yararlı bir aracısınız." Ardından temsilcinizle sohbet etmeye başlayabilirsiniz.

    Agent Playground'un ekran görüntüsü.

    Note

    Aracıları yapılandırmaya veya oluşturmaya çalışırken izin hatası alıyorsanız projede Azure AI Kullanıcısına sahip olduğunuzdan emin olun.

| Başvuru belgeleri | Örnekler | Kitaplık kaynak kodu | Paket (NuGet) |

Prerequisites

  • Aracı ortamını ayarlama
  • SDK veya Aracı Oyun Alanı'nı kullanarak aracı oluşturması veya düzenlemesi gereken her ekip üyesine Azure AI KullanıcıRBAC rolünü atayın
    • Bu rol proje kapsamında atanmalıdır
    • Gerekli en düşük izinler: aracılar/*/okuma, aracılar/*/eylem, aracılar/*/delete

Ajana yapılandır ve çalıştır

.NET Konsol projesi oluşturun.

dotnet new console

.NET paketini projenize yükleyin. Örneğin. .NET CLI kullanıyorsanız aşağıdaki komutu çalıştırın.

dotnet add package Azure.AI.Agents.Persistent
dotnet add package Azure.Identity

Ardından API isteklerinizin kimliğini doğrulamak ve programı çalıştırmak için az login komutunu kullanarak Azure aboneliğinizde oturum açın.

az login

Aracı oluşturup çalıştırmak için aşağıdaki kodu kullanın. Bu kodu çalıştırmak için projenizin uç noktasını almanız gerekir. Bu dize şu biçimdedir:

https://<AIFoundryResourceName>.services.ai.azure.com/api/projects/<ProjectName>

Important

Mayıs 2025'te başlayan Azure AI Agent Service, daha önce hub tabanlı projeler için kullanılan bağlantı dizesi yerine Foundry projeleri için bir uç nokta kullanır. Hub tabanlı bir proje kullanıyorsanız SDK ve REST API'nin geçerli sürümlerini kullanamazsınız. Daha fazla bilgi için bkz. Hub tabanlı projelerle SDK kullanımı.

Uç noktanızı projenize genel bakış kısmında, Microsoft Foundry portalında, Kitaplıklar>Foundry altında bulabilirsiniz.

Dökümhane portalında uç noktayı gösteren ekran görüntüsü.

Bu uç noktayı adlı ProjectEndpointbir ortam değişkeninde ayarlayın.

Ayrıca modelinizin dağıtım adına da ihtiyacınız vardır. Sol gezinti menüsündeki Modeller + Uç Noktalar'da bulabilirsiniz.

Dökümhane portalının model dağıtım ekranını gösteren ekran görüntüsü.

Model dağıtım adınızı adlı ModelDeploymentNamebir ortam değişkeni olarak kaydedin.

using Azure;
using Azure.AI.Agents.Persistent;
using Azure.Identity;
using System.Diagnostics;

var projectEndpoint = System.Environment.GetEnvironmentVariable("ProjectEndpoint");
var modelDeploymentName = System.Environment.GetEnvironmentVariable("ModelDeploymentName");



//Create a PersistentAgentsClient and PersistentAgent.
PersistentAgentsClient client = new(projectEndpoint, new DefaultAzureCredential());

//Give PersistentAgent a tool to execute code using CodeInterpreterToolDefinition.
PersistentAgent agent = client.Administration.CreateAgent(
    model: modelDeploymentName,
    name: "My Test Agent",
    instructions: "You politely help with math questions. Use the code interpreter tool when asked to visualize numbers.",
    tools: [new CodeInterpreterToolDefinition()]
);

//Create a thread to establish a session between Agent and a User.
PersistentAgentThread thread = client.Threads.CreateThread();

//Ask a question of the Agent.
client.Messages.CreateMessage(
    thread.Id,
    MessageRole.User,
    "Hi, Agent! Draw a graph for a line with a slope of 4 and y-intercept of 9.");

//Have Agent begin processing user's question with some additional instructions associated with the ThreadRun.
ThreadRun run = client.Runs.CreateRun(
    thread.Id,
    agent.Id,
    additionalInstructions: "Please address the user as Jane Doe. The user has a premium account.");

//Poll for completion.
do
{
    Thread.Sleep(TimeSpan.FromMilliseconds(500));
    run = client.Runs.GetRun(thread.Id, run.Id);
}
while (run.Status == RunStatus.Queued
    || run.Status == RunStatus.InProgress
    || run.Status == RunStatus.RequiresAction);

//Get the messages in the PersistentAgentThread. Includes Agent (Assistant Role) and User (User Role) messages.
Pageable<PersistentThreadMessage> messages = client.Messages.GetMessages(
    threadId: thread.Id,
    order: ListSortOrder.Ascending);

//Display each message and open the image generated using CodeInterpreterToolDefinition.
foreach (PersistentThreadMessage threadMessage in messages)
{
    foreach (MessageContent content in threadMessage.ContentItems)
    {
        switch (content)
        {
            case MessageTextContent textItem:
                Console.WriteLine($"[{threadMessage.Role}]: {textItem.Text}");
                break;
            case MessageImageFileContent imageFileContent:
                Console.WriteLine($"[{threadMessage.Role}]: Image content file ID = {imageFileContent.FileId}");
                BinaryData imageContent = client.Files.GetFileContent(imageFileContent.FileId);
                string tempFilePath = Path.Combine(AppContext.BaseDirectory, $"{Guid.NewGuid()}.png");
                File.WriteAllBytes(tempFilePath, imageContent.ToArray());
                client.Files.DeleteFile(imageFileContent.FileId);

                ProcessStartInfo psi = new()
                {
                    FileName = tempFilePath,
                    UseShellExecute = true
                };
                Process.Start(psi);
                break;
        }
    }
}

//If you want to delete your agent, uncomment the following lines:
//client.Threads.DeleteThread(threadId: thread.Id);
//client.Administration.DeleteAgent(agentId: agent.Id);

| Referans belgeleri | Örnekler | Kitaplık kaynak kodu | Paket (PyPi) |

Prerequisites

  • Aracı ortamını ayarlama
  • SDK veya Aracı Oyun Alanı'nı kullanarak aracı oluşturması veya düzenlemesi gereken her ekip üyesine Azure AI KullanıcıRBAC rolünü atayın
    • Bu rol proje kapsamında atanmalıdır
    • Gerekli en düşük izinler: aracılar/*/okuma, aracılar/*/eylem, aracılar/*/delete

Ajana yapılandır ve çalıştır

Python paketlerini yüklemek için aşağıdaki komutları çalıştırın.

pip install azure-ai-projects
pip install azure-identity

Ardından API isteklerinizin kimliğini doğrulamak ve programı çalıştırmak için az login komutunu kullanarak Azure aboneliğinizde oturum açın.

az login

Aracı oluşturup çalıştırmak için aşağıdaki kodu kullanın. Bu kodu çalıştırmak için projenizin uç noktasını almanız gerekir. Bu dize şu biçimdedir:

https://<AIFoundryResourceName>.services.ai.azure.com/api/projects/<ProjectName>

Important

Mayıs 2025'te başlayan Azure AI Agent Service, daha önce hub tabanlı projeler için kullanılan bağlantı dizesi yerine Foundry projeleri için bir uç nokta kullanır. Hub tabanlı bir proje kullanıyorsanız SDK ve REST API'nin geçerli sürümlerini kullanamazsınız. Daha fazla bilgi için bkz. Hub tabanlı projelerle SDK kullanımı.

Uç noktanızı projenize genel bakış kısmında, Microsoft Foundry portalında, Kitaplıklar>Foundry altında bulabilirsiniz.

Dökümhane portalında uç noktayı gösteren ekran görüntüsü.

Bu uç noktayı adlı PROJECT_ENDPOINTbir ortam değişkeni olarak ayarlayın.

Ayrıca modelinizin dağıtım adına da ihtiyacınız vardır. Sol gezinti menüsündeki Modeller + Uç Noktalar'da bulabilirsiniz.

Dökümhane portalının model dağıtım ekranını gösteren ekran görüntüsü.

Model dağıtım adınızı adlı MODEL_DEPLOYMENT_NAMEbir ortam değişkeni olarak kaydedin.

import os
from pathlib import Path
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
from azure.ai.agents.models import CodeInterpreterTool

# Create an AIProjectClient instance
project_client = AIProjectClient(
    endpoint=os.getenv("PROJECT_ENDPOINT"),
    credential=DefaultAzureCredential(),  
    # Use Azure Default Credential for authentication
)

with project_client:

    code_interpreter = CodeInterpreterTool()

    agent = project_client.agents.create_agent(
        model=os.getenv("MODEL_DEPLOYMENT_NAME"),  # Model deployment name
        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
        tool_resources=code_interpreter.resources,  # Attach tool resources
    )
    print(f"Created agent, ID: {agent.id}")

    # Create a thread for communication
    thread = project_client.agents.threads.create()
    print(f"Created thread, ID: {thread.id}")

    question = """Draw a graph for a line with a slope of 4 
    and y-intercept of 9 and provide the file to me?"""

    # Add a message to the thread
    message = project_client.agents.messages.create(
        thread_id=thread.id,
        role="user",  # Role of the message sender
        content=question,  # Message content
    )
    print(f"Created message, ID: {message['id']}")

    # Create and process an agent run
    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.""",
    )

    print(f"Run finished with status: {run.status}")

    # Check if the run failed
    if run.status == "failed":
        print(f"Run failed: {run.last_error}")

    # Fetch and log all messages
    messages = project_client.agents.messages.list(thread_id=thread.id)
    print(f"Messages: {messages}")

    for message in messages:
        print(f"Role: {message.role}, Content: {message.content}")
        for this_content in message.content:
            print(f"Content Type: {this_content.type}, Content Data: {this_content}")
            if this_content.text.annotations:
                for annotation in this_content.text.annotations:
                    print(f"Annotation Type: {annotation.type}, Text: {annotation.text}")
                    print(f"Start Index: {annotation.start_index}")
                    print(f"End Index: {annotation.end_index}")
                    print(f"File ID: {annotation.file_path.file_id}")
                    # Save every image file in the message
                    file_id = annotation.file_path.file_id
                    file_name = f"{file_id}_image_file.png"
                    project_client.agents.files.save(file_id=file_id, file_name=file_name)
                    print(f"Saved image file to: {Path.cwd() / file_name}")
    #Uncomment these lines to delete the agent when done
    #project_client.agents.delete_agent(agent.id)
    #print("Deleted agent")

| Başvuru belgeleri | Örnekler | Kütüphane kaynak kodu | Paket (npm) |

Prerequisites

  • Aracı ortamını ayarlama
  • SDK veya Aracı Oyun Alanı'nı kullanarak aracı oluşturması veya düzenlemesi gereken her ekip üyesine Azure AI KullanıcıRBAC rolünü atayın
    • Bu rol proje kapsamında atanmalıdır
    • Gerekli en düşük izinler: aracılar/*/okuma, aracılar/*/eylem, aracılar/*/delete

Ajana yapılandır ve çalıştır

Bu koddaki anahtar nesneler şunlardır:

İlk olarak, komutunu çalıştırarak yeni bir TypeScript projesi başlatın:

npm init -y
npm pkg set type="module"

Gerekli npm paketlerini yüklemek için aşağıdaki komutları çalıştırın.

npm install @azure/ai-agents @azure/identity
npm install @types/node typescript --save-dev

Ardından API isteklerinizin kimliğini doğrulamak ve programı çalıştırmak için az login komutunu kullanarak Azure aboneliğinizde oturum açın.

az login

Matematik sorusunu I need to solve the equation '3x + 11 = 14'. Can you help me?yanıtlamak için aşağıdaki kodu kullanın. Bu kodu çalıştırmak için projenizin uç noktasını almanız gerekir. Bu dize şu biçimdedir:

https://<AIFoundryResourceName>.services.ai.azure.com/api/projects/<ProjectName>

Uç noktanızı projenize genel bakış kısmında, Microsoft Foundry portalında, Kitaplıklar>Foundry altında bulabilirsiniz.

Dökümhane portalında uç noktayı gösteren ekran görüntüsü.

Bu uç noktayı bir dosyada adlı PROJECT_ENDPOINT bir .env ortam değişkeni olarak ayarlayın.

Ayrıca modelinizin dağıtım adına da ihtiyacınız vardır. Sol gezinti menüsündeki Modeller + Uç Noktalar'da bulabilirsiniz.

Dökümhane portalının model dağıtım ekranını gösteren ekran görüntüsü.

Model dağıtım adınızı adlı MODEL_DEPLOYMENT_NAMEbir ortam değişkeni olarak kaydedin.

Important

  • Bu hızlı başlangıç kodu, hassas yapılandırma için ortam değişkenlerini kullanır. Dosyanızda .env listelendiğinden emin olarak, .env dosyanızı hiçbir zaman sürüm denetimine işlemeyin .gitignore.
  • Unutmayın: Hassas bilgileri yanlışlıkla işlerseniz, bu kimlik bilgilerinin gizliliğinin ihlal edilmiş olduğunu göz önünde bulundurun ve bunları hemen döndürün.

Aşağıdaki içeriğe sahip bir tsconfig.json dosyası oluşturun:

{
  "compilerOptions": {
    "module": "nodenext",
    "target": "esnext",
    "types": ["node"],
    "lib": ["esnext"],
    "sourceMap": true,
    "declaration": true,
    "declarationMap": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "strict": true,
    "verbatimModuleSyntax": true,
    "isolatedModules": true,
    "noUncheckedSideEffectImports": true,
    "moduleDetection": "force",
    "skipLibCheck": true,
  }
}

Ardından bir index.ts dosya oluşturun ve aşağıdaki kodu yapıştırın:

import { AgentsClient } from "@azure/ai-agents";
import { DefaultAzureCredential } from "@azure/identity";

const projectEndpoint = process.env["PROJECT_ENDPOINT"] || "<project endpoint>";
const modelDeploymentName = process.env["MODEL_DEPLOYMENT_NAME"] || "gpt-4o";

export async function main(): Promise<void> {
  // Create an Azure AI Client
  const client = new AgentsClient(projectEndpoint, new DefaultAzureCredential());

  // Create an agent
  const agent = await client.createAgent(modelDeploymentName, {
    name: "my-agent",
    instructions: "You are a helpful agent specialized in math. When providing mathematical explanations, use plain text formatting with simple characters like +, -, *, / for operations. Do not use LaTeX formatting with backslashes or special notation. Make your explanations clear and easy to read in a terminal.",
  });
  console.log(`Created agent, agent ID : ${agent.id}`);

  // Create a thread
  const thread = await client.threads.create();
  console.log(`Created thread, thread ID : ${thread.id}`);

  // List all threads for the agent
  const threads = client.threads.list();
  console.log(`Threads for agent ${agent.id}:`);
  for await (const t of threads) {
    console.log(`Thread ID: ${t.id} created at: ${t.createdAt}`);
  }

  // Create a message
  const message = await client.messages.create(thread.id, "user", "I need to solve the equation `3x + 11 = 14`. Can you help me?");
  console.log(`Created message, message ID : ${message.id}`);

  // Create and poll a run
  console.log("Creating run...");
  const run = await client.runs.createAndPoll(thread.id, agent.id, {
    pollingOptions: {
      intervalInMs: 2000,
    },
    onResponse: (response): void => {
      const parsedBody =
        typeof response.parsedBody === "object" && response.parsedBody !== null
          ? response.parsedBody
          : null;
      const status = parsedBody && "status" in parsedBody ? parsedBody.status : "unknown";
      console.log(`Received response with status: ${status}`);
    },
  });
  console.log(`Run finished with status: ${run.status}`);

  const messagesIterator = client.messages.list(thread.id);
  console.log("\n\n========================================================");
  console.log("=================== CONVERSATION RESULTS ===================");
  console.log("========================================================\n");
  
  // Collect all messages first
  const messages = [];
  for await (const m of messagesIterator) {
    messages.push(m);
  }
  
  // Reverse the order of messages (or sort by timestamp if available)
  messages.reverse();
  
  // Display messages in the new order
  for (const m of messages) {
    if (m.role === "user") {
      console.log(`\n❓ USER QUESTION: ${
        Array.isArray(m.content) && m.content[0]?.type === "text" && 'text' in m.content[0]
          ? m.content[0].text.value
          : JSON.stringify(m.content)
      }`);
    } else if (m.role === "assistant") {
      console.log("\n🤖 ASSISTANT'S ANSWER:");
      console.log("--------------------------------------------------");
      
      // Extract and print the text content in a more readable format
      if (m.content && Array.isArray(m.content)) {
        for (const content of m.content) {
          if (content.type === "text" && 'text' in content) {
            console.log(content.text?.value);
          } else {
            console.log(content);
          }
        }
      } else {
        console.log(JSON.stringify(m.content, null, 2));
      }
      console.log("--------------------------------------------------\n");
    }
  }
  
  console.log("\n========================================================");
  console.log("====================== END OF RESULTS ======================");
  console.log("========================================================\n");

  // Clean up
  await client.threads.delete(thread.id);
  await client.deleteAgent(agent.id);
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
});

kullanarak npx tsx -r dotenv/config index.tskodu çalıştırın. Bu kod şu soruyu I need to solve the equation '3x + 11 = 14'. Can you help me?yanıtlar: . Yanıtlar belirleyici değildir; çıkışınız aşağıdaki çıkışa benzer olacaktır:

Created agent, agent ID : asst_X4yDNWrdWKb8LN0SQ6xlzhWk
Created thread, thread ID : thread_TxqZcHL2BqkNWl9dFzBYMIU6
Threads for agent asst_X4yDNWrdWKb8LN0SQ6xlzhWk:
...
Created message, message ID : msg_R0zDsXdc2UbfsNXvS1zeS6hk
Creating run...
Received response with status: queued
Received response with status: in_progress
Received response with status: completed
Run finished with status: completed


========================================================
=================== CONVERSATION RESULTS ===================
========================================================


❓ USER QUESTION: I need to solve the equation `3x + 11 = 14`. Can you help me?

🤖 ASSISTANT'S ANSWER:
--------------------------------------------------
Certainly! Let's solve the equation step by step:

We have:
3x + 11 = 14

### Step 1: Eliminate the constant (+11) on the left-hand side.
Subtract 11 from both sides:
3x + 11 - 11 = 14 - 11
This simplifies to:
3x = 3

We have:
3x + 11 = 14

### Step 1: Eliminate the constant (+11) on the left-hand side.
Subtract 11 from both sides:
3x + 11 - 11 = 14 - 11
This simplifies to:
3x = 3

### Step 2: Solve for x.
Divide both sides by 3:
3x / 3 = 3 / 3
This simplifies to:
x = 1

### Final Answer:
x = 1
--------------------------------------------------


========================================================
====================== END OF RESULTS ======================
========================================================

Tam örnek kaynak kodu kullanılabilir.

| Başvuru belgeleri | Örnekler | Kitaplık kaynak kodu | Paket (Maven) |

Prerequisites

  • Aracı ortamını ayarlama
  • SDK veya Aracı Oyun Alanı'nı kullanarak aracı oluşturması veya düzenlemesi gereken her ekip üyesine Azure AI KullanıcıRBAC rolünü atayın
    • Bu rol proje kapsamında atanmalıdır
    • Gerekli en düşük izinler: aracılar/*/okuma, aracılar/*/eylem, aracılar/*/delete

Ajana yapılandır ve çalıştır

İlk olarak yeni bir Java konsol projesi oluşturun. Kodu çalıştırmak için aşağıdaki bağımlılıklara ihtiyacınız olacaktır:

<dependencies>
    <dependency>
        <groupId>com.azure</groupId>
        <artifactId>azure-ai-agents-persistent</artifactId>
        <version>1.0.0-beta.2</version>
    </dependency>
    <dependency>
        <groupId>com.azure</groupId>
        <artifactId>azure-identity</artifactId>
        <version>1.17.0-beta.1</version>
    </dependency>
</dependencies>

Ardından API isteklerinizin kimliğini doğrulamak ve programı çalıştırmak için az login komutunu kullanarak Azure aboneliğinizde oturum açın.

az login

Aracı oluşturup çalıştırmak için aşağıdaki kodu kullanın. Bu kodu çalıştırmak için projenizin uç noktasını almanız gerekir. Bu dize şu biçimdedir:

https://<AIFoundryResourceName>.services.ai.azure.com/api/projects/<ProjectName>

Important

Mayıs 2025'te başlayan Azure AI Agent Service, daha önce hub tabanlı projeler için kullanılan bağlantı dizesi yerine Foundry projeleri için bir uç nokta kullanır. Hub tabanlı bir proje kullanıyorsanız SDK ve REST API'nin geçerli sürümlerini kullanamazsınız. Daha fazla bilgi için bkz. Hub tabanlı projelerle SDK kullanımı.

Uç noktanızı projenize genel bakış kısmında, Microsoft Foundry portalında, Kitaplıklar>Foundry altında bulabilirsiniz.

Dökümhane portalında uç noktayı gösteren ekran görüntüsü.

Bu uç noktayı adlı PROJECT_ENDPOINTbir ortam değişkeninde ayarlayın.

Ayrıca modelinizin dağıtım adına da ihtiyacınız vardır. Sol gezinti menüsündeki Modeller + Uç Noktalar'da bulabilirsiniz.

Dökümhane portalının model dağıtım ekranını gösteren ekran görüntüsü.

Model dağıtım adınızı adlı MODEL_DEPLOYMENT_NAMEbir ortam değişkeni olarak kaydedin.

Kod örneği

package com.example.agents;

import com.azure.ai.agents.persistent.MessagesClient;
import com.azure.ai.agents.persistent.PersistentAgentsAdministrationClient;
import com.azure.ai.agents.persistent.PersistentAgentsClient;
import com.azure.ai.agents.persistent.PersistentAgentsClientBuilder;
import com.azure.ai.agents.persistent.RunsClient;
import com.azure.ai.agents.persistent.ThreadsClient;
import com.azure.ai.agents.persistent.models.CodeInterpreterToolDefinition;
import com.azure.ai.agents.persistent.models.CreateAgentOptions;
import com.azure.ai.agents.persistent.models.CreateRunOptions;
import com.azure.ai.agents.persistent.models.MessageImageFileContent;
import com.azure.ai.agents.persistent.models.MessageRole;
import com.azure.ai.agents.persistent.models.MessageTextContent;
import com.azure.ai.agents.persistent.models.PersistentAgent;
import com.azure.ai.agents.persistent.models.PersistentAgentThread;
import com.azure.ai.agents.persistent.models.RunStatus;
import com.azure.ai.agents.persistent.models.ThreadMessage;
import com.azure.ai.agents.persistent.models.ThreadRun;
import com.azure.ai.agents.persistent.models.MessageContent;
import com.azure.core.http.rest.PagedIterable;
import com.azure.identity.DefaultAzureCredentialBuilder;
import java.util.Arrays;

public class AgentSample {

    public static void main(String[] args) {
        // variables for authenticating requests to the agent service 
        String projectEndpoint = System.getenv("PROJECT_ENDPOINT");
        String modelName = System.getenv("MODEL_DEPLOYMENT_NAME");

        // initialize clients to manage various aspects of agent runtime
        PersistentAgentsClientBuilder clientBuilder = new PersistentAgentsClientBuilder()
            .endpoint(projectEndpoint)
            .credential(new DefaultAzureCredentialBuilder().build());
        PersistentAgentsClient agentsClient = clientBuilder.buildClient();
        PersistentAgentsAdministrationClient administrationClient = agentsClient.getPersistentAgentsAdministrationClient();
        ThreadsClient threadsClient = agentsClient.getThreadsClient();
        MessagesClient messagesClient = agentsClient.getMessagesClient();
        RunsClient runsClient = agentsClient.getRunsClient();
        
        
        String agentName = "my-agent"; // the name of the agent
        CreateAgentOptions createAgentOptions = new CreateAgentOptions(modelName)
            .setName(agentName)
            .setInstructions("You are a helpful agent") // system insturctions
            .setTools(Arrays.asList(new CodeInterpreterToolDefinition()));
        PersistentAgent agent = administrationClient.createAgent(createAgentOptions);

        PersistentAgentThread thread = threadsClient.createThread();
        ThreadMessage createdMessage = messagesClient.createMessage(
            thread.getId(),
            MessageRole.USER,
            "I need to solve the equation `3x + 11 = 14`. Can you help me?"); // The message to the agent

        try {
            //run the agent
            CreateRunOptions createRunOptions = new CreateRunOptions(thread.getId(), agent.getId())
                .setAdditionalInstructions("");
            ThreadRun threadRun = runsClient.createRun(createRunOptions);
            // wait for the run to complete before printing the message
            waitForRunCompletion(thread.getId(), threadRun, runsClient);
            printRunMessages(messagesClient, thread.getId());
        } catch (InterruptedException e) {
            throw new RuntimeException(e);
        } finally {
            //cleanup - uncomment these lines if you want to delete the agent
            //threadsClient.deleteThread(thread.getId());
            //administrationClient.deleteAgent(agent.getId());
        }
    }

    // A helper function to print messages from the agent
    public static void printRunMessages(MessagesClient messagesClient, String threadId) {

        PagedIterable<ThreadMessage> runMessages = messagesClient.listMessages(threadId);
        for (ThreadMessage message : runMessages) {
            System.out.print(String.format("%1$s - %2$s : ", message.getCreatedAt(), message.getRole()));
            for (MessageContent contentItem : message.getContent()) {
                if (contentItem instanceof MessageTextContent) {
                    System.out.print((((MessageTextContent) contentItem).getText().getValue()));
                } else if (contentItem instanceof MessageImageFileContent) {
                    String imageFileId = (((MessageImageFileContent) contentItem).getImageFile().getFileId());
                    System.out.print("Image from ID: " + imageFileId);
                }
                System.out.println();
            }
        }
    }

    // a helper function to wait until a run has completed running
    public static void waitForRunCompletion(String threadId, ThreadRun threadRun, RunsClient runsClient)
        throws InterruptedException {

        do {
            Thread.sleep(500);
            threadRun = runsClient.getRun(threadId, threadRun.getId());
        }
        while (
            threadRun.getStatus() == RunStatus.QUEUED
                || threadRun.getStatus() == RunStatus.IN_PROGRESS
                || threadRun.getStatus() == RunStatus.REQUIRES_ACTION);

        if (threadRun.getStatus() == RunStatus.FAILED) {
            System.out.println(threadRun.getLastError().getMessage());
        }
    }
}

| Başvuru belgeleri |

Prerequisites

  • Aracı ortamını ayarlama
  • SDK veya Aracı Oyun Alanı'nı kullanarak aracı oluşturması veya düzenlemesi gereken her ekip üyesine Azure AI KullanıcıRBAC rolünü atayın
    • Bu rol proje kapsamında atanmalıdır
    • Gerekli en düşük izinler: aracılar/*/okuma, aracılar/*/eylem, aracılar/*/delete

Ajana yapılandır ve çalıştır

API isteklerinizin kimliğini doğrulamak için az login komutunu kullanarak Azure aboneliğinizde oturum açın.

az login

Ardından, API çağrılarına yetkilendirme sağlamak için Entra Id belirtecini getirmeniz gerekir. CLI komutunu kullanarak belirteci getirin:

az account get-access-token --resource 'https://ai.azure.com' | jq -r .accessToken | tr -d '"'

Erisim belirtecini bir ortam değişkeni olarak AGENT_TOKEN adıyla ayarlayın.

Foundry Agent Service'e REST API çağrılarını başarıyla yapmak için projenizin uç noktasını kullanmanız gerekir:

https://<your_ai_service_name>.services.ai.azure.com/api/projects/<your_project_name>

Örneğin, uç noktanız şuna benzer olacaktır:

https://exampleaiservice.services.ai.azure.com/api/projects/project

Bu uç noktayı adlı AZURE_AI_FOUNDRY_PROJECT_ENDPOINTbir ortam değişkeni olarak ayarlayın.

Note

  • api-version parametresi için GA API sürümü 2025-05-01 ve en son önizleme API sürümü 2025-05-15-preview. Önizleme aşamasındaki araçlar için önizleme API'sini kullanmanız gerekir.
  • API sürümünüzü $API_VERSION gibi bir ortam değişkeni yapmayı düşünün.

Bir aracı oluştur

Note

Azure AI Aracıları Hizmeti ile model parametre için model dağıtım adı gerekir. Model dağıtım adınız temel alınan model adından farklıysa kodunuzu olarak "model": "{your-custom-model-deployment-name}"ayarlayabilirsiniz.

curl --request POST \
  --url $AZURE_AI_FOUNDRY_PROJECT_ENDPOINT/assistants?api-version=2025-05-01 \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "You are a helpful agent.",
    "name": "my-agent",
    "tools": [{"type": "code_interpreter"}],
    "model": "gpt-4o-mini"
  }'

Bir konu oluştur

curl --request POST \
  --url $AZURE_AI_FOUNDRY_PROJECT_ENDPOINT/threads?api-version=2025-05-01 \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d ''

Konuya bir kullanıcı sorusu ekle

curl --request POST \
  --url $AZURE_AI_FOUNDRY_PROJECT_ENDPOINT/threads/thread_abc123/messages?api-version=2025-05-01 \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
      "role": "user",
      "content": "I need to solve the equation `3x + 11 = 14`. Can you help me?"
    }'

İpliği çalıştır

curl --request POST \
  --url $AZURE_AI_FOUNDRY_PROJECT_ENDPOINT/threads/thread_abc123/runs?api-version=2025-05-01 \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": "asst_abc123",
  }'

Çalıştırmanın durumunu kontrol et

curl --request GET \
  --url $AZURE_AI_FOUNDRY_PROJECT_ENDPOINT/threads/thread_abc123/runs/run_abc123?api-version=2025-05-01 \
  -H "Authorization: Bearer $AGENT_TOKEN"

Temsilcinin yanıtını al

curl --request GET \
  --url $AZURE_AI_FOUNDRY_PROJECT_ENDPOINT/threads/thread_abc123/messages?api-version=2025-05-01 \
  -H "Authorization: Bearer $AGENT_TOKEN"

Sonraki Adımlar

Aracılarınızın web'e erişme, temel bilgileri sağlama gibi özelliklerini genişletmek için kullanabileceğiniz araçlar hakkında bilgi edinin.

  • Last updated on