Προσθήκη και διαχείριση εργαλείων

Η ενότητα Tooling βοηθά τους προγραμματιστές να ανακαλύψουν, να διαμορφώσουν και να ενσωματώσουν διακομιστές Model Context Protocol (MCP) στις ροές εργασίας των παραγόντων AI. Οι διακομιστές MCP παρέχουν εξωτερικές λειτουργίες ως εργαλεία που μπορούν να αξιοποιήσουν οι παράγοντες AI. Για μια επισκόπηση των διαθέσιμων διακομιστών εργαλείων, ανατρέξτε στους διακομιστές εργαλείων του Agent 365.

Παρουσιάζει τη ροή αιτημάτων και απαντήσεων

Επισκόπηση

Η ενοποίηση εργαλείων Agent 365 ακολουθεί αυτήν τη ροή εργασίας:

Διαμόρφωση διακομιστών MCP - Χρησιμοποιήστε το Agent 365 CLI για να ανακαλύψετε και να προσθέσετε διακομιστές MCP
Δημιουργία manifest - Το CLI δημιουργεί ToolingManifest.json στον φάκελο του έργου σας με διαμορφώσεις διακομιστών.
Εφαρμογή δικαιωμάτων στη δομή προγράμματος - Ένας Καθολικός διαχειριστής εκχωρεί δικαιώματα OAuth2 στη δομή προγράμματος του παράγοντα εκτελώντας a365 setup all (για πρώτη ρύθμιση) ή a365 setup permissions mcp (αν η δομή προγράμματος υπάρχει ήδη). Σε κάθε περίπτωση, η εντολή διαβάζει ToolingManifest.json και απαιτεί τη συγκατάθεση διαχειριστή. Αυτό το βήμα είναι πάντα ανεξάρτητο από την προσθήκη διακομιστών στο μανιφέστο.
Ενσωματώστε στον κώδικα - Φορτώστε το μανιφέστο και καταχωρίστε τα εργαλεία με το πρόγραμμα συντονισμού σας.
Κλήση εργαλείων - Ο παράγοντας καλεί εργαλεία κατά την εκτέλεση για την πραγματοποίηση λειτουργιών.

Προαπαιτούμενα στοιχεία

Πριν διαμορφώσετε τους διακομιστές MCP, βεβαιωθείτε ότι έχετε:

Agent 365 CLI εγκατεστημένο και ρυθμισμένο
.NET 8.0 SDK ή νεότερη έκδοση - Λήψη
Προνόμια καθολικού διαχειριστή στον μισθωτή Microsoft 365

Ρύθμιση ταυτότητας παράγοντα

Εάν χρησιμοποιείτε έλεγχο ταυτότητας παράγοντα, ολοκληρώστε τη διαδικασίαεγγραφής παράγοντα για να δημιουργήσετε την ταυτότητα του παράγοντα σας πριν ρυθμίσετε τους διακομιστές MCP. Αυτή η διαδικασία δημιουργεί το αναγνωριστικό παράγοντα Entra και τον χρήστη παράγοντα που επιτρέπει στον παράγοντά σας να πραγματοποιεί έλεγχο ταυτότητας και να έχει πρόσβαση στα εργαλεία MCP.

Ρύθμιση ελέγχου ταυτότητας OBO

Εάν χρησιμοποιείτε έλεγχο ταυτότητας On-Behalf-Of (OBO) αντί για έλεγχο ταυτότητας παράγοντα, ο παράγοντάς σας μπορεί να έχει πρόσβαση στα εργαλεία MCP χρησιμοποιώντας δικαιώματα χρήστη με ανάθεση χωρίς ταυτότητα χρήστη παράγοντα. Στη ροή OBO, ο παράγοντας ανταλλάσσει το διακριτικό ανάθεσης του χρήστη για να εκτελέσει ενέργειες για λογαριασμό του χρήστη.

Για περισσότερες πληροφορίες σχετικά με τον τρόπο λειτουργίας της ροής OBO, δείτε τις Ροές ελέγχου ταυτότητας. Για ένα πλήρες παράδειγμα υλοποίησης, ανατρέξτε στο δείγμα εξουσιοδότησης OBO στο SDK παραγόντων Microsoft 365.

Ρύθμιση παραμέτρων κύριας υπηρεσίας

Εκτελέστε αυτό το σενάριο μίας χρήσης για να δημιουργήσετε το service principal για τα Agent 365 Tools στον μισθωτή σας.

Σημαντικό

Αυτή η εφάπαξ λειτουργία ανά μισθωτή απαιτεί δικαιώματα καθολικού διαχειριστή.

Κάντε λήψη της δέσμης ενεργειών New-Agent365ToolsServicePrincipalProdPublic.ps1
Ανοίξτε το PowerShell ως Διαχειριστής και μεταβείτε στον κατάλογο σεναρίων.
Εκτελέστε τη δέσμη ενεργειών.
```
.\New-Agent365ToolsServicePrincipalProdPublic.ps1
```
Εισέλθετε χρησιμοποιώντας τα διαπιστευτήρια Azure όταν σας ζητηθεί.

Μετά την ολοκλήρωση, ο μισθωτής σας είναι έτοιμος για ανάπτυξη παράγοντα και ρύθμιση παραμέτρων διακομιστή MCP.

Ρυθμίστε διακομιστές MCP

Χρησιμοποιήστε το CLI Agent 365 για να εντοπίσετε, να προσθέσετε και να διαχειριστείτε διακομιστές MCP για τον παράγοντά σας. Για μια πλήρη λίστα των διαθέσιμων διακομιστών MCP και των δυνατοτήτων τους, ανατρέξτε στον κατάλογο MCP διακομιστών.

Ανακαλύψτε τους διαθέσιμους διακομιστές

Καταγράψτε όλους τους διακομιστές MCP που μπορείτε να διαμορφώσετε:

a365 develop list-available

Προσθέστε διακομιστές MCP

Προσθέστε έναν ή περισσότερους διακομιστές MCP στη διαμόρφωση του παράγοντά σας:

a365 develop add-mcp-servers mcp_MailTools

Σημαντικό

Αυτή η εντολή ενημερώνεται μόνο ToolingManifest.json στον φάκελο του έργου σας — δεν εκχωρεί δικαιώματα στη δομή προγράμματος. Ο τρόπος με τον οποίο εφαρμόζονται τα δικαιώματα εξαρτάται από το στάδιο στο οποίο βρίσκεστε στη διαδικασία εγκατάστασης:

Πριν από την αρχική ρύθμιση: Εκτελέστε a365 develop add-mcp-servers πρώτα και μετά προχωρήστε με a365 setup all. Η εντολή setup all περιλαμβάνει το βήμα εφαρμογής δικαιωμάτων MCP κατά τη δημιουργία της δομής προγράμματος.
Όταν η δομή προγράμματος έχει ήδη δημιουργηθεί: Ένας καθολικός διαχειριστής πρέπει να εκτελέσει την εντολή a365 setup permissions mcp ξεχωριστά. Ο διαχειριστής πρέπει να έχει το a365.config.json με το deploymentProjectPath να παραπέμπει στον φάκελο του έργου που περιέχει το ενημερωμένο αρχείο ToolingManifest.json. Μέχρι να ολοκληρωθεί αυτό το βήμα, τα νέα δικαιώματα του διακομιστή MCP δεν είναι ορατά στη δομή προγράμματος.

Λίστα ρυθμισμένων διακομιστών

Προβολή τρέχοντων διακομιστών MCP:

a365 develop list-configured

Καταργήστε τους διακομιστές MCP

Καταργήστε έναν διακομιστή MCP από τη διαμόρφωσή σας:

a365 develop remove-mcp-servers mcp_MailTools

Για την πλήρη τεκμηρίωση CLI, δείτε την εντολή a365 develop.

Χρήση εικονικού διακομιστή εργαλείων για δοκιμή

Για δοκιμή και ανάπτυξη, χρησιμοποιήστε τον εικονικό διακομιστή εργαλείων CLI Agent 365 αντί να συνδεθείτε σε πραγματικούς διακομιστές MCP. Ο δοκιμαστικός διακομιστής προσομοιώνει τις αλληλεπιδράσεις με διακομιστές MCP, ώστε να μπορείτε να δοκιμάσετε τον παράγοντα σας τοπικά χωρίς εξωτερικές εξαρτήσεις, όπως η αυθεντικοποίηση.

Ο δοκιμαστικός διακομιστής προσφέρει τα ακόλουθα οφέλη για τοπική ανάπτυξη και δοκιμές:

Ανάπτυξη εκτός σύνδεσης: Δοκιμάστε τον παράγοντα σας χωρίς σύνδεση στο διαδίκτυο ή εξωτερικές εξαρτήσεις.
Συνεπείς δοκιμές: Λάβετε προβλέψιμες απαντήσεις για τη δοκιμή ακραίων περιπτώσεων.
Εντοπισμός σφαλμάτων: Προβολή όλων των αιτημάτων και των απαντήσεων σε πραγματικό χρόνο
Ταχεία επαναληπτική ανάπτυξη: Δεν χρειάζεται να περιμένετε για εξωτερικές κλήσεις API ή να ρυθμίσετε σύνθετα περιβάλλοντα δοκιμών.

Ξεκινήστε τον δοκιμαστικό διακομιστή εργαλείων χρησιμοποιώντας την a365 develop start-mock-tooling-server εντολή.

Μάθετε να εγκαθιστάτε και να ρυθμίζετε τον δοκιμαστικό διακομιστή εργαλείων.

Σημείωμα

Οι ακόλουθες ενότητες για τη διαμόρφωση manifest και την ενσωμάτωση εργαλείων στον παράγοντά σας λειτουργούν με τον ίδιο τρόπο είτε χρησιμοποιείτε τον δοκιμαστικό διακομιστή εργαλείων είτε τους πραγματικούς διακομιστές MCP. Ρυθμίστε τη MCP_PLATFORM_ENDPOINT μεταβλητή περιβάλλοντος ώστε να οδηγεί στον εικονικό διακομιστή (για παράδειγμα: http://localhost:5309) αντί για το τελικό σημείο παραγωγής.

Κατανοήστε το μανιφέστο εργαλείων

Όταν εκτελέσετε την εντολή a365 develop add-mcp-servers, το CLI δημιουργεί το αρχείο ToolingManifest.json με τη διαμόρφωση για όλους τους διακομιστές MCP. Το περιβάλλον εκτέλεσης παράγοντα χρησιμοποιεί αυτό το μανιφέστο για να κατανοήσει ποιοι διακομιστές είναι διαθέσιμοι και πώς να πραγματοποιήσει έλεγχο ταυτότητας με αυτούς.

Δομή μανιφέστου

Παράδειγμα ToolingManifest.json:

{
  "mcpServers": [
    {
      "mcpServerName": "mcp_MailTools",
      "mcpServerUniqueName": "mcp_MailTools",
      "scope": "McpServers.Mail.All",
      "audience": "api://05879165-0320-489e-b644-f72b33f3edf0"
    }
  ]
}

Παράμετροι μανιφέστου

Κάθε καταχώρηση διακομιστή MCP περιέχει:

Παράμετρος	Περιγραφή
mcpServerName	Το εμφανιζόμενο όνομα του διακομιστή MCP.
mcpServerUniqueName	Το μοναδικό αναγνωριστικό για την παρουσία διακομιστή MCP.
πεδίο	Το πεδίο OAuth που απαιτείται για την πρόσβαση στις δυνατότητες του διακομιστή MCP (για παράδειγμα: `McpServers.Mail.All` για λειτουργίες αλληλογραφίας). Η εντολή `add-mcp-servers` ανακτά αυτήν την τιμή από τον κατάλογο του διακομιστή MCP.
κοινό	Το URI του Microsoft Entra ID που προσδιορίζει τον πόρο API προορισμού. Η εντολή `add-mcp-servers` ανακτά αυτήν την τιμή από τον κατάλογο του διακομιστή MCP.

Σημείωμα

Το Agent 365 CLI συμπληρώνει αυτόματα τις τιμές scope και audience όταν προσθέτετε έναν διακομιστή MCP. Αυτές οι τιμές προέρχονται από τον κατάλογο MCP και καθορίζουν τις άδειες που απαιτούνται για την πρόσβαση σε κάθε διακομιστή MCP.

Ενσωματώστε εργαλεία στον παράγοντα σας

Αφού δημιουργήσετε τη δήλωση εργαλείων, ενσωματώστε τους διαμορφωμένους διακομιστές MCP στον κώδικα του παράγοντά σας. Αυτή η ενότητα καλύπτει το προαιρετικό βήμα επιθεώρησης και τα απαιτούμενα βήματα ενσωμάτωσης των διακομιστών MCP.

Λίστα διακομιστών εργαλείων (προαιρετικό)

Φιλοδώρημα

Αυτό το βήμα είναι προαιρετικό. Χρησιμοποιήστε την υπηρεσία διαμόρφωσης διακομιστή εργαλείων για να επιθεωρήσετε τους διαθέσιμους διακομιστές εργαλείων από τη διακήρυξη εργαλείων πριν τους προσθέσετε στο πρόγραμμα συντονισμού.

Χρησιμοποιήστε την υπηρεσία ρύθμισης παραμέτρων διακομιστή εργαλείων για να ανακαλύψετε ποιοι διακομιστές εργαλείων είναι διαθέσιμοι στον παράγοντά σας από τη διακήρυξη εργαλείων. Αυτή η μέθοδος σάς επιτρέπει:

Ανακτήστε όλους τους διαμορφωμένους διακομιστές MCP από το αρχείο ToolingManifest.json.
Ανακτήστε μεταδεδομένα και δυνατότητες διακομιστή.
Επαληθεύστε τη διαθεσιμότητα του διακομιστή πριν από την εγγραφή.

Η μέθοδος λίστας διακομιστών εργαλείων είναι διαθέσιμη στα βασικά πακέτα εργαλείων:

# Use McpToolServerConfigurationService.list_tool_servers
from microsoft.agents.a365.tooling import McpToolServerConfigurationService

config_service = McpToolServerConfigurationService()
tool_servers = await config_service.list_tool_servers(agentic_app_id, auth_token)

Παράμετροι:

Παράμετρος	Type	Περιγραφή	Αναμενόμενη τιμή	Απαιτείται/προαιρετικό
`agentic_app_id`	str	Το μοναδικό αναγνωριστικό για το στιγμιότυπο της εφαρμογής παράγοντα	Έγκυρη συμβολοσειρά αναγνωριστικού εφαρμογής παράγοντα	Υποχρεωτικό
`auth_token`	str	Διακριτικό φορέα για έλεγχο ταυτότητας μέσω της πύλης διακομιστή MCP	Έγκυρο διακριτικό φορέα OAuth	Υποχρεωτικό

Πακέτο: microsoft_agents_a365.tooling

// Use McpToolServerConfigurationService.listToolServers
const { McpToolServerConfigurationService } = require('@microsoft/agents-a365-tooling');

const configService = new McpToolServerConfigurationService();
const toolServers = await configService.listToolServers(agentUserId, authToken);

Παράμετροι:

Παράμετρος	Type	Περιγραφή	Αναμενόμενη τιμή	Απαιτείται/προαιρετικό
`agentInstanceId`	string	Το μοναδικό αναγνωριστικό για την παρουσία παράγοντα	Έγκυρη συμβολοσειρά αναγνωριστικού παρουσίας παράγοντα	Απαραίτητο
`authToken`	string	Διακριτικό φορέα για έλεγχο ταυτότητας μέσω της πύλης διακομιστή MCP	Έγκυρο διακριτικό φορέα OAuth	Υποχρεωτικό

Πακέτο: @microsoft/agents-a365-tooling

// Use IMcpToolServerConfigurationService.ListToolServersAsync
using Microsoft.Agents.A365.Tooling.Services;

var configService = serviceProvider.GetRequiredService<IMcpToolServerConfigurationService>();
var toolServers = await configService.ListToolServersAsync(agentInstanceId, authToken);

Παράμετροι:

Παράμετρος	Type	Περιγραφή	Αναμενόμενη τιμή	Απαιτείται/προαιρετικό
`agentInstanceId`	string	Το μοναδικό αναγνωριστικό για την παρουσία παράγοντα	Έγκυρη συμβολοσειρά αναγνωριστικού παρουσίας παράγοντα	Απαραίτητο
`authToken`	string	Διακριτικό φορέα για έλεγχο ταυτότητας μέσω της πύλης διακομιστή MCP	Έγκυρο διακριτικό φορέα OAuth	Υποχρεωτικό

Πακέτο: Microsoft.Agents.A365.Tooling.Services

Καταχώρηση εργαλείων στο πρόγραμμα συντονισμού σας

Χρησιμοποιήστε τη μέθοδο επέκτασης για συγκεκριμένο πλαίσιο για να καταχωρήσετε όλους τους διακομιστές MCP στο πλαίσιο ενορχήστρωσης:

AddToolServersToAgentAsync (.NET)
add_tool_servers_to_agent (Python)
addToolServersToAgent (Node.js)

Αυτές οι μέθοδοι:

Εγγράψτε όλα τα εργαλεία από διαμορφωμένους διακομιστές MCP στο πρόγραμμα συντονισμού σας
Ρυθμίστε αυτόματα τα στοιχεία ελέγχου ταυτότητας και σύνδεσης
Κάντε τα εργαλεία άμεσα διαθέσιμα για να τα καλέσετε τον παράγοντά σας

Επιλέξτε την επέκταση προγράμματος συντονισμού

Το Agent 365 Tooling προσφέρει ειδικά πακέτα επέκτασης για διαφορετικά πλαίσια ενορχήστρωσης:

microsoft_agents_a365.tooling: Βασική λειτουργικότητα εργαλείων
microsoft_agents_a365.tooling.extensions.agentframework: Ενσωμάτωση Agent Framework
microsoft_agents_a365.tooling.extensions.azureaifoundry: Ενσωμάτωση Azure AI Foundry
microsoft_agents_a365.tooling.extensions.openai: Ενσωμάτωση OpenAI
microsoft_agents_a365.tooling.extensions.semantickernel: Ενσωμάτωση Semantic Kernel

Σημείωμα

Όταν εκτελείτε a365 develop add-mcp-servers, το CLI ανακτά αυτόματα τα scopes OAuth και τις τιμές audience από τον κατάλογο του MCP server και τα καταγράφει στο ToolingManifest.json. Οι μέθοδοι επέκτασης χρησιμοποιούν αυτές τις τιμές για να ρυθμίσουν τον έλεγχο ταυτότητας κατά το runtime — δεν απαιτείται χειροκίνητη παραμετροποίηση στον κώδικα του παράγοντα σας. Ωστόσο, ένας Global Administrator πρέπει ακόμα να παραχωρήσει αυτές τις άδειες στο blueprint του παράγοντα πριν ο παράγοντας σας μπορέσει να τις χρησιμοποιήσει στην παραγωγή: μέσω a365 setup all (πρώτη εγκατάσταση) ή a365 setup permissions mcp (αν το blueprint υπάρχει ήδη).

Για λεπτομερή παραδείγματα υλοποίησης, δείτε τα Agent 365 Samples.

Παραδείγματα υλοποίησης

Τα παρακάτω παραδείγματα δείχνουν πώς να ενσωματώσετε το Agent 365 Tooling σε διαφορετικά πλαίσια ενορχήστρωσης.

Python με OpenAI

Αυτό το παράδειγμα παρουσιάζει πώς να ενσωματώσετε τα εργαλεία MCP με το OpenAI σε μια εφαρμογή Python.

1. Προσθήκη δηλώσεων εισαγωγής

Προσθέστε τις απαιτούμενες εισαγωγές για πρόσβαση στη μονάδα εργαλείων και στις επεκτάσεις OpenAI:

from microsoft.agents.a365.tooling import McpToolServerConfigurationService
from microsoft.agents.a365.tooling.extensions.openai import mcp_tool_registration_service

2. Αρχικοποιήστε τις υπηρεσίες εργαλείων

Δημιουργήστε στιγμιότυπα των υπηρεσιών διαμόρφωσης και καταχώρησης εργαλείων:

# Create configuration service and tool service with dependency injection
self.config_service = McpToolServerConfigurationService()
self.tool_service = mcp_tool_registration_service.McpToolRegistrationService()

3. Καταχωρίστε τα εργαλεία MCP με τον OpenAI παράγοντας

Χρησιμοποιήστε τη μέθοδο add_tool_servers_to_agent για να καταχωρίσετε όλα τα διαμορφωμένα εργαλεία MCP στον OpenAI παράγοντά σας. Αυτή η μέθοδος χειρίζεται σενάρια ελέγχου ταυτότητας τόσο με χρήση παράγοντα όσο και χωρίς χρήση παράγοντα:

async def setup_mcp_servers(self, auth: Authorization, context: TurnContext):
    """Set up MCP server connections"""
    try:
        use_agentic_auth = os.getenv("USE_AGENTIC_AUTH", "false").lower() == "true"
        if use_agentic_auth:
            self.agent = await self.tool_service.add_tool_servers_to_agent(
                agent=self.agent,
                agentic_app_id=agentic_app_id,
                auth=auth,
                context=context,
            )
        else:
            self.agent = await self.tool_service.add_tool_servers_to_agent(
                agent=self.agent,
                agentic_app_id=agentic_app_id,
                auth=auth,
                context=context,
                auth_token=self.auth_options.bearer_token,
            )

    except Exception as e:
        logger.error(f"Error setting up MCP servers: {e}")

Παράμετροι μεθόδου

Ο παρακάτω πίνακας περιγράφει τις παραμέτρους για χρήση με add_tool_servers_to_agent.

Παράμετρος	Περιγραφή
`agent`	Το αντικείμενο OpenAI παράγοντα με το οποίο γίνεται εγγραφή εργαλείων.
`agentic_app_id`	Το μοναδικό αναγνωριστικό για τον παράγοντας (αναγνωριστικό εφαρμογής agentic).
`auth`	Το πλαίσιο εξουσιοδότησης για τον χρήστη.
`context`	Το πλαίσιο στροφής της τρέχουσας συνομιλίας από το SDK παράγοντα. Παρέχει ταυτότητα χρήστη, μεταδεδομένα συνομιλίας και πλαίσιο ελέγχου ταυτότητας για ασφαλή εγγραφή εργαλείων.
`auth_token`	(Προαιρετικός) Διακριτικό φορέα για σενάρια μη παράγοντα ελέγχου ταυτότητας.

4. Κλήση κατά την αρχικοποίηση

Βεβαιωθείτε ότι καλείτε τη μέθοδο setup κατά την αρχικοποίηση πριν εκτελέσετε τον παράγοντα:

# Setup MCP servers during initialization
await self.setup_mcp_servers(auth, context)

Η μέθοδος add_tool_servers_to_agent εκτελεί αυτόματα:

Φορτώνει όλους τους διακομιστές MCP από το αρχείο ToolingManifest.json.
Καταχωρεί τα εργαλεία τους στον OpenAI παράγοντας.
Ρυθμίζει τον έλεγχο ταυτότητας με βάση τη διαμόρφωση του manifest.
Καθιστά τα εργαλεία διαθέσιμα ώστε να τα ενεργοποιήσει ο παράγοντας σας.

JavaScript με LangChain

Αυτό το παράδειγμα δείχνει πώς να ενσωματώσετε εργαλεία MCP με το LangChain σε μια εφαρμογή JavaScript ή TypeScript.

1. Προσθήκη δηλώσεων εισαγωγής

Προσθέστε τις απαιτούμενες εισαγωγές για πρόσβαση στη μονάδα εργαλείων και στις επεκτάσεις LangChain:

import { McpToolServerConfigurationService } from '@microsoft/agents-a365-tooling';
import { McpToolRegistrationService } from '@microsoft/agents-a365-tooling-extensions-langchain';

2. Αρχικοποιήστε τις υπηρεσίες εργαλείων

Δημιουργήστε μια παρουσία της υπηρεσίας καταχώρισης εργαλείων:

const toolService = new McpToolRegistrationService();

3. Καταχωρίστε τα εργαλεία MCP με τον LangChain παράγοντα

Χρησιμοποιήστε τη addToolServersToAgent μέθοδο για να καταχωρίσετε όλα τα διαμορφωμένα εργαλεία MCP στον LangChain παράγοντα σας. Αυτή η μέθοδος χειρίζεται σενάρια ελέγχου ταυτότητας τόσο με χρήση παράγοντα όσο και χωρίς χρήση παράγοντα:

// Get MCP Tools
try {
  const agent = await toolService.addToolServersToAgent(
    agent,
    process.env.AGENTIC_USER_ID || '',
    authorization,
    turnContext,
    process.env.MCP_AUTH_TOKEN || "",
  );
} catch (error) {
  console.error('Error adding MCP tool servers:', error);
}

Παράμετροι μεθόδου

Ο παρακάτω πίνακας περιγράφει τις παραμέτρους που πρέπει να χρησιμοποιηθούν με τη addToolServersToAgent μέθοδο.

Παράμετρος	Περιγραφή
`agent`	Το αντικείμενο LangChain ReactAgent με το οποίο γίνεται η εγγραφή εργαλείων.
`agentUserId`	Το μοναδικό αναγνωριστικό για τον χρήστη παράγοντα. Χρησιμοποιήστε μια κενή συμβολοσειρά (`''`) εάν δεν χρησιμοποιείτε έλεγχο ταυτότητας τύπου παράγοντα.
`authorization`	Το πλαίσιο εξουσιοδότησης για τον χρήστη.
`turnContext`	Το πλαίσιο στροφής της τρέχουσας συνομιλίας από το SDK παράγοντα. Παρέχει ταυτότητα χρήστη, μεταδεδομένα συνομιλίας και πλαίσιο ελέγχου ταυτότητας για ασφαλή εγγραφή εργαλείων.
`authToken`	(Προαιρετικός) Διακριτικό φορέα για σενάρια μη παράγοντα ελέγχου ταυτότητας.

4. Κλήση κατά την αρχικοποίηση

Καλέστε τη μέθοδο addToolServersToAgent κατά την αρχικοποίηση για να καταχωρήσετε τα εργαλεία MCP στον παράγοντα σας.

Η μέθοδος addToolServersToAgent εκτελεί αυτόματα:

Φορτώνει όλους τους διακομιστές MCP από το αρχείο ToolingManifest.json.
Καταχωρεί τα εργαλεία τους στον παράγοντας LangChain.
Ρυθμίζει τον έλεγχο ταυτότητας με βάση τη διαμόρφωση του manifest.
Καθιστά τα εργαλεία διαθέσιμα ώστε να τα ενεργοποιήσει ο παράγοντας σας.

.NET με Semantic Kernel

Αυτό το παράδειγμα δείχνει πώς να ενσωματώσετε εργαλεία MCP με το Semantic Kernel σε μια εφαρμογή .NET.

1. Προσθήκη δηλώσεων εισαγωγής

Προσθέστε τους απαιτούμενους χώρους ονομάτων για να έχετε πρόσβαση στη λειτουργική μονάδα εργαλείων και στις επεκτάσεις Semantic Kernel:

using Microsoft.Agents.A365.Tooling;
using Microsoft.Agents.A365.Tooling.Extensions.SemanticKernel;

2. Καταχωρίστε υπηρεσίες με έγχυση εξάρτησης

Προσθέστε τις υπηρεσίες εργαλείων στον περιέκτη έγχυσης εξαρτήσεων ώστε να μπορείτε να τις εισάγετε στις τάξεις σας:

builder.Services.AddSingleton<IMcpToolRegistrationService, McpToolRegistrationService>();
builder.Services.AddSingleton<IMcpToolServerConfigurationService, McpToolServerConfigurationService>();

3. Δηλώστε ιδιωτικό πεδίο

Δηλώστε ένα ιδιωτικό πεδίο για να αποθηκεύει την αναφορά στην υπηρεσία καταχώρισης εργαλείου:

private readonly IMcpToolRegistrationService _toolsService;

4. Καταχωρίστε τα εργαλεία MCP με το Semantic Kernel

Χρησιμοποιήστε τη μέθοδο επέκτασης AddToolServersToAgentAsync για να καταχωρίσετε όλα τα διαμορφωμένα εργαλεία MCP στο Semantic Kernel. Αυτή η μέθοδος χειρίζεται σενάρια ελέγχου ταυτότητας τόσο με χρήση παράγοντα όσο και χωρίς χρήση παράγοντα:

// Simplified call (authentication configured automatically)
await toolService.AddToolServersToAgentAsync(kernel, userAuthorization, turnContext);

// Or with explicit authentication parameters:
if (useAgenticAuth)
{
    await toolService.AddToolServersToAgentAsync(kernel, userAuthorization, authHandlerName, turnContext);
}
else
{
    await toolService.AddToolServersToAgentAsync(kernel, userAuthorization, authHandlerName, turnContext, authToken);
}

Σημείωμα

Διατίθενται πολλαπλές υπερφορτώσεις μεθόδων. Η απλοποιημένη έκδοση χρησιμοποιεί την προεπιλεγμένη διαμόρφωση ελέγχου ταυτότητας, ενώ η έκδοση με ρητές επιλογές επιτρέπει τον ορισμό προσαρμοσμένου χειριστή ελέγχου ταυτότητας.

Παράμετροι μεθόδου

Ο παρακάτω πίνακας περιγράφει τις παραμέτρους για χρήση με AddToolServersToAgentAsync.

Παράμετρος	Περιγραφή
`kernel`	Το αντικείμενο Semantic Kernel με το οποίο καταχωρούνται εργαλεία. Ο πυρήνας ενορχηστρώνει υπηρεσίες AI, προσθήκες και εκτέλεση λειτουργιών.
`userAuthorization`	Το πλαίσιο εξουσιοδότησης για τον χρήστη.
`authHandlerName`	Όνομα χειριστή ελέγχου ταυτότητας για χρήση με το σύστημα UserAuthorization.
`turnContext`	Το πλαίσιο της τρέχουσας στροφής συνομιλίας (ένας κύκλος μηνύματος χρήστη και απάντησης παράγοντα) από το Agents SDK. Παρέχει ταυτότητα χρήστη, μεταδεδομένα συνομιλίας και πλαίσιο ελέγχου ταυτότητας για ασφαλή εγγραφή εργαλείων.
`authToken`	(Προαιρετικός) Διακριτικό φορέα για σενάρια μη παράγοντα ελέγχου ταυτότητας.

Η μέθοδος AddToolServersToAgentAsync εκτελεί αυτόματα:

Φορτώνει όλους τους διακομιστές MCP από το αρχείο ToolingManifest.json.
Καταχωρεί τα εργαλεία τους στον Σημασιολογικό Πυρήνα.
Ρυθμίζει τον έλεγχο ταυτότητας με βάση τη διαμόρφωση του manifest.
Καθιστά τα εργαλεία διαθέσιμα ώστε να τα ενεργοποιήσει ο παράγοντας σας.

Για ολοκληρωμένα παραδείγματα, επισκεφθείτε το Agent 365 Samples repository.

Άλλοι τρόποι πρόσβασης σε διακομιστές Agent 365 MCP

Εκτός από το Agent 365 SDK, μπορείτε να αποκτήσετε πρόσβαση σε διακομιστές MCP μέσω άλλων εμπειριών ανάπτυξης:

Visual Studio Code - Συνδεθείτε απευθείας με MCP servers για προσαρμοσμένες ροές εργασιών ανάπτυξης:
Microsoft Copilot Studio - Ενσωματώστε MCP servers σε ροές συνομιλίας χρησιμοποιώντας μια εμπειρία χαμηλών απαιτήσεων κώδικα.
Azure AI Foundry - Χρησιμοποιήστε MCP servers με πλήρη υποστήριξη SDK και προηγμένες δυνατότητες ενορχήστρωσης.

Για μια πλήρη επισκόπηση των διαθέσιμων διακομιστών MCP και των επιλογών ενοποίησης σε αυτές τις πλατφόρμες, ανατρέξτε στο θέμα Επισκόπηση διακομιστών εργαλείων Agent 365.

Διακομιστής MCP BYO (Bring Your Own)

Η δυνατότητα BYO διακομιστή MCP σας επιτρέπει να καταχωρίσετε τους δικούς σας εξωτερικούς διακομιστές MCP στο Microsoft Agent 365, ώστε να μπορούν να διαχειρίζονται, να εγκρίνονται και να παρακολουθούνται κεντρικά στο Κέντρο διαχείρισης Microsoft 365. Δρομολογεί αυτούς τους διακομιστές μέσω της πύλης εργαλείων Agent 365, δίνοντας στους διαχειριστές τον έλεγχο της έγκρισης, της πρόσβασης και των πολιτικών, ενώ επιτρέπει στις ομάδες ασφαλείας να παρακολουθούν τη χρήση μέσω τηλεμετρίας. Ως προγραμματιστής, μπορείτε να καταχωρήσετε τον διακομιστή MCP χρησιμοποιώντας το Agent 365 CLI και, στη συνέχεια, να ζητήσετε από τον διαχειριστή σας να ελέγξει και να εγκρίνει την εγγραφή και να εκχωρήσει δικαιώματα. Ο εγκεκριμένος διακομιστής μπορεί στη συνέχεια να χρησιμοποιηθεί σε υποστηριζόμενα εργαλεία πελάτη, με συνεχή παρακολούθηση που διασφαλίζει τη συμμόρφωση και την ορατότητα σε όλες τις ενσωματώσεις.

Για πλήρεις οδηγίες, δείτε Φέρτε τον δικό σας διακομιστή MCP (BYO).

Δοκιμή του παράγοντά σας

Αφού ενσωματώσετε τα εργαλεία MCP στον παράγοντά σας, δοκιμάστε τις επικλήσεις εργαλείων για να βεβαιωθείτε ότι λειτουργούν σωστά και χειρίζονται διαφορετικά σενάρια. Ακολουθήστε τον οδηγό δοκιμών για να ρυθμίσετε το περιβάλλον σας. Στη συνέχεια, εστιάστε κυρίως στην ενότητα Δοκιμή κλήσεων εργαλείων για να επαληθεύσετε ότι τα MCP εργαλεία σας λειτουργούν όπως αναμένεται. Επίσης, δείτε τον δοκιμαστικό διακομιστή εργαλείων για να δοκιμάσετε τη σύνδεση με τον διακομιστή MCP και τις κλήσεις εργαλείων χωρίς να χρειάζεται να χειριστείτε τον έλεγχο ταυτότητας.

Προσθήκη παρατηρησιμότητας

Προσθέστε παρατηρησιμότητα στον παράγοντα σας για να παρακολουθείτε και να ιχνηλατείτε τις κλήσεις των εργαλείων MCP του παράγοντα. Με την προσθήκη δυνατοτήτων παρατηρησιμότητας, μπορείτε να παρακολουθείτε την απόδοση, να εντοπίζετε προβλήματα και να αναλύετε τα μοτίβα χρήσης των εργαλείων MCP. Μάθετε περισσότερα για την υλοποίηση ιχνηλάτησης και παρακολούθησης.

Αντιμετώπιση προβλημάτων

Αυτή η ενότητα παραθέτει συνήθη προβλήματα κατά τη διαμόρφωση και τη χρήση διακομιστών και εργαλείων MCP.

Φιλοδώρημα

Ο Οδηγός αντιμετώπισης προβλημάτων του Agent 365 περιλαμβάνει συστάσεις αντιμετώπισης προβλημάτων υψηλού επιπέδου, βέλτιστες πρακτικές και συνδέσμους για περιεχόμενο αντιμετώπισης προβλημάτων για κάθε μέρος του κύκλου ζωής ανάπτυξης του Agent 365.

Προβλήματα διακομιστών MCP και εργαλείων

Συμπτώματα:

Σφάλματα κατά την κλήση εργαλείων.
Σφάλματα "Ο διακομιστής MCP δεν βρέθηκε".
Σφάλματα άρνησης άδειας κατά την κλήση εργαλείων.

Ριζική αιτία:

Ο διακομιστής MCP δεν έχει ρυθμιστεί.
Λείπουν δικαιώματα.
Η κύρια υπηρεσία δεν έχει ρυθμιστεί.
Σύγχυση μεταξύ δοκιμαστικών και διακομιστών παραγωγής.

Λύσεις: Δοκιμάστε τις επόμενες λύσεις για να αντιμετωπίσετε το πρόβλημα.

Επαληθεύστε ότι οι διακομιστές MCP έχουν διαμορφωθεί

Εμφανίστε τους διαμορφωμένους διακομιστές και προσθέστε όσους λείπουν.
```
# List configured servers
a365 develop list-configured

# If empty, add required servers (example: Mail MCP server)
a365 develop add-mcp-servers mcp_MailTools
```
Ελέγξτε αν υπάρχει κύρια υπηρεσία

Βεβαιωθείτε ότι έχει δημιουργηθεί το απαιτούμενο service principal για εργαλεία.
```
# Run the one-time setup script
# https://github.com/microsoft/Agent365-devTools/blob/main/scripts/cli/Auth/New-Agent365ToolsServicePrincipalProdPublic.ps1
```
Για την αρχική ανάπτυξη και δοκιμή, χρησιμοποιήστε δοκιμαστικούς διακομιστές

Χρησιμοποιήστε τον εικονικό διακομιστή εργαλείων για πρώιμη τοπική ανάπτυξη και δοκιμή, εάν θέλετε να δοκιμάσετε τον υπόλοιπο παράγοντά σας χωρίς στοιχεία εργαλείων παραγωγής.
```
# Start mock tooling server
a365 develop start-mock-tooling-server

# Update your .env
MCP_PLATFORM_ENDPOINT=http://localhost:5309
```
Μάθετε για τον δοκιμαστικό διακομιστή εργαλείων (mock tooling server).
Επαλήθευση δικαιωμάτων στο κέντρο διαχείρισης

Επιβεβαιώστε ότι ο παράγοντας σας διαθέτει τα απαραίτητα δικαιώματα MCP.
- Επαληθεύστε ότι τα δικαιώματα API του blueprint του παράγοντα στην Azure portal εμφανίζουν όλα τα δικαιώματα διακομιστή MCP.
Επαλήθευση:
```
# Test a tool call in Agents Playground
# Should execute without permission errors
```

Σχόλια

Ήταν χρήσιμη αυτή η σελίδα;

Last updated on 2026-07-30

Προσθήκη και διαχείριση εργαλείων

Επισκόπηση

Προαπαιτούμενα στοιχεία

Ρύθμιση ταυτότητας παράγοντα

Ρύθμιση ελέγχου ταυτότητας OBO

Ρύθμιση παραμέτρων κύριας υπηρεσίας

Ρυθμίστε διακομιστές MCP

Ανακαλύψτε τους διαθέσιμους διακομιστές

Προσθέστε διακομιστές MCP

Λίστα ρυθμισμένων διακομιστών

Καταργήστε τους διακομιστές MCP

Χρήση εικονικού διακομιστή εργαλείων για δοκιμή

Κατανοήστε το μανιφέστο εργαλείων

Δομή μανιφέστου

Παράμετροι μανιφέστου

Ενσωματώστε εργαλεία στον παράγοντα σας

Λίστα διακομιστών εργαλείων (προαιρετικό)

Καταχώρηση εργαλείων στο πρόγραμμα συντονισμού σας

Επιλέξτε την επέκταση προγράμματος συντονισμού

Παραδείγματα υλοποίησης

Python με OpenAI

1. Προσθήκη δηλώσεων εισαγωγής

2. Αρχικοποιήστε τις υπηρεσίες εργαλείων

3. Καταχωρίστε τα εργαλεία MCP με τον OpenAI παράγοντας

Παράμετροι μεθόδου

4. Κλήση κατά την αρχικοποίηση

Άλλοι τρόποι πρόσβασης σε διακομιστές Agent 365 MCP

Διακομιστής MCP BYO (Bring Your Own)

Δοκιμή του παράγοντά σας

Προσθήκη παρατηρησιμότητας

Αντιμετώπιση προβλημάτων

Προβλήματα διακομιστών MCP και εργαλείων

Σχόλια

Πρόσθετοι πόροι