Edite seu agente do Microsoft Copilot Studio no Microsoft Visual Studio Code

Ao clonar o agente Microsoft Copilot Studio para sua máquina local, você pode editar seus componentes usando as ferramentas de edição de texto do Microsoft Visual Studio Code. A extensão Copilot Studio oferece suporte a IntelliSense, validação e à linguagem YAML para tornar a edição eficiente e livre de erros.

Estrutura de arquivos do agente

Compreender a estrutura dos arquivos é 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 de 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 facilitar atualizações rápidas

Exibir problemas

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

Painel de Problemas

1. Use Ctrl+Shift+M para abrir o painel Problemas (ou vá até Exibir>Problemas).

2. Veja todos os erros e avisos.

3. Selecione qualquer problema para ir ao local.

Trabalhar com alterações

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

Editar componentes do agente

Tópicos

Tópicos definem fluxos conversacionais e diálogos. Eles são um tipo de AdaptiveDialog.

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

Estrutura do arquivo de tópico

Aqui está um exemplo de um tópico simples de saudação:

# 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 de tópico avançados

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

Ferramentas

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

As ferramentas podem incluir:

• Prompts
• Workflows (fluxos do Power Automate)
• Ferramentas do CUA
• Conectores personalizados
• APIs REST
• Conectores de MCP

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

Editar gatilhos

Gatilhos definem quando tópicos ou ações são acionados. 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ê enviar documentos usando o recurso de upload no Copilot Studio, esses documentos estarão disponíveis para download clicando no nome na janela Arquivos de Conhecimento Remoto. 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(a): 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(a): checkPaymentStatus não check1
• Evite abreviações: customerEmail não custEmail

Comentários

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 a edição:

• Aprenda Sobre Sincronização.