Modificare l'agente Microsoft Copilot Studio in Microsoft Visual Studio Code

Quando cloni il tuo agente Microsoft Copilot Studio in un computer locale, puoi modificarne i componenti usando le funzionalità di modifica del testo disponibili in Microsoft Visual Studio Code. L'estensione Copilot Studio offre supporto per IntelliSense, la convalida e il linguaggio YAML per rendere la modifica efficiente e priva di errori.

Struttura dei file dell'agente

Comprendere la struttura dei file è fondamentale per apportare modifiche in modo efficiente.

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

Modificare la configurazione principale dell'agente

Funzionalità di IntelliSense

Mentre digiti, vengono mostrati suggerimenti vengono evidenziati i valori non validi. Questi suggerimenti cambiano a seconda del livello di nodo in cui ti trovi.

• Premi Ctrl+Space per visualizzare suggerimenti basati sul livello di nodo.
• Premi Ctrl+F per cercare nomi di variabili e altre informazioni in tutto l'agente così da aggiornare rapidamente

Visualizzare i problemi

Puoi visualizzare i problemi nei file nel riquadro Problemi in Visual Studio Code. Inoltre, quando apri un file, una sottolineatura rossa ti permette di individuare subito i problemi.

Riquadro Problemi

1. Premi Ctrl+Shift+M per aprire il riquadro Problemi (oppure vai a Visualizza>Problemi).

2. Visualizza tutti gli errori e gli avvisi.

3. Seleziona un problema qualsiasi per passare alla posizione in cui si presenta il problema.

Uso delle modifiche

Le modifiche apportate e salvate appaiono in un colore diverso in Visual Studio, così è più facile individuarle.

Modificare i componenti dell'agente

Argomenti

Gli argomenti definiscono le iterazioni e i flussi delle conversazioni. Sono un tipo di AdaptiveDialog.

Puoi usare GitHub Copilot o altri agenti per aiutarti a creare nuovi componenti o, se vuoi, per scrivere gli argomenti.

Struttura del file tematico

Ecco un esempio di argomento di saluto semplice:

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

Funzionalità di argomento avanzate

Puoi usare altri componenti negli argomenti quali:

• Entità:

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

• Variabili:

    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
  

• Condizioni che usano 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.
  

• Altri nodi, ad esempio, i nodi HTTP

• Schede adattive

Strumenti

Gli strumenti definiscono le azioni che il tuo agente può svolgere. Puoi vederli nell'area Strumenti dell'interfaccia utente dell'agente Copilot Studio.

Gli strumenti possono includere:

• Richieste
• Flussi di lavoro (flussi Power Automate)
• Strumenti CUA
• Connettori personalizzati
• API REST
• Connettori MCP

Gli strumenti compaiono all'interno dell'estensione nella cartella /actions dell'agente, ma possono anche trovarsi in altre cartelle con metadati aggiuntivi. Ad esempio, i flussi di lavoro e i trigger hanno ciascuno una propria cartella e propri file JSON.

Modificare i trigger

I trigger definiscono quando gli argomenti o le azioni si attivano. Puoi impostarli come pianificazioni, eventi o tipi basati su condizioni. I trigger si riferiscono normalmente a un flusso di lavoro.

kind: ExternalTriggerConfiguration
externalTriggerSource:
  kind: WorkflowExternalTrigger

Gestire file di conoscenza remoti

Se carichi documenti utilizzando la funzionalità di caricamento in Copilot Studio, questi documenti sono disponibili per il download facendo clic sul nome nella finestra File di conoscenza remoti. I documenti non vengono scaricati automaticamente. Occorre selezionarli per il download nella finestra. Al termine del download, vedrai una notifica.

Se vuoi caricare nuovi file, puoi inserirli nella cartella knowledge/files nella definizione dell'agente. Quando applichi queste modifiche, vengono caricate tramite la funzionalità di caricamento dei contenuti dell'agente.

Procedure consigliate

Convenzione di denominazione

File:

• Usa il kebab-case: create-ticket.tool.yaml
• Usa descrizioni: product-pricing-faq.yaml non faq.yaml
• Usa il suffisso del tipo: .topic.yaml, .tool.yaml e .trigger.yaml

ID e variabili:

• Usa la notazione Camel: userOrderNumber, productDetails
• Usa descrizioni: checkPaymentStatus non check1
• Evita le abbreviazioni: customerEmail non custEmail

Commenti

Per spiegare una logica complessa, inserisci commenti:

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

Passaggi successivi

Ora che sai come apportare le modifiche:

• Scopri informazioni sulla sincronizzazione.