Início rápido: Criar um novo agente (clássico)

Pré-requisitos

• Uma subscrição Azure - Crie uma gratuitamente.

• Garantir que a pessoa que cria a conta e o projeto tem o papel de Proprietário da Conta Foundry no âmbito da subscrição, o que concederá as permissões necessárias para criar o projeto

  Importante

  As funções RBAC do Foundry foram recentemente renomeadas. Foundry User, Foundry Owner, Foundry Account Owner e Foundry Project Manager foram anteriormente nomeados Azure AI User, Azure AI Owner, Azure AI Account Owner e Azure AI Project Manager. Poderá ainda ver os nomes anteriores em alguns locais enquanto esta alteração de nome está a ser implementada. Os IDs das funções e as permissões principais não são alterados por esta mudança de nome.

  • Alternativamente, ter o papel de Contribuinte ou Proprietário ao nível da subscrição permitirá a criação do projeto

• Depois de o projeto ser criado, certifique-se de que a pessoa que está a criar o agente no projeto tem a função Utilizador Foundry atribuída ao nível do projeto

Crie uma conta Foundry e um projeto no portal Foundry

Para criar uma conta e um projeto no Foundry, siga estes passos:

1. Vai à Foundry. Se estiver num projeto, selecione Foundry no canto superior esquerdo da página para ir à página inicial.

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

   

3. Introduza um nome para o projeto. Se quiser personalizar os valores predefinidos, selecione Opções Avançadas.

   

4. Selecione Criar.

5. Espere que os seus recursos sejam provisionados.

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

6. Quando estiver concluído, será encaminhado diretamente para a área de treino dos agentes e pode começar a criar agentes. Pode dar instruções ao seu agente sobre o que fazer e como o fazer. Por exemplo: "És um agente prestável que pode responder a perguntas sobre geografia." Depois podes começar a conversar com o teu agente.

   

   Nota

   Se estiver a receber erro de permissão ao tentar configurar ou criar agentes, certifique-se de que tem o Utilizador Foundry no projeto.

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

Pré-requisitos

• Um ambiente preparado para agentes

• Atribua a função Foundry UserRBAC a cada membro da equipa que necessite de criar ou editar agentes com o SDK ou o Agent Playground

  Importante

  As funções RBAC do Foundry foram recentemente renomeadas. Foundry User, Foundry Owner, Foundry Account Owner e Foundry Project Manager foram anteriormente nomeados Azure AI User, Azure AI Owner, Azure AI Account Owner e Azure AI Project Manager. Poderá ainda ver os nomes anteriores em alguns locais enquanto esta alteração de nome está a ser implementada. Os IDs das funções e as permissões principais não são alterados por esta mudança de nome.

  • Este papel deve ser atribuído no âmbito do projeto
  • Permissões mínimas obrigatórias: agents/*/read, agents/*/action, agents/*/delete

Configurar e executar um agente

Crie um projeto de consola .NET.

dotnet new console

Instale o pacote .NET no seu projeto. Por exemplo, se estiveres a usar a CLI .NET, executa o seguinte comando.

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

De seguida, para autenticar os seus pedidos de API e executar o programa, use o comando az login para iniciar sessão na sua subscrição Azure.

az login

Use o código seguinte para criar e executar um agente. Para executar este código, vais precisar de obter o endpoint do teu projeto. Esta cadeia está no formato:

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

Pode encontrar o seu endpoint na visão geral do seu projeto no Portal Foundry da Microsoft, em Libraries>Foundry.

Defina este endpoint numa variável de ambiente chamada ProjectEndpoint.

Também precisa do nome de implementação do seu modelo. Podes encontrá-lo em Modelos + Endpoints no menu de navegação à esquerda.

Guarde o nome do nome de implementação do seu 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ênciaExemplos | Código-fonte | da bibliotecaPacote (PyPi) |

Pré-requisitos

• Um ambiente preparado para agentes

• Atribua a Foundry Userfunção RBAC a cada membro da equipa que precise de criar ou editar agentes com o SDK ou o Agent Playground

  Importante

  As funções RBAC do Foundry foram recentemente renomeadas. Foundry User, Foundry Owner, Foundry Account Owner e Foundry Project Manager foram anteriormente nomeados Azure AI User, Azure AI Owner, Azure AI Account Owner e Azure AI Project Manager. Poderá ainda ver os nomes anteriores em alguns locais enquanto esta alteração de nome está a ser implementada. Os IDs das funções e as permissões principais não são alterados por esta mudança de nome.

  • Este papel deve ser atribuído no âmbito do projeto
  • Permissões mínimas obrigatórias: agents/*/read, agents/*/action, agents/*/delete

Configurar e executar um agente

Execute os seguintes comandos para instalar os pacotes em python.

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

De seguida, para autenticar os seus pedidos de API e executar o programa, use o comando az login para iniciar sessão na sua subscrição Azure.

az login

Use o código seguinte para criar e executar um agente. Para executar este código, vais precisar de obter o endpoint do teu projeto. Esta cadeia está no formato:

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

Pode encontrar o seu endpoint na visão geral do seu projeto no Portal Foundry da Microsoft, em Libraries>Foundry.

Defina este endpoint como uma variável de ambiente chamada PROJECT_ENDPOINT.

Também precisa do nome de implementação do seu modelo. Podes encontrá-lo em Modelos + Endpoints no menu de navegação à esquerda.

Guarde o nome do nome de implementação do seu 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 | Samples | Código-fonte da biblioteca | Package (npm) |

Pré-requisitos

• Um ambiente preparado para agentes

• Atribua a função de Utilizador do FoundryRBAC a cada membro da equipa que precise de criar ou editar agentes utilizando o SDK ou o Agent Playground

  Importante

  As funções RBAC do Foundry foram recentemente renomeadas. Foundry User, Foundry Owner, Foundry Account Owner e Foundry Project Manager foram anteriormente nomeados Azure AI User, Azure AI Owner, Azure AI Account Owner e Azure AI Project Manager. Poderá ainda ver os nomes anteriores em alguns locais enquanto esta alteração de nome está a ser implementada. Os IDs das funções e as permissões principais não são alterados por esta mudança de nome.

  • Este papel deve ser atribuído no âmbito do projeto
  • Permissões mínimas obrigatórias: agents/*/read, agents/*/action, agents/*/delete

• Node.js LTS

Configurar e executar um agente

Objetos-chave neste código incluem:

• AgentsClient

Primeiro, inicialize um novo projeto TypeScript executando:

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

Execute os seguintes comandos para instalar os pacotes npm necessários.

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

De seguida, para autenticar os seus pedidos de API e executar o programa, use o comando az login para iniciar sessão na sua subscrição Azure.

az login

Use o seguinte código para responder à pergunta I need to solve the equation '3x + 11 = 14'. Can you help me?de matemática. Para executar este código, vais precisar de obter o endpoint do teu projeto. Esta cadeia está no formato:

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

Pode encontrar o seu endpoint na visão geral do seu projeto no Portal Foundry da Microsoft, em Libraries>Foundry.

Defina este endpoint como uma variável de ambiente nomeada PROJECT_ENDPOINT num .env ficheiro.

Também precisa do nome de implementação do seu modelo. Podes encontrá-lo em Modelos + Endpoints no menu de navegação à esquerda.

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

Crie um ficheiro 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,
  }
}

De seguida, crie um index.ts ficheiro 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);
});

Executa o código usando npx tsx -r dotenv/config index.ts. Este código responde à questão I need to solve the equation '3x + 11 = 14'. Can you help me?. As respostas não são determinísticas, a 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 completo exemplo disponível.

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

Pré-requisitos

• Um ambiente preparado para agentes

• Atribuir a função Foundry UserRBAC a cada membro da equipa que precise de criar ou editar agentes com o SDK ou o Agent Playground

  Importante

  As funções RBAC do Foundry foram recentemente renomeadas. Foundry User, Foundry Owner, Foundry Account Owner e Foundry Project Manager foram anteriormente nomeados Azure AI User, Azure AI Owner, Azure AI Account Owner e Azure AI Project Manager. Poderá ainda ver os nomes anteriores em alguns locais enquanto esta alteração de nome está a ser implementada. Os IDs das funções e as permissões principais não são alterados por esta mudança de nome.

  • Este papel deve ser atribuído no âmbito do projeto
  • Permissões mínimas obrigatórias: agents/*/read, agents/*/action, agents/*/delete

Configurar e executar um agente

Primeiro, crie um novo projeto de consola Java. Vai 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>

De seguida, para autenticar os seus pedidos de API e executar o programa, use o comando az login para iniciar sessão na sua subscrição Azure.

az login

Use o código seguinte para criar e executar um agente. Para executar este código, vais precisar de obter o endpoint do teu projeto. Esta cadeia está no formato:

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

Pode encontrar o seu endpoint na visão geral do seu projeto no Portal Foundry da Microsoft, em Libraries>Foundry.

Defina este endpoint numa variável de ambiente chamada PROJECT_ENDPOINT.

Também precisa do nome de implementação do seu modelo. Podes encontrá-lo em Modelos + Endpoints no menu de navegação à esquerda.

Guarde o nome do nome de implementação do seu 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 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());
        }
    }
}

| Documentação de referência |

Pré-requisitos

• Um ambiente preparado para agentes

• Atribua a Utilizador Foundryfunção RBAC a cada membro da equipa que precise de criar ou editar agentes através do SDK ou do Agent Playground

  Importante

  As funções RBAC do Foundry foram recentemente renomeadas. Foundry User, Foundry Owner, Foundry Account Owner e Foundry Project Manager foram anteriormente nomeados Azure AI User, Azure AI Owner, Azure AI Account Owner e Azure AI Project Manager. Poderá ainda ver os nomes anteriores em alguns locais enquanto esta alteração de nome está a ser implementada. Os IDs das funções e as permissões principais não são alterados por esta mudança de nome.

  • Este papel deve ser atribuído no âmbito do projeto
  • Permissões mínimas obrigatórias: agents/*/read, agents/*/action, agents/*/delete

Configurar e executar um agente

Para autenticar os seus pedidos de API, use o comando az login para iniciar sessão na sua subscrição Azure.

az login

De seguida, terá de buscar o token Entra ID para fornecer autorização às chamadas da API. Obtém o token usando o comando 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 com sucesso chamadas REST API ao Foundry Agent Service, terá de usar o endpoint do seu projeto:

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

Por exemplo, o seu endpoint terá uma aparência semelhante à:

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

Defina este endpoint como uma variável de ambiente chamada AZURE_AI_FOUNDRY_PROJECT_ENDPOINT.

Criar um agente

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

Crie um tópico

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

Adicione uma pergunta de utilizador ao tópico

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

Abre o tópico

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 estado da corrida

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"