Compartilhar via

Início Rápido: Criar um novo agente

Note

Este documento refere-se ao portal do Microsoft Foundry (clássico ).

🔍 Exiba a documentação do Microsoft Foundry (novo) para saber mais sobre o novo portal.

Note

Este início rápido é para a versão anterior dos agentes. Confira o início rápido do Microsoft Foundry para usar a nova versão da API.

O Serviço do Foundry Agent permite que você crie agentes de IA adaptados às suas necessidades por meio de instruções personalizadas e aumentadas por ferramentas avançadas, como interpretador de código e funções personalizadas.

Prerequisites

  • Uma assinatura do Azure – Crie uma gratuitamente.
  • Verifique se o indivíduo que cria a conta e o projeto tem a função de Proprietário da Conta de IA do Azure no escopo da assinatura, o que concederá as permissões necessárias para criar o projeto
    • Como alternativa, ter a função Colaborador ou Colaborador dos Serviços Cognitivos no nível da assinatura permitirá a criação do projeto
  • Depois que o projeto for criado, verifique se o indivíduo que cria o agente dentro do projeto tem a função de usuário de IA do Azure no nível do projeto

Important

O portal do Microsoft Foundry só dá suporte à configuração básica do agente no momento. Se você quiser executar uma configuração de agente padrão, consulte o artigo de configuração do Ambiente para saber mais.

Criar uma conta e um projeto do Foundry no portal do Foundry

Para criar uma conta e um projeto no Foundry, siga estas etapas:

  1. Vá à Foundry. Se você estiver em um projeto, selecione Foundry no canto superior esquerdo da página para acessar a home page.

  2. Use o fluxo de criação de introdução do agente para a experiência mais rápida. Clique em Criar um agente.

    Uma captura de tela do portal do Foundry.

  3. Insira um nome para o projeto. Se você quiser personalizar os valores padrão, selecione Opções avançadas.

    Uma captura de tela das opções avançadas para criar um projeto.

  4. Selecione Criar.

  5. Aguarde até que seus recursos sejam provisionados.

    1. Uma conta e um projeto (recurso filho da sua conta) serão criados.
    2. O modelo gpt-4o será implantado automaticamente
    3. Um agente padrão será criado

  6. Após a conclusão, você entrará diretamente no playground do agente e poderá começar a criar agentes. Você pode dar ao seu agente instruções sobre o que fazer e como fazer isso. Por exemplo: "Você é um agente útil que pode responder perguntas sobre geografia.". Em seguida, você pode começar a conversar com seu agente.

    Captura de tela do playground do agente.

    Note

    Se você estiver recebendo um erro de permissão ao tentar configurar ou criar agentes, verifique se você tem o Usuário de IA do Azure no projeto.

| Documentação de referência | Exemplos | Código-fonte da biblioteca | Pacote (NuGet) |

Prerequisites

  • Um ambiente de agente de configuração
  • Atribuir a função RBAC do usuário de IA do Azure a cada membro da equipe que precisa criar ou editar agentes usando o SDK ou o Agent Playground
    • Essa função deve ser atribuída no escopo do projeto
    • Permissões mínimas necessárias: agentes/*/read, agents/*/action, agents/*/delete

Configurar e executar um agente

Crie um projeto do Console do .NET.

dotnet new console

Instale o pacote .NET em seu projeto. Por exemplo, se você estiver usando a CLI do .NET, execute o comando a seguir.

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

Em seguida, para autenticar suas solicitações de API e executar o programa, use o comando az login para entrar em sua assinatura do Azure.

az login

Use o código a seguir para criar e executar um agente. Para executar esse código, você precisará obter o ponto de extremidade do seu projeto. Esta cadeia de caracteres está no formato:

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

Important

A partir de maio de 2025, o Serviço de Agente de IA do Azure usa um endpoint para projetos do Foundry em vez da cadeia de conexão usada anteriormente para projetos baseados em hub. Se você estiver usando um projeto baseado em hub, não poderá usar as versões atuais do SDK e da API REST. Para obter mais informações, consulte o uso do SDK com projetos baseados em hub.

Você pode encontrar seu ponto de extremidade na visão geral do seu projeto no portal do Microsoft Foundry, em Bibliotecas>Foundry.

Uma captura de tela mostrando o endpoint no portal do Foundry.

Defina esse ponto de extremidade em uma variável de ambiente chamada ProjectEndpoint.

Você também precisa do nome de implantação do modelo. Você pode encontrá-lo em Modelos + Pontos de Extremidade no menu de navegação à esquerda.

Uma captura de tela mostrando a tela de implantação do modelo no portal do Foundry.

Salve o nome do seu nome de implantação de modelo como uma variável de ambiente chamada ModelDeploymentName.

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

| Documentação de referência | Exemplos | Código-fonte da biblioteca | Pacote (PyPi) |

Prerequisites

  • Um ambiente de agente de configuração
  • Atribuir a função RBAC do usuário de IA do Azure a cada membro da equipe que precisa criar ou editar agentes usando o SDK ou o Agent Playground
    • Essa função deve ser atribuída no escopo do projeto
    • Permissões mínimas necessárias: agentes/*/read, agents/*/action, agents/*/delete

Configurar e executar um agente

Execute os comandos a seguir para instalar os pacotes do Python.

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

Em seguida, para autenticar suas solicitações de API e executar o programa, use o comando az login para entrar em sua assinatura do Azure.

az login

Use o código a seguir para criar e executar um agente. Para executar esse código, você precisará obter o ponto de extremidade do seu projeto. Esta cadeia de caracteres está no formato:

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

Important

A partir de maio de 2025, o Serviço de Agente de IA do Azure usa um endpoint para projetos do Foundry em vez da cadeia de conexão usada anteriormente para projetos baseados em hub. Se você estiver usando um projeto baseado em hub, não poderá usar as versões atuais do SDK e da API REST. Para obter mais informações, consulte o uso do SDK com projetos baseados em hub.

Você pode encontrar seu ponto de extremidade na visão geral do seu projeto no portal do Microsoft Foundry, em Bibliotecas>Foundry.

Uma captura de tela mostrando o endpoint no portal do Foundry.

Defina esse ponto de extremidade como uma variável de ambiente chamada PROJECT_ENDPOINT.

Você também precisa do nome de implantação do modelo. Você pode encontrá-lo em Modelos + Pontos de Extremidade no menu de navegação à esquerda.

Uma captura de tela mostrando a tela de implantação do modelo no portal do Foundry.

Salve o nome do seu nome de implantação de modelo como uma variável de ambiente chamada MODEL_DEPLOYMENT_NAME.

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

| Documentação de referência | Exemplos | Código-fonte da biblioteca | Pacote (npm) |

Prerequisites

  • Um ambiente de agente de configuração
  • Atribuir a função RBAC do usuário de IA do Azure a cada membro da equipe que precisa criar ou editar agentes usando o SDK ou o Agent Playground
    • Essa função deve ser atribuída no escopo do projeto
    • Permissões mínimas necessárias: agentes/*/read, agents/*/action, agents/*/delete

Configurar e executar um agente

Os principais objetos neste código incluem:

Primeiro, inicialize um novo projeto TypeScript executando:

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

Execute os comandos a seguir para instalar os pacotes npm necessários.

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

Em seguida, para autenticar suas solicitações de API e executar o programa, use o comando az login para entrar em sua assinatura do Azure.

az login

Use o código a seguir para responder à pergunta I need to solve the equation '3x + 11 = 14'. Can you help me?matemática. Para executar esse código, você precisará obter o ponto de extremidade do seu projeto. Esta cadeia de caracteres está no formato:

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

Você pode encontrar seu ponto de extremidade na visão geral do seu projeto no portal do Microsoft Foundry, em Bibliotecas>Foundry.

Uma captura de tela mostrando o endpoint no portal do Foundry.

Defina esse ponto de extremidade como uma variável de ambiente nomeada PROJECT_ENDPOINT em um .env arquivo.

Você também precisa do nome de implantação do modelo. Você pode encontrá-lo em Modelos + Pontos de Extremidade no menu de navegação à esquerda.

Uma captura de tela mostrando a tela de implantação do modelo no portal do Foundry.

Salve o nome do seu nome de implantação de modelo como uma variável de ambiente chamada MODEL_DEPLOYMENT_NAME.

Important

  • Este código de início rápido usa variáveis de ambiente para configuração confidencial. Nunca faça commit do seu arquivo .env no controle de versão, certificando-se de que .env esteja listado em seu arquivo .gitignore.
  • Lembre-se: se você fizer commit de informações confidenciais acidentalmente, considere essas credenciais comprometidas e gire-as imediatamente.

Crie um arquivo tsconfig.json com o seguinte conteúdo:

{
  "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,
  }
}

Em seguida, crie um index.ts arquivo e cole o seguinte código:

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

Execute o código usando npx tsx -r dotenv/config index.ts. Esse código responde à pergunta I need to solve the equation '3x + 11 = 14'. Can you help me?. As respostas não são determinísticas, sua saída será semelhante à saída abaixo:

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

Código-fonte de exemplo completo disponível.

| Documentação de referência | Amostras | Código-fonte da biblioteca | Pacote (Maven) |

Prerequisites

  • Um ambiente de agente de configuração
  • Atribuir a função RBAC do usuário de IA do Azure a cada membro da equipe que precisa criar ou editar agentes usando o SDK ou o Agent Playground
    • Essa função deve ser atribuída no escopo do projeto
    • Permissões mínimas necessárias: agentes/*/read, agents/*/action, agents/*/delete

Configurar e executar um agente

Primeiro, crie um novo projeto de console Java. Você precisará das seguintes dependências para executar o código:

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

Em seguida, para autenticar suas solicitações de API e executar o programa, use o comando az login para entrar em sua assinatura do Azure.

az login

Use o código a seguir para criar e executar um agente. Para executar esse código, você precisará obter o ponto de extremidade do seu projeto. Esta cadeia de caracteres está no formato:

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

Important

A partir de maio de 2025, o Serviço de Agente de IA do Azure usa um endpoint para projetos do Foundry em vez da cadeia de conexão usada anteriormente para projetos baseados em hub. Se você estiver usando um projeto baseado em hub, não poderá usar as versões atuais do SDK e da API REST. Para obter mais informações, consulte o uso do SDK com projetos baseados em hub.

Você pode encontrar seu ponto de extremidade na visão geral do seu projeto no portal do Microsoft Foundry, em Bibliotecas>Foundry.

Uma captura de tela mostrando o endpoint no portal do Foundry.

Defina esse ponto de extremidade em uma variável de ambiente chamada PROJECT_ENDPOINT.

Você também precisa do nome de implantação do modelo. Você pode encontrá-lo em Modelos + Pontos de Extremidade no menu de navegação à esquerda.

Uma captura de tela mostrando a tela de implantação do modelo no portal do Foundry.

Salve o nome do seu nome de implantação de modelo como uma variável de ambiente chamada MODEL_DEPLOYMENT_NAME.

Exemplo de código

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

| Documentação de referência |

Prerequisites

  • Um ambiente de agente de configuração
  • Atribuir a função RBAC do usuário de IA do Azure a cada membro da equipe que precisa criar ou editar agentes usando o SDK ou o Agent Playground
    • Essa função deve ser atribuída no escopo do projeto
    • Permissões mínimas necessárias: agentes/*/read, agents/*/action, agents/*/delete

Configurar e executar um agente

Para autenticar suas solicitações de API, use o comando az login para entrar em sua assinatura do Azure.

az login

Em seguida, você precisará buscar o token do Entra ID para fornecer como autorização para as chamadas à API. Busque o token usando o comando da CLI:

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

Defina o token de acesso como uma variável de ambiente chamada AGENT_TOKEN.

Para fazer chamadas REST API para o Serviço do Foundry Agent, você precisará usar o endpoint do projeto:

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

Por exemplo, seu endpoint será semelhante a:

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

Defina esse ponto de extremidade como uma variável de ambiente chamada AZURE_AI_FOUNDRY_PROJECT_ENDPOINT.

Note

  • Para o parâmetro api-version, a versão da API GA é 2025-05-01 e a versão mais recente da API de visualização é 2025-05-15-preview. Você deve usar a API de visualização para ferramentas que estão em versão prévia.
  • Considere tornar sua versão da API uma variável de ambiente, como $API_VERSION.

Criar um agente

Note

Com o Serviço de Agentes de IA do Azure, o parâmetro model requer o nome da implantação do modelo. Se o nome da implantação de modelo for diferente do nome do modelo subjacente, você ajustará seu código para "model": "{your-custom-model-deployment-name}".

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

Criar um thread

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

Adicionar uma pergunta do usuário ao thread

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

Executar a conversa

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

Recuperar o status da execução

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"

Recuperar a resposta do agente

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

Próximas etapas

Saiba mais sobre as ferramentas que você pode usar para estender os recursos de seus agentes, como acessar a Web, fornecer informações de aterramento e muito mais.

  • Last updated on