A Assistant API oferece suporte a chamadas de função. Esse recurso permite que um agente invoque automaticamente funções externas para executar tarefas, como traduzir textos. Este tópico usa um exemplo simples de "Agente de Tradução" para ajudar você a compreender rapidamente os fundamentos das chamadas de função.
Início rápido
Neste exemplo, você criará um agente de tradução e uma função chamada translate_text que o agente poderá invocar. Em seguida, solicite ao agente que traduza "Hello world" para chinês.
Antes de começar
Instale as bibliotecas de dependência necessárias, como requests e dashscope, executando o seguinte comando:
Etapa 1: Crie a função "translate_text"
Primeiro, crie uma função de tradução simples. Para fins de demonstração, esta função usa uma tabela de tradução predefinida.
- Recurso de tradução: Simula uma funcionalidade de tradução usando uma tabela predefinida que permite a conversão entre vários idiomas.
- Tratamento de erros: A função possui um mecanismo básico de tratamento de exceções para garantir respostas adequadas em qualquer situação.
translate_text definida para fornecer serviços de tradução.
Etapa 2: Descreva a função "translate_text"
Descreva a função translate_text para o agente. O agente usa essa descrição para chamar a função corretamente.
- name: O nome da função é
translate_text. O agente usa esse identificador para realizar a chamada. - description: Descrição da ferramenta que auxilia o agente a compreender sua finalidade.
- parameters: Define os parâmetros da função, incluindo o texto a ser traduzido e o idioma de destino.
Etapa 3: Crie um agente
Crie uma instância de Assistant. Essa instância representa o agente que usará a ferramenta de tradução definida anteriormente.
- model: Especifica o modelo a ser usado. Este exemplo emprega o
qwen-plus, compatível com compreensão de linguagem e processamento de tarefas. - name: Nome do agente. Defina o valor como "Translation Assistant".
- description: Descreve o objetivo do agente: auxiliar os usuários na tradução de textos.
- tools: Registra a
translation_tooldefinida previamente, habilitando o agente a invocá-la.
Etapa 4: Crie um thread de conversa e interaja com o agente
Crie um novo thread de conversa, adicione uma mensagem de usuário e execute o agente para processar a consulta.
- Threads.create(): Inicia um novo thread de conversa para as mensagens subsequentes.
- Messages.create(): Adiciona uma mensagem do usuário ao thread. Neste caso, solicita-se a tradução de "Hello world" para chinês.
- Runs.create(): Aciona o início do processamento da mensagem do usuário pelo agente.
- Runs.wait(): Aguarda a conclusão do processamento pelo agente.
Etapa 5: Trate a chamada de função e retorne o resultado
Se o agente precisar invocar uma ferramenta durante o processamento, a função translate_text será chamada e o resultado retornado.
- Verificação de chamada de função: Se o agente precisar chamar uma função, seu código verifica se a função solicitada é
translate_texte executa a tradução usando a função definida anteriormente. - Envio do resultado: Envie o resultado da tradução para o agente usando
Runs.submit_tool_outputse aguarde a próxima resposta.
Etapa 6:Obtenha a resposta do agente
Após a conclusão do processamento, recupere a resposta do agente no thread de conversa e exiba-a para o usuário.
Resumo
Ao seguir estas etapas, você criou com sucesso um agente capaz de lidar com solicitações de tradução dos usuários e usar uma função de tradução para converter texto. A Assistant API simplifica e torna eficiente a construção de agentes complexos e orientados a tarefas.
Conforme necessário, estenda os recursos do agente adicionando mais ferramentas ou modificando as instruções de comportamento.
Gere rapidamente descrições para funções de negócio
No exemplo de Início Rápido, é preciso descrever a função "translate_text" para o agente. Esse processo pode ser tedioso. Por isso, fornecemos uma função de conversão simples para ajudar você a descrever rapidamente suas funções de negócio.
translate_text do Início Rápido:
translate_text é convertida automaticamente para:
Use saída em streaming
Ao usar saída em streaming, modifique a lógica do código na Etapa 5: Trate a chamada de função e retorne o resultado. Isso ocorre porque o objeto Runs agora retorna um fluxo de eventos do Assistant.
Quando o Assistant decide chamar uma função, o objeto Runs retorna o evento thread.run.requires_action e os parâmetros de entrada data.required_action.submit_tool_outputs.tool_calls fornecidos pelo Large Language Model (LLM). Nesse momento, envie a saída da função.
Observe que também é necessário ativar a saída em streaming ao enviar a saída da função com run = Runs.submit_tool_outputs.
while extra fora do loop for que processa o fluxo de eventos. Isso acontece porque o sistema gera um novo objeto Runs quando você envia a saída da função. O loop while ajuda a rastrear automaticamente o fluxo de eventos mais recente, permitindo que o Assistant continue gerando uma resposta após receber o resultado da chamada de função.