Editar seu agente de Microsoft Copilot Studio no Microsoft Visual Studio Code

Ao clonar o agente de Microsoft Copilot Studio em seu computador local, você pode editar seus componentes usando os recursos de edição de texto do Microsoft Visual Studio Code. A extensão Copilot Studio fornece suporte a linguagem IntelliSense, validação e YAML para tornar a edição eficiente e sem erros.

Estrutura do arquivo do agente

Compreender a estrutura do arquivo é fundamental para uma edição eficiente.

my-agent/
├── actions                   # Connectors
│   ├── DevOpsAction.mcs.yml  
│   └── GetItems.mcs.yml      
├── knowledge/files                # Knowledge sources
│   ├── source1.yaml
│   └── source2.yaml
├── topics/                   # Conversation topics
│   ├── greeting.mcs.yaml
│   ├── help.mcs.yaml
│   └── escalate.mcs.yaml
├── workflows/                    # Agent tools and actions
│   └── GetDevOpsItems
│       ├── metadata.yaml
│       └── workflow.json
│   └── GetMeetings
│       ├── metadata.yaml
│       └── workflow.json
├── trigger/                 # Event triggers
│   └── welcometrigger.mcs.yaml
├── agent.mcs.yaml                # Main agent definition
├── icon.png                      # Icon used for the agent, visible in test panel and in supported channels
├── settings.mcs.yml              # Configuration settings for the agent
└── connectioreferences.mcs.yml   # Connection References used by Connectors and other actions

Editar a configuração do agente principal

Recursos do IntelliSense

Enquanto você digita, sugestões são exibidas e valores inválidos são destacados. Essas sugestões mudam conforme o nível de nó em que você está.

• Use Ctrl+Space para receber sugestões baseadas no nível do nó.
• Use Ctrl+F para buscar nomes de variáveis e outras informações em todo o seu agente para atualizar rapidamente

Ver problemas

Você pode exibir problemas com arquivos no painel Problems no Visual Studio Code. Além disso, ao abrir um arquivo, pode ver um sublinhado vermelho identificando problemas.

Painel de problemas

1. Use Ctrl+Shift+M para abrir o painel de Problemas (ou vá em Ver>Problemas).

2. Veja todos os erros e avisos.

3. Selecione qualquer problema para ir ao local.

Trabalhando com mudanças

Quando uma alteração é feita e salva, ela aparece em uma cor diferente em Visual Studio para que você possa identificá-la facilmente.

Componentes do agente de edição

Topics

Os tópicos definem os fluxos de conversa e os diálogos. Eles são um tipo de AdaptiveDialog.

Você pode usar GitHub Copilot ou outros agentes para ajudar a criar componentes new ou, se desejar, escrever seus próprios tópicos.

Estrutura do arquivo tópico

Aqui está um exemplo de um tópico simples para saudações:

# This is the name of the topic that will appear in the 'topics' list in Copilot Studio
kind: AdaptiveDialog
beginDialog:
  kind: OnConversationStart
  id: main
  actions:
    - kind: SendActivity
      id: sendMessage_M0LuhV
      activity:
        text:
          - Hello, I'm {System.Bot.Name}. How can I help?
        speak:
          - Hello and thank you for calling {System.Bot.Name}.

Recursos avançados de tópicos

Você pode usar outros componentes em tópicos como:

• Entidades:

              - kind: Question
                id: question_1
                alwaysPrompt: true
                variable: init:Topic.Continue
                prompt: Can I help with anything else?
                entity: BooleanPrebuiltEntity
  

• Variáveis:

    actions:
      - kind: Question
        id: 41d42054-d4cb-4e90-b922-2b16b37fe379
        conversationOutcome: ResolvedImplied
        alwaysPrompt: true
        variable: init:Topic.SurveyResponse
        prompt: Did that answer your question?
        entity: BooleanPrebuiltEntity
  

• Condições usando Power Fx:

              - kind: ConditionGroup
                id: condition-1
                conditions:
                  - id: condition-1-item-0
                    condition: =Topic.Continue = true
                    actions:
                      - kind: SendActivity
                        id: sendMessage_4eOE6h
                        activity: Go ahead. I'm listening.
  

• Outros nós, por exemplo, nós HTTP

• Cartões Adaptáveis

Tools

Ferramentas definem ações que seu agente pode realizar. Você pode vê-los na área Tools da interface do usuário do Copilot Studio Agent.

As ferramentas podem incluir:

• Solicitações
• Fluxos de trabalho (processos do Power Automate)
• Ferramentas CUA
• Conectores personalizados
• APIs REST
• Conectores MCP

Ferramentas aparecem dentro da extensão, na pasta de /actions um agente, mas também podem aparecer em outras pastas com metadados extras. Por exemplo, Workflows e Triggers têm suas próprias pastas e JSON.

Gatilhos de edição

Gatilhos definem quando tópicos ou ações são ativados. Você pode defini-los como horários, eventos ou tipos condicionais. Gatilhos normalmente fazem referência a um fluxo de trabalho.

kind: ExternalTriggerConfiguration
externalTriggerSource:
  kind: WorkflowExternalTrigger

Gerenciar arquivos de conhecimento remotos

Se você fizer upload de documentos usando a ferramenta de upload no Copilot Studio, esses documentos estarão disponíveis para download clicando no nome na janela Arquivos de Conhecimento Remotos. Os documentos não são baixados automaticamente e devem ser selecionados para download na janela. Você recebe uma notificação quando o download é bem-sucedido.

Se quiser enviar novos arquivos, pode colocá-los na knowledge/files pasta da definição do agente. Quando você aplica essas mudanças, elas são enviadas pelo recurso de upload de conteúdo do agente.

Práticas Recomendadas

Convenções de nomenclatura

Arquivos:

• Usar kebab-case: create-ticket.tool.yaml
• Seja descritivo: product-pricing-faq.yaml não faq.yaml
• Use o sufixo do tipo: .topic.yaml, .tool.yaml, .trigger.yaml

IDs e variáveis:

• Usar camelCase: userOrderNumber, productDetails
• Seja descritivo: checkPaymentStatus não check1
• Evite abreviações: customerEmail não custEmail

Comments

Para explicar lógica complexa, adicione comentários:

nodes:
  # Check if user is within business hours and eligible for live support
  # Business hours: 9 AM - 5 PM EST, Monday-Friday
  # Eligibility: Premium tier customers only
  - id: check-live-support-availability
    type: condition

Próximas etapas

Agora que você entende como é editar:

• Aprenda sobre sincronização.