Editar o seu agente do Microsoft Copilot Studio no Microsoft Visual Studio Code

Ao clonar o agente do Microsoft Copilot Studio para o seu computador local, pode editar os seus componentes utilizando as funcionalidades de edição de texto do Microsoft Visual Studio Code. A extensão do Copilot Studio inclui IntelliSense, validação e suporte à linguagem YAML, tornando a edição eficiente e sem erros.

Estrutura de ficheiros do agente

Compreender a estrutura dos ficheiros é 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 principal do agente

Funcionalidades do IntelliSense

À medida que escreve, as sugestões são apresentadas e os valores inválidos são realçados. Estas sugestões mudam consoante o nível de nó em que está.

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

Ver problemas

Pode ver problemas com ficheiros no painel de Problemas no Visual Studio Code. Além disso, ao abrir um ficheiro, pode ver um sublinhado vermelho a identificar problemas.

Painel de problemas

1. Utilize Ctrl+Shift+M para abrir o painel Problemas (ou aceda a Ver>Problemas).

2. Veja todos os erros e avisos.

3. Selecione qualquer problema para saltar para a localização.

Trabalhar com alterações

Quando uma alteração é feita e guardada, é apresentada numa cor diferente no Visual Studio, para que possa ser facilmente identificada.

Editar componentes do agente

Tópicos

Os Tópicos definem fluxos de conversação e diálogos. São um tipo de AdaptiveDialog.

Pode utilizar o GitHub Copilot ou outros agentes para ajudar a criar novos componentes ou, se preferir, escrever os seus próprios tópicos.

Estrutura do ficheiro de tópico

Eis um exemplo de um tópico de saudação simples:

# 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}.

Funcionalidades de tópico avançadas

Pode utilizar outros componentes em tópicos, tais 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 utilizando o 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 Adaptativos

Ferramentas

As ferramentas definem ações que o agente pode executar. Pode vê-las na área de Ferramentas da IU do Agente do Copilot Studio.

As Ferramentas podem incluir:

• Pedidos
• Fluxos de trabalho (Fluxos do Power Automate)
• Ferramentas CUA
• Conectores personalizados
• APIs REST
• Conectores de MCP

As ferramentas são apresentadas na extensão dentro da pasta /actions do agente, mas também podem ser apresentadas noutras pastas com metadados adicionais. Por exemplo, Fluxos de trabalho e Acionadores têm as suas próprias pastas e ficheiros JSON.

Editar acionadores

Os Acionadores definem quando os tópicos ou as ações são ativados. Pode defini-los como tipos baseados em agendamento, eventos ou condições. Os acionadores normalmente referem-se a um fluxo de trabalho.

kind: ExternalTriggerConfiguration
externalTriggerSource:
  kind: WorkflowExternalTrigger

Gerir ficheiros de conhecimento remotos

Se carregar documentos utilizando a funcionalidade de carregamento no Copilot Studio, estes documentos ficam disponíveis para transferir ao clicar no nome na janela Ficheiros de Conhecimento Remotos. Os documentos não são transferidos automaticamente e têm de ser escolhidos para transferir na janela. É apresentada uma notificação quando a transferência é concluída com êxito.

Se quiser carregar novos ficheiros, pode colocá-los na pasta knowledge/files na definição do agente. Quando as alterações forem aplicadas, são carregadas através da funcionalidade de carregamento de conteúdos do agente.

Melhores práticas

Convenções de nomenclatura

Ficheiros:

• Utilizar minúsculas e separação com hífen: create-ticket.tool.yaml
• Seja descritivo: product-pricing-faq.yaml não faq.yaml
• Utilize o sufixo de tipo: .topic.yaml, .tool.yaml, .trigger.yaml

IDs e variáveis:

• Utilize camelCase: userOrderNumber, productDetails
• Seja descritivo: checkPaymentStatus não check1
• Evite abreviaturas: 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

Passos seguintes

Agora que já compreende o que é a edição:

• Saiba mais sobre sincronização.