Habilidades dos assistentes#

Uma habilidade armazena instruções e arquivos para uma tarefa recorrente: scripts Python, modelos do Word, PDFs, planilhas e materiais de referência. Por exemplo, um assistente usa o mesmo modelo de relatório e o mesmo script de cálculo a cada mês.

Acesso e preparação#

A seção de habilidades está disponível após a instalação de uma versão do Sherpa AI Server com o catálogo de habilidades e a aplicação das migrações. O recurso não exige configuração adicional no servidor. A permissão de leitura da seção de assistentes permite consultar as habilidades acessíveis e baixar arquivos. A permissão de edição permite criar habilidades, atribuí-las a assistentes e editar as próprias habilidades. O modo "All agents" exige entrar em nome da conta. Você pode vincular uma habilidade aos assistentes das pastas de objetos às quais tem acesso.

Somente scripts Python são aceitos. O administrador do sistema instala as bibliotecas no ambiente do interpretador. As bibliotecas instaladas são verificadas pela API do interpretador. Se faltar uma biblioteca necessária, a habilidade exibe um aviso e não é executada. Se a verificação estiver indisponível ou o pacote importado não incluir uma lista de bibliotecas, o status informa que a compatibilidade não foi verificada. Uma lista explicitamente vazia significa que nenhuma biblioteca externa é necessária.

Usuários com acesso somente de leitura podem abrir "Assistentes" e clicar no botão "Habilidades" no cartão do assistente. Na janela "Habilidades", clique em "Visualizar" ao lado de uma habilidade. As instruções são abertas somente para leitura. Clique em "Baixar" para salvar um arquivo.

Cartão do assistente com o botão para consultar habilidades, interface em russo

Cartão do assistente: botão Habilidades (interface em russo)

Exemplo: para verificar quais dados o assistente usa no relatório de vendas, abra as habilidades dele, visualize a habilidade de relatório de vendas e baixe data/sales.csv.

Janela Habilidades com instruções e um arquivo para um usuário com acesso de leitura, interface em russo

Janela Habilidades: consulta de instruções e download de um arquivo (interface em russo)

A verificação de compatibilidade usa as bibliotecas selecionadas nas configurações do assistente. Se uma biblioteca necessária estiver instalada, mas não selecionada, um usuário com permissão para editar o assistente deve ativá-la em "Alterar bibliotecas do interpretador".

Criação de uma habilidade#

Crie uma habilidade no catálogo para guardar instruções e arquivos reutilizáveis.

Pesquise no catálogo de habilidades por nome, nome do pacote ou descrição. Os cabeçalhos têm filtros por nome, nome do pacote, descrição e atribuição.

Catálogo de habilidades com os botões de criação e importação, interface em russo

Catálogo de habilidades com os botões de criação e importação, interface em russo

  1. Abra "Skills" no menu de navegação.
  2. Clique no botão para criar uma habilidade.

Campos obrigatórios

  • Informe um nome descritivo, como "Relatório mensal".
  • No nome do pacote, informe monthly-report. Esse nome seleciona a habilidade em uma mensagem.
  • No campo que descreve quando utilizá-la, informe: "Preparar um relatório com um modelo do Word e uma planilha".
  • Nas instruções, indique as ações, os caminhos dos arquivos e o resultado esperado. Por exemplo: "Use assets/template.docx, data.xlsx, scripts/process.py. Salve o resultado em /sandbox/monthly-report.docx".

Campos opcionais

  • Nas bibliotecas Python, informe os nomes dos pacotes separados por vírgulas: python-docx, openpyxl. Deixe este campo vazio se os scripts não precisarem de pacotes externos.

Salve a habilidade.

Exemplo: use os valores acima para criar uma habilidade de relatório mensal. Depois de salvar, monthly-report aparecerá no catálogo.

Janela de criação com as configurações do relatório mensal (interface em russo)

Janela de criação com as configurações do relatório mensal (interface em russo)

Depois de salvar, envie o modelo, a planilha e o script no editor, usando os caminhos indicados nas instruções. O envio de pastas preserva os caminhos internos. Para um arquivo individual, use o campo opcional de caminho do recurso. Os arquivos são salvos imediatamente, separadamente do texto das instruções.

Importação de um pacote#

A importação de um ZIP adiciona instruções e recursos ao catálogo em uma etapa. Na seção de habilidades, clique em "Import ZIP" e selecione um arquivo como monthly-report.zip. Ele deve conter um único SKILL.md na raiz ou em uma pasta comum. Os caminhos dos recursos são relativos à pasta que contém SKILL.md. O exemplo abaixo mostra o conteúdo de SKILL.md.

---
name: monthly-report
description: Prepare a monthly report using a Word template and a spreadsheet.
metadata:
  title: Monthly report
  python_packages:
    - python-docx
    - openpyxl
---
Read assets/template.docx and data.xlsx. Run scripts/process.py.
Save the result to /sandbox/monthly-report.docx and print that path.

Os scripts devem ficar em scripts/ e ter a extensão .py. O limite é de 100 arquivos e 20 MiB de dados descompactados. As entradas de diretório não contam como arquivos. As instruções têm limite de 20.000 bytes. Links simbólicos, caminhos fora da pasta e conflitos entre arquivos e diretórios são rejeitados.

Exemplo: inclua em monthly-report.zip as instruções em SKILL.md, o modelo assets/template.docx, os dados de entrada data.xlsx e o script scripts/process.py. Após importar o arquivo, localize monthly-report no catálogo.

Catálogo de habilidades com o pacote monthly-report importado (interface em russo)

Catálogo de habilidades com o pacote monthly-report importado (interface em russo)

Conexão e edição#

Vários assistentes podem usar a mesma habilidade do catálogo. As alterações nas instruções e nos arquivos valem para todos os assistentes com a habilidade atribuída.

No catálogo, clique em "Configure" na linha da habilidade. No modo de agentes selecionados, as alterações nas caixas de seleção dos assistentes entram em vigor imediatamente. Para atribuir a habilidade a todos os assistentes atuais e futuros da conta, escolha o modo para todos os agentes e salve a habilidade. Ao retornar ao modo de agentes selecionados, as atribuições anteriores voltam a valer. Uma habilidade de toda a conta não pode ser desativada nem desvinculada nas configurações de um assistente.

Exemplo: para que o assistente de suporte possa resumir as solicitações dos clientes, selecione-o na janela de configuração da habilidade «Resumo de solicitações». A habilidade ficará disponível para esse assistente.

Janela de configuração com Resumo de solicitações atribuída ao assistente de suporte (interface em russo)

Janela de configuração com Resumo de solicitações atribuída ao assistente de suporte (interface em russo)

Para conectar uma habilidade nas configurações do assistente, abra a aba "Skills" e clique em "Connect skill". Pesquise pelo título ou pela finalidade e clique em "Attach" ao lado da habilidade. A habilidade conectada aparece imediatamente na lista do assistente. Os rótulos e as capturas a seguir correspondem à interface em inglês.

Aba Skills com a pesquisa de Monthly report no catálogo, interface em inglês

Configurações do assistente, aba Skills, conexão de Monthly report, interface em inglês

Cada habilidade conectada tem os seguintes controles:

  • O interruptor "Enabled" altera a disponibilidade para o assistente selecionado. Desativá-lo preserva a atribuição.
  • "View" abre as instruções e os arquivos em uma janela separada. Para editar o conteúdo, abra o catálogo de habilidades.
  • "Actions" contém "Detach". Essa opção remove a atribuição e mantém a habilidade no catálogo.
  • "All agents" identifica uma atribuição para toda a conta. Altere essa atribuição no catálogo de habilidades.

Exemplo: Support summary está ativada para o assistente de suporte, enquanto Document check está atribuída a todos os agentes.

Configurações do assistente, aba Skills, habilidades conectadas, interface em inglês

Configurações do assistente, aba Skills, habilidades conectadas, interface em inglês

Se outro usuário alterar a habilidade enquanto ela estiver sendo editada, uma mensagem de conflito será exibida. O texto digitado permanece no editor, e o botão "Save skill" fica indisponível. "Refresh" não remove o conflito nem descarta o rascunho.

  1. Antes de reabrir a habilidade, copie o texto necessário do editor para um documento separado.
  2. Clique em "Reopen skill" na mensagem de conflito. O editor carrega a versão mais recente da habilidade salva no servidor. As alterações locais não salvas são descartadas.
  3. Compare a versão atual com o texto copiado, reaplique as alterações necessárias e clique em "Save skill".

Reabrir a habilidade não desfaz as alterações já salvas no servidor nem exclui os arquivos da habilidade.

Uso no chat#

As habilidades conectadas estão disponíveis nos chats com o assistente nos modos "Agent" e "Code interpreter". Por padrão, o assistente escolhe uma habilidade adequada com base na descrição da tarefa. Os rótulos e as capturas a seguir correspondem à interface em inglês.

  1. Abra um chat com o assistente.
  2. Selecione o modo "Agent" ou "Code interpreter".
  3. Digite e envie uma solicitação, como "Prepare a monthly report using the saved template".
Campo de entrada do chat no modo Agent com seleção automática de habilidades, interface em inglês

Chat, campo de entrada no modo Agent, seleção automática, interface em inglês

Para escolher uma habilidade manualmente, abra "Chat tools" no canto inferior esquerdo do campo e escolha "Skills". Na janela "Choose an available skill", clique no título da habilidade. O nome aparece como uma etiqueta compacta na barra de ferramentas. "Clear skill selection" na etiqueta restaura a seleção automática e preserva o rascunho. Escolher ou remover uma habilidade não altera o modo do chat.

Chat, janela Choose an available skill, interface em inglês

Chat, janela Choose an available skill, interface em inglês

Exemplo: escolha "Monthly report" em "Skills" e envie a solicitação da etapa 3. O assistente recebe as instruções para preparar o relatório usando o modelo.

Campo de entrada no modo Agent com a etiqueta Monthly report ao lado do menu de ferramentas, interface em inglês

Chat, campo de entrada no modo Agent, Monthly report selecionada, interface em inglês

A seleção manual adiciona /monthly-report ao início da mensagem. Na seleção automática, o modelo usa as descrições das habilidades. As instruções completas são carregadas quando uma habilidade é selecionada. A qualidade da seleção depende do modelo e da descrição de quando usar a habilidade.

Os arquivos da habilidade são somente leitura no interpretador durante a execução atual. Salve os resultados em /sandbox/. O documento gerado aparece na mensagem do chat para download. Ao preparar o catálogo, o nome de cada habilidade é vinculado ao seu GUID durante toda a execução. Renomear a habilidade ou atribuir seu nome anterior a outra habilidade não a substitui em um catálogo existente. As instruções, os arquivos e os requisitos de bibliotecas são fixados no primeiro carregamento bem-sucedido. Alterações anteriores a esse carregamento são incluídas. Novos carregamentos na mesma execução usam a versão fixada. Alterações posteriores ao primeiro carregamento ficam disponíveis em uma nova execução. Habilidades desativadas, vínculos desconectados e acesso revogado são verificados novamente. Quando a execução termina, falha ou é cancelada, sua cópia dos arquivos da habilidade é removida de forma assíncrona. Se o interpretador estiver temporariamente indisponível, a limpeza continua após a conexão ser restabelecida. Se as tentativas falharem, o administrador do sistema verifica o serviço e tenta a limpeza novamente. A limpeza dos arquivos do chat preserva as cópias das execuções ativas. Os documentos gerados continuam disponíveis para download no chat.

Se o catálogo e as instruções excederem o orçamento de contexto do modelo, reduza as descrições ou instruções, desconecte habilidades desnecessárias ou selecione um modelo com contexto maior. Solicite ao administrador do sistema as bibliotecas ausentes. As habilidades não instalam bibliotecas automaticamente.

Corrija nomes de bibliotecas ou restrições de versão inválidos no campo de requisitos de bibliotecas Python. Um requisito não pode conter uma quebra de linha. Um erro de formato não significa que outra biblioteca precise ser instalada.