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

Not

Bu belge, Microsoft Dökümhane (klasik) portalına atıfta bulunur.

Ajanlar (klasik) artık önerilmemektedir ve 31 Mart 2027'de kullanımdan kaldırılacaktır. Genel kullanıma sunulan Microsoft Foundry Agents Service yeni aracıları kullanın. İş yüklerinizi güncelleştirmek için geçiş kılavuzunu izleyin.

Not

Bu hızlı başlangıç kılavuzu, aracıların önceki sürümü içindir. API'nin yeni sürümünü kullanmak için Microsoft Foundry için quickstart bölümüne 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.

Önkoşullar

• Azure aboneliği - ücretsiz bir abonelik oluşturma.

• Hesabı ve projeyi oluşturan kişinin, abonelik kapsamı düzeyinde Foundry Account Owner rolüne sahip olduğundan emin olun; bu, projenin oluşturulması için gerekli izinleri sağlar.

  Önemli

  Foundry RBAC rolleri yakın zamanda yeniden adlandırıldı. Foundry User, Foundry Owner, Foundry Hesabı Sahibi ve Foundry Project Manager daha önce Azure Yapay Zeka Kullanıcısı, Azure Yapay Zeka Sahibi, Azure Yapay Zeka Hesabı Sahibi ve Azure Yapay Zeka Project Yöneticisi olarak adlandırıldı. Yeniden adlandırma kullanıma sunulmaya devam ederken bazı yerlerde önceki adları görmeye devam edebilirsiniz. Rol kimlikleri ve temel izinler yeniden adlandırma ile değiştirilmez.

  • Alternatif olarak, abonelik düzeyinde Katkıda Bulunan veya Sahip rolüne sahip olmak projenin oluşturulmasına izin verir

• Proje oluşturulduktan sonra, proje içinde aracıyı oluşturacak kişinin proje düzeyinde Foundry User rolüne sahip olduğundan emin olun

Önemli

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.

Foundry portalında bir Foundry 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ı deneyimi elde etmek için Aracı başlatma sürecini kullanın. Aracı oluştur'a tıklayın.

   

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

   

4. Oluştur'u seçin.

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

   1. Hesabınız için bir hesap ve proje (alt kaynak) oluşturulacaktır.
   2. gpt-4o modeli otomatik olarak dağıtılacak
   3. Varsayılan aracı oluşturulacak

6. İşlem tamamlandığında, doğrudan uygulama geliştirme alanına inecek ve aracınızı oluşturmaya başlayabilirsiniz. Temsilcinize ne yapması ve nasıl yapması gerektiğine dair 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.

   

   Not

   Aracıları yapılandırmaya veya oluşturmaya çalışırken bir izin hatası alıyorsanız, proje üzerinde Foundry User rolüne sahip olduğunuzdan emin olun.

| Başvuru belgeleri | Örnekler | Library kaynak kodu | Package (NuGet) |

Önkoşullar

• Aracı ortamını ayarlama

• SDK'yı veya Aracı Oyun Alanı'nı kullanarak aracı oluşturması veya düzenlemesi gereken her ekip üyesine Dökümhane KullanıcısıRBAC rolünü atayın

  Önemli

  Foundry RBAC rolleri yakın zamanda yeniden adlandırıldı. Foundry User, Foundry Owner, Foundry Hesabı Sahibi ve Foundry Project Manager daha önce Azure Yapay Zeka Kullanıcısı, Azure Yapay Zeka Sahibi, Azure Yapay Zeka Hesabı Sahibi ve Azure Yapay Zeka Project Yöneticisi olarak adlandırıldı. Yeniden adlandırma kullanıma sunulmaya devam ederken bazı yerlerde önceki adları görmeye devam edebilirsiniz. Rol kimlikleri ve temel izinler yeniden adlandırma ile değiştirilmez.

  • Bu rol proje kapsamında atanmalıdır
  • Gerekli en düşük izinler: aracılar/*/okuma, aracılar/*/eylem, aracılar/*/delete

Ajanı yapılandırın ve çalıştırın

bir .NET Konsolu projesi oluşturun.

dotnet new console

projenize .NET paketini 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 Azure aboneliğinizde oturum açmak için az login komutunu kullanın.

az login

Aracı oluşturmak ve ç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>

Önemli

Mayıs 2025 itibarıyla Azure AI Agent Hizmeti, 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ı.

Projeniz için uç noktanızı Microsoft Foundry portalının genel bakış kısmında, Libraries altında, Foundry başlığı altında bulabilirsiniz.

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.

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

| Başvuru belgeleri | Örnekleri | Kitaplık kaynak kodu | Paket (PyPi) |

Önkoşullar

• Aracı ortamını ayarlama

• SDK’yı veya Ajan Oyun Alanı’nı kullanarak ajan oluşturması ya da düzenlemesi gereken her ekip üyesine Foundry UserRBAC rolünü atayın

  Önemli

  Foundry RBAC rolleri yakın zamanda yeniden adlandırıldı. Foundry User, Foundry Owner, Foundry Hesabı Sahibi ve Foundry Project Manager daha önce Azure Yapay Zeka Kullanıcısı, Azure Yapay Zeka Sahibi, Azure Yapay Zeka Hesabı Sahibi ve Azure Yapay Zeka Project Yöneticisi olarak adlandırıldı. Yeniden adlandırma kullanıma sunulmaya devam ederken bazı yerlerde önceki adları görmeye devam edebilirsiniz. Rol kimlikleri ve temel izinler yeniden adlandırma ile değiştirilmez.

  • Bu rol proje kapsamında atanmalıdır
  • Gerekli en düşük izinler: aracılar/*/okuma, aracılar/*/eylem, aracılar/*/delete

Ajanı yapılandırın ve çalıştırın

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 Azure aboneliğinizde oturum açmak için az login komutunu kullanın.

az login

Aracı oluşturmak ve ç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>

Önemli

Mayıs 2025 itibarıyla Azure AI Agent Hizmeti, 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ı.

Projeniz için uç noktanızı Microsoft Foundry portalının genel bakış kısmında, Libraries altında, Foundry başlığı altında bulabilirsiniz.

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.

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

| Reference belgeleri | Örnekler | Kütüphane kaynak kodu | Paket (npm) |

Önkoşullar

• Aracı ortamını ayarlama

• SDK veya Agent Playground kullanarak agent oluşturmaya ya da düzenlemeye ihtiyaç duyan her ekip üyesine Foundry UserRBAC rolünü atayın

  Önemli

  Foundry RBAC rolleri yakın zamanda yeniden adlandırıldı. Foundry User, Foundry Owner, Foundry Hesabı Sahibi ve Foundry Project Manager daha önce Azure Yapay Zeka Kullanıcısı, Azure Yapay Zeka Sahibi, Azure Yapay Zeka Hesabı Sahibi ve Azure Yapay Zeka Project Yöneticisi olarak adlandırıldı. Yeniden adlandırma kullanıma sunulmaya devam ederken bazı yerlerde önceki adları görmeye devam edebilirsiniz. Rol kimlikleri ve temel izinler yeniden adlandırma ile değiştirilmez.

  • Bu rol proje kapsamında atanmalıdır
  • Gerekli en düşük izinler: aracılar/*/okuma, aracılar/*/eylem, aracılar/*/delete

• Node.js LTS

Ajanı yapılandırın ve çalıştırın

Bu koddaki anahtar nesneler şunlardır:

• AgentsClient

İ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 Azure aboneliğinizde oturum açmak için az login komutunu kullanı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>

Projeniz için uç noktanızı Microsoft Foundry portalının genel bakış kısmında, Libraries altında, Foundry başlığı altında bulabilirsiniz.

Bu uç noktayı PROJECT_ENDPOINT dosyasında .env olarak adlandırılan bir ortam değişkeni şeklinde 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.

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

Önemli

• Bu hızlı başlangıç kodu, hassas yapılandırma için ortam değişkenlerini kullanır. .env dosyanızda listelendiğinden emin olarak .env dosyanızı hiçbir zaman sürüm denetimine yüklemeyin .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 | Library kaynak kodu | Package (Maven) |

Önkoşullar

• Aracı ortamını ayarlama

• SDK’yı veya Agent Playground’u kullanarak ajan oluşturması ya da düzenlemesi gereken her ekip üyesine Foundry UserRBAC rolünü atayın

  Önemli

  Foundry RBAC rolleri yakın zamanda yeniden adlandırıldı. Foundry User, Foundry Owner, Foundry Hesabı Sahibi ve Foundry Project Manager daha önce Azure Yapay Zeka Kullanıcısı, Azure Yapay Zeka Sahibi, Azure Yapay Zeka Hesabı Sahibi ve Azure Yapay Zeka Project Yöneticisi olarak adlandırıldı. Yeniden adlandırma kullanıma sunulmaya devam ederken bazı yerlerde önceki adları görmeye devam edebilirsiniz. Rol kimlikleri ve temel izinler yeniden adlandırma ile değiştirilmez.

  • Bu rol proje kapsamında atanmalıdır
  • Gerekli en düşük izinler: aracılar/*/okuma, aracılar/*/eylem, aracılar/*/delete

Ajanı yapılandırın ve çalıştırın

İlk olarak Yeni 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 Azure aboneliğinizde oturum açmak için az login komutunu kullanın.

az login

Aracı oluşturmak ve ç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>

Önemli

Mayıs 2025 itibarıyla Azure AI Agent Hizmeti, 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ı.

Projeniz için uç noktanızı Microsoft Foundry portalının genel bakış kısmında, Libraries altında, Foundry başlığı altında bulabilirsiniz.

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.

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

Önkoşullar

• Aracı ortamını ayarlama

• SDK'yı veya Aracı Oyun Alanı'nı kullanarak aracı oluşturması veya düzenlemesi gereken her ekip üyesine Dökümhane KullanıcısıRBAC rolünü atayın

  Önemli

  Foundry RBAC rolleri yakın zamanda yeniden adlandırıldı. Foundry User, Foundry Owner, Foundry Hesabı Sahibi ve Foundry Project Manager daha önce Azure Yapay Zeka Kullanıcısı, Azure Yapay Zeka Sahibi, Azure Yapay Zeka Hesabı Sahibi ve Azure Yapay Zeka Project Yöneticisi olarak adlandırıldı. Yeniden adlandırma kullanıma sunulmaya devam ederken bazı yerlerde önceki adları görmeye devam edebilirsiniz. Rol kimlikleri ve temel izinler yeniden adlandırma ile değiştirilmez.

  • Bu rol proje kapsamında atanmalıdır
  • Gerekli en düşük izinler: aracılar/*/okuma, aracılar/*/eylem, aracılar/*/delete

Ajanı yapılandırın ve çalıştırın

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

az login

Ardından, API çağrılarına yetkilendirme olarak 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 '"'

Erişim belirtecini AGENT_TOKEN adlı bir ortam değişkeni olarak 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.

Not

• 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 şeklindedir. Ö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 olarak yapmayı göz önünde bulundurun.

Bir ajan oluştur

Not

Azure AI Aracıları Hizmeti ile model parametresi model dağıtım adı gerektirir. 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"
  }'

İş parçacığı 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 ''

İş parçacığına 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?"
    }'

İş parçacığını çalıştırma

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ırma durumunu al

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"

Aracı yanıtını alın

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.