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

Quando clona o agente Microsoft Copilot Studio para a sua máquina local, pode editar os seus componentes utilizando as funcionalidades de edição de texto do Microsoft Visual Studio Code. A extensão Copilot Studio oferece suporte para IntelliSense, validação e linguagem YAML para tornar a edição eficiente e sem erros.

Estrutura do ficheiro 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 do agente principal

Funcionalidades do IntelliSense

À medida que escreves, as sugestões são apresentadas e os valores inválidos são destacados. 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ó.
• Use Ctrl+F para pesquisar nomes de variáveis e outras informações em todo o seu agente para atualizar rapidamente

Problemas de visualização

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

Painel de problemas

1. Use Ctrl+Shift+M para abrir o painel de Problemas (ou ir a Ver>Problemas).

2. Veja todos os erros e avisos.

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

Trabalhar com mudanças

Quando uma alteração é feita e guardada, ela aparece numa cor diferente no Visual Studio para que a possas identificar facilmente.

Componentes do agente de edição

Topics

Os temas definem os fluxos de conversa e os diálogos. São um tipo de AdaptiveDialog.

Pode usar GitHub Copilot ou outros agentes para ajudar a construir componentes novo ou, se quiser, escrever os seus próprios tópicos.

Estrutura do ficheiro de tópicos

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

Funcionalidades avançadas de tópicos

Pode utilizar 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 Adaptativos

Tools

As ferramentas definem ações que o seu agente pode realizar. Podes vê-los na área Tools da interface do Copilot Studio Agent.

As ferramentas podem incluir:

• Sugerências
• Fluxos de trabalho (fluxos do Power Automate)
• Ferramentas CUA
• Conectores personalizados
• APIs REST
• Conectores MCP

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

Gatilhos de edição

Os gatilhos definem quando os tópicos ou ações são ativados. Pode defini-los como horários, eventos ou tipos condicionais. Os gatilhos normalmente referem-se a um fluxo de trabalho.

kind: ExternalTriggerConfiguration
externalTriggerSource:
  kind: WorkflowExternalTrigger

Gerir ficheiros de conhecimento remotos

Se carregar documentos usando a funcionalidade de upload no Copilot Studio, estes documentos estão disponíveis para download clicando no nome na janela Remote Knowledge Files. Os documentos não são descarregados automaticamente e devem ser selecionados para download na janela. Vês uma notificação quando o download é bem-sucedido.

Se quiseres carregar novos ficheiros, podes colocá-los na knowledge/files pasta na definição do agente. Quando aplicas essas alterações, elas são carregadas através da funcionalidade de upload 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
• Use o sufixo do 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

Comments

Para explicar a 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óximos passos

Agora que percebes o que é editar:

• Aprenda sobre sincronização.