Criar sistemas colaborativos de vários agentes com Agentes Conectados (clássico)

Criando uma configuração de vários agentes

1. Navegue até a página Agentes no portal
2. Selecione um agente existente na lista ou crie um novo.
3. Role para baixo até a seção Agentes conectados no painel configurado do agente e selecione Adicionar +.

4. Na caixa de diálogo exibida, escolha um agente para o agente principal para o qual delegar tarefas e descreva:

   • Selecione um agente existente na lista suspensa. Esse é o agente conectado ao qual o agente principal delegará tarefas.
   • Insira um nome exclusivo para o agente conectado (somente letras e sublinhados). Esse nome é usado para chamada de função no nível da API. Mantenha-o descritivo e legível pelo computador para maximizar a precisão do recall (por exemplo, summarize_text, ). lookup_product_info
   • Adicione uma descrição clara de quando e por que o agente conectado deve ser invocado. Isso ajuda a orientar a tomada de decisão do agente principal sobre quando entregar tarefas a agentes conectados durante o runtime.

5. Selecione Adicionar +

6. Repita as etapas 3 a 5 para adicionar agentes especializados adicionais ao agente principal.

7. Depois que os agentes conectados aparecerem no painel de instalação, role para cima e selecione Experimentar no Playground

8. Use prompts de teste no Agent Playground para validar que o agente principal roteia corretamente as tarefas para os agentes conectados quando aplicável. Por exemplo, se você criou um agente principal chamado research_agent, que não tem nenhuma ferramenta configurada e conectou um agente chamado stock_price_bot, tente um prompt como:

   "Qual é o preço atual das ações de Microsoft?"

   O research_agent deve delegar esta solicitação a stock_price_bot com base na descrição de roteamento que você definiu.

Usar o SDK do .NET

Para permitir que o Agente use um agente conectado, use ConnectedAgentToolDefinition junto com a ID do agente, o nome e uma descrição.

1. Primeiro, precisamos criar o cliente do agente e ler as variáveis de ambiente, que serão usadas nas próximas etapas.

   var projectEndpoint = configuration["ProjectEndpoint"];
   var modelDeploymentName = configuration["ModelDeploymentName"];
   
   PersistentAgentsClient client = new(projectEndpoint, new DefaultAzureCredential());
   

2. Em seguida, criaremos o agente mainAgentprincipal e o agente conectado stockAgent usando o cliente do agente. Esse agente conectado será usado para inicializar o ConnectedAgentToolDefinition.

   PersistentAgent stockAgent = client.Administration.CreateAgent(
           model: modelDeploymentName,
           name: "stock_price_bot",
           instructions: "Your job is to get the stock price of a company. If you don't know the realtime stock price, return the last known stock price."
           // tools: [...] tools that would be used to get stock prices
       );
   ConnectedAgentToolDefinition connectedAgentDefinition = new(new ConnectedAgentDetails(stockAgent.Id, stockAgent.Name, "Gets the stock price of a company"));
   
   PersistentAgent mainAgent = client.Administration.CreateAgent(
           model: modelDeploymentName,
           name: "stock_price_bot",
           instructions: "Your job is to get the stock price of a company, using the available tools.",
           tools: [connectedAgentDefinition]
       );
   
   
   

3. Agora, criaremos o thread, adicionaremos a mensagem, contendo uma pergunta para o agente e iniciaremos a execução.

   PersistentAgentThread thread = client.Threads.CreateThread();
   
   // Create message to thread
   PersistentThreadMessage message = client.Messages.CreateMessage(
       thread.Id,
       MessageRole.User,
       "What is the stock price of Microsoft?");
   
   // Run the agent
   ThreadRun run = client.Runs.CreateRun(thread, agent);
   do
   {
       Thread.Sleep(TimeSpan.FromMilliseconds(500));
       run = client.Runs.GetRun(thread.Id, run.Id);
   }
   while (run.Status == RunStatus.Queued
       || run.Status == RunStatus.InProgress);
   
   // Confirm that the run completed successfully
   if (run.Status != RunStatus.Completed)
   {
       throw new Exception("Run did not complete successfully, error: " + run.LastError?.Message);
   }
   

4. Imprima as mensagens do agente no console em ordem cronológica.

   Pageable<PersistentThreadMessage> messages = client.Messages.GetMessages(
       threadId: thread.Id,
       order: ListSortOrder.Ascending
   );
   
   foreach (PersistentThreadMessage threadMessage in messages)
   {
       Console.Write($"{threadMessage.CreatedAt:yyyy-MM-dd HH:mm:ss} - {threadMessage.Role,10}: ");
       foreach (MessageContent contentItem in threadMessage.ContentItems)
       {
           if (contentItem is MessageTextContent textItem)
           {
               string response = textItem.Text;
               if (textItem.Annotations != null)
               {
                   foreach (MessageTextAnnotation annotation in textItem.Annotations)
                   {
                       if (annotation is MessageTextUriCitationAnnotation urlAnnotation)
                       {
                           response = response.Replace(urlAnnotation.Text, $" [{urlAnnotation.UriCitation.Title}]({urlAnnotation.UriCitation.Uri})");
                       }
                   }
               }
               Console.Write($"Agent response: {response}");
           }
           else if (contentItem is MessageImageFileContent imageFileItem)
           {
               Console.Write($"<image from ID: {imageFileItem.FileId}");
           }
           Console.WriteLine();
       }
   }
   

5. Limpe os recursos excluindo thread e agente.

   agentClient.DeleteThread(threadId: thread.Id);
   agentClient.DeleteAgent(agentId: agent.Id);
   agentClient.DeleteAgent(agentId: connectedAgent.Id);
   

Criando uma configuração de vários agentes

Para criar uma configuração de vários agentes, siga estas etapas:

1. Inicialize o objeto cliente.

   import os
   from azure.ai.projects import AIProjectClient
   from azure.ai.agents.models import ConnectedAgentTool, MessageRole
   from azure.identity import DefaultAzureCredential
   
   
   project_client = AIProjectClient(
   endpoint=os.environ["PROJECT_ENDPOINT"],
   credential=DefaultAzureCredential(),
   )
   

2. Crie um agente que será conectado a um agente "principal".

   stock_price_agent = project_client.agents.create_agent(
       model=os.environ["MODEL_DEPLOYMENT_NAME"],
       name="stock_price_bot",
       instructions="Your job is to get the stock price of a company. If you don't know the realtime stock price, return the last known stock price.",
       #tools=... # tools to help the agent get stock prices
   )
   

3. Inicializar a ferramenta com a identificação, o nome e a descrição do agente conectado.

   connected_agent = ConnectedAgentTool(
       id=stock_price_agent.id, name=stock_price_agent.name, description="Gets the stock price of a company"
   )
   

4. Crie o agente principal que usará o agente conectado.

   agent = project_client.agents.create_agent(
       model=os.environ["MODEL_DEPLOYMENT_NAME"],
       name="my-agent",
       instructions="You are a helpful agent, and use the available tools to get stock prices.",
       tools=connected_agent.definitions,
   )
   
   print(f"Created agent, ID: {agent.id}")
   

5. Crie um thread e adicione uma mensagem a ele.

   thread = project_client.agents.threads.create()
   print(f"Created thread, ID: {thread.id}")
   
   # Create message to thread
   message = project_client.agents.messages.create(
       thread_id=thread.id,
       role=MessageRole.USER,
       content="What is the stock price of Microsoft?",
   )
   print(f"Created message, ID: {message.id}")
   
   

6. Crie uma tarefa e aguarde até que ela seja concluída.

   
   # Create and process Agent run in thread with tools
   run = project_client.agents.runs.create_and_process(thread_id=thread.id, agent_id=agent.id)
   print(f"Run finished with status: {run.status}")
   
   if run.status == "failed":
       print(f"Run failed: {run.last_error}")
   
   # Delete the Agent when done
   project_client.agents.delete_agent(agent.id)
   print("Deleted agent")
   
   # Delete the connected Agent when done
   project_client.agents.delete_agent(stock_price_agent.id)
   print("Deleted connected agent")
   

7. Imprima a resposta do agente. O agente principal compilará as respostas dos agentes conectados e fornecerá a resposta. as respostas do agente conectado só são visíveis para o agente principal e não para o usuário final.

   # Print the Agent's response message with optional citation
   response_message = project_client.agents.messages.get_last_message_by_role(
       thread_id=thread.id, 
       role=MessageRole.AGENT
   )
   if response_message:
       for text_message in response_message.text_messages:
           print(f"Agent response: {text_message.text.value}")
       for annotation in response_message.url_citation_annotations:
           print(f"URL Citation: [{annotation.url_citation.title}]({annotation.url_citation.url})")