Notatka
Dostęp do tej strony wymaga autoryzacji. Może spróbować zalogować się lub zmienić katalogi.
Dostęp do tej strony wymaga autoryzacji. Możesz spróbować zmienić katalogi.
Ważna
Elementy oznaczone podglądem w tym artykule są obecnie w wersji zapoznawczej. Ta wersja zapoznawcza jest udostępniana bez umowy dotyczącej poziomu usług, a Microsoft nie zaleca korzystania z niej w przypadku obciążeń produkcyjnych. Niektóre funkcje mogą nie być obsługiwane lub mogą mieć ograniczone możliwości. Aby uzyskać więcej informacji, zobacz Wygólne warunki użytkowania Microsoft Azure Previews.
Uwaga / Notatka
- W tym artykule opisano narzędzie Microsoft SharePoint dla usługi Foundry Agent Service. Aby uzyskać informacje na temat używania i wdrażania witryn SharePoint, zobacz dokumentację SharePoint.
- Zobacz najlepsze rozwiązania dotyczące optymalizowania użycia narzędzi.
Użyj wersji zapoznawczej narzędzia SharePoint do ugruntowania obsługi w usłudze Microsoft Foundry Agent, pobierając zawartość z witryny lub folderu SharePoint (na przykład contoso.sharepoint.com/sites/policies). Gdy użytkownik zadaje pytanie, agent może wywołać narzędzie SharePoint w celu pobrania odpowiedniego tekstu z dokumentów, do których użytkownik może uzyskać dostęp. Następnie agent generuje odpowiedź na podstawie pobranej zawartości.
Ta integracja korzysta z przekazywania tożsamości (w imieniu użytkownika), dzięki czemu uprawnienia SharePoint są nadal stosowane do każdego żądania. Aby uzyskać więcej informacji o bazowej integracji interfejsu API Retrieval usługi Microsoft Copilot, zobacz Jak to działa.
Ważna
Przed rozpoczęciem: narzędzie SharePoint wymaga uwierzytelniania tożsamości użytkownika (bez aplikacji tylko/pryncypału usługi), Twoja witryna SharePoint i agent Foundry muszą znajdować się w tej samej dzierżawie, a tylko jedno narzędzie SharePoint na agenta jest obsługiwane. Narzędzie nie działa, gdy agent zostanie opublikowany w Microsoft Teams. Zobacz Ograniczenia , aby uzyskać pełną listę.
Wymagania wstępne
Uprawniona licencja lub model płatności za rzeczywiste użycie:
- Deweloperzy i użytkownicy końcowi muszą posiadać licencję Microsoft 365 Copilot, zgodnie z wymogami interfejsu Microsoft Copilot Retrieval API.
- Jeśli deweloperzy i użytkownicy końcowi nie mają licencji Microsoft 365 Copilot, możesz włączyć model pay-as-you-go.
Deweloperzy i użytkownicy końcowi mają co najmniej
Foundry Userrolę RBAC przypisaną w projekcie Foundry. Aby uzyskać więcej informacji na temat kontroli dostępu opartej na rolach Azure, zobacz Azure kontrola dostępu oparta na rolach w narzędziu Foundry.Ważna
Niedawno zmieniono nazwy ról RBAC w usłudze Foundry. Użytkownik Foundry, właściciel Foundry, właściciel konta Foundry i menedżer projektu Foundry były wcześniej nazywane odpowiednio użytkownikiem Azure AI, właścicielem Azure AI, właścicielem konta Azure AI i menedżerem projektu Azure AI. Poprzednie nazwy mogą być nadal widoczne w niektórych miejscach, podczas gdy zmiana nazwy jest wdrażana. Identyfikatory ról i uprawnienia podstawowe są niezmienione przez zmianę nazwy.
Deweloperzy i użytkownicy końcowi mają co najmniej
READdostęp do witryny SharePoint.Upewnij się, że dzierżawa programu SharePoint i projekt Foundry znajdują się w tej samej dzierżawie firmy Microsoft Entra. Wymiana tokenów między dzierżawami nie jest obsługiwana.
Zainstaluj wymagany pakiet zestawu SDK:
-
Python:
pip install "azure-ai-projects>=2.0.0" -
C#: Instalowanie
Azure.AI.Projectspakietu NuGet -
TypeScript/JavaScript:
npm install @azure/ai-projects -
Java: Dodaj najnowszą zależność
com.azure:azure-ai-agentsdopom.xml
-
Python:
Skonfiguruj zmienne środowiskowe używane przez przykład:
-
FOUNDRY_PROJECT_ENDPOINT: Adres URL punktu końcowego projektu Foundry -
FOUNDRY_MODEL_DEPLOYMENT_NAME: Nazwa wdrożenia modelu (na przykładgpt-4) -
SHAREPOINT_PROJECT_CONNECTION_ID: Identyfikator połączenia SharePoint w formacie/subscriptions/{{subscriptionID}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.CognitiveServices/accounts/{{foundryAccountName}}/projects/{{foundryProjectName}}/connections/{{foundryConnectionName}} - W przypadku przykładów REST:
AGENT_TOKEN
-
Zobacz szybki start, aby uzyskać dodatkowe szczegóły konfiguracji uwierzytelniania.
Konfigurowanie połączenia SharePoint i użytkownika delegowanego
Narzędzie SharePoint używa delegowanego uwierzytelniania użytkownika. Uruchom agenta przy użyciu tożsamości zalogowanego użytkownika, aby SharePoint mógł zastosować uprawnienia tego użytkownika do witryn, folderów i dokumentów. Uwierzytelnianie tylko dla aplikacji i jednostki usługi nie jest obsługiwane.
Uwaga / Notatka
Zacznij od witryny SharePoint, która ma prostą strukturę folderów i niewielką liczbę krótkich dokumentów.
- Wybierz SharePoint i postępuj zgodnie z monitami, aby dodać narzędzie. Można dodać tylko jedno narzędzie SharePoint dla każdego agenta.
- Dodaj połączenie SharePoint. Aby uzyskać pełny przepływ pracy połączenia, zobacz Dodawanie nowego połączenia do projektu.
- W konfiguracji połączenia SharePoint wprowadź adres URL witryny lub adres URL folderu:
- Adres URL witryny:
https://<company>.sharepoint.com/sites/<site_name> - Adres URL folderu:
https://<company>.sharepoint.com/sites/<site_name>/Shared%20documents/<folder_name>
Użyj adresu URL witryny lub folderu w jednym z tych formatów. Nie kopiuj pełnego adresu przeglądarki, który może zawierać nieobsługiwaną ścieżkę lub wartości ciągu zapytania.
- Zapisz połączenie, a następnie skopiuj jego identyfikator połączenia.
- Ustaw identyfikator połączenia jako
SHAREPOINT_PROJECT_CONNECTION_ID. - Zaloguj się jako użytkownik, który ma co najmniej
READdostęp do skonfigurowanego zakresu SharePoint i uruchom agenta przy użyciu tożsamości delegowanej tego użytkownika.
Zweryfikować pobieranie z uwzględnieniem uprawnień
Przed udostępnieniem agenta użytkownikom sprawdź zarówno pomyślne pobieranie, jak i odrzucone pobieranie:
- Wybierz dokument w skonfigurowanym zakresie, który może odczytać jeden użytkownik testowy, a drugi użytkownik testowy nie może odczytać.
- Zaloguj się jako użytkownik z dostępem, zadaj pytanie, którego odpowiedź znajduje się w tym dokumencie, i upewnij się, że odpowiedź zawiera oczekiwane informacje i cytat do dokumentu.
- Zaloguj się jako użytkownik bez dostępu i zadaj to samo pytanie. Upewnij się, że odpowiedź nie zawiera informacji ani cytatów z dokumentu z ograniczeniami.
Uruchom oba testy z uwierzytelnianiem użytkownika delegowanego. Odpowiedź pierwszego użytkownika potwierdza, że dane zostały pobrane; inny wynik dla drugiego użytkownika potwierdza, że w usłudze SharePoint jest stosowane przycinanie uprawnień.
Wsparcie użytkowania
W poniższej tabeli przedstawiono zestaw SDK i obsługę konfiguracji.
| Pomoc techniczna firmy Microsoft Foundry | zestaw SDK Python | Zestaw SDK języka C# | Zestaw SDK dla języka JavaScript | zestaw SDK Java | interfejs API REST | Konfiguracja agenta podstawowego | Konfiguracja agenta standardowego |
|---|---|---|---|---|---|---|---|
| ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
Parametry
Narzędzie SharePoint używa połączenia projektu, aby określić, z której witryny lub folderu SharePoint można pobrać.
| Parametr | Wymagane | Notatki |
|---|---|---|
type |
Tak | Użyj sharepoint_grounding_preview. |
sharepoint_grounding_preview.project_connections[].project_connection_id |
Tak | Użyj wartości SHAREPOINT_PROJECT_CONNECTION_ID. |
Jeśli musisz utworzyć połączenie SharePoint dla projektu, zobacz Dodaj nowe połączenie z projektem.
Tworzenie agenta za pomocą narzędzia SharePoint
Przykłady SDK używają elementu DefaultAzureCredential. Gdy uruchamiasz je lokalnie, to poświadczenie musi wskazywać na tożsamość zalogowanego użytkownika, na przykład tożsamość ustanowioną przez az login. Wyklucz poświadczenia tożsamości zarządzanej i nazwy głównej usługi z lokalnego łańcucha poświadczeń. W aplikacji produkcyjnej uwierzytelniaj każde żądanie za pomocą delegowanej tożsamości bieżącego użytkownika i używaj przepływu typu On-Behalf-Of. Nie uruchamiaj wywołań narzędzia SharePoint za pomocą tożsamości zarządzanej aplikacji ani jej jednostki usługi.
W poniższym przykładzie przedstawiono, jak utworzyć agenta, który używa narzędzia SharePoint do wspierania odpowiedzi danymi z zawartości witryny SharePoint. Wybierz Prompt Agents, aby użyć zestawu SDK Azure AI Projects do utworzenia agenta promptów po stronie serwera, lub Hosted Agents, aby użyć struktury Agent Framework FoundryChatClient do zbudowania efemerycznego agenta działającego w procesie.
Pobudzaj agentów
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
PromptAgentDefinition,
SharepointPreviewTool,
SharepointGroundingToolParameters,
ToolProjectConnection,
)
# Format: "https://resource_name.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"
AGENT_NAME = "MyAgent"
SHAREPOINT_CONNECTION_NAME = "my-sharepoint-connection"
# Create a client to call Foundry API
with AIProjectClient(
endpoint=PROJECT_ENDPOINT,
credential=DefaultAzureCredential(),
) as project:
# Get connection ID from connection name
sharepoint_connection = project.connections.get(
SHAREPOINT_CONNECTION_NAME,
)
# Configure SharePoint tool with the project connection
sharepoint_tool = SharepointPreviewTool(
sharepoint_grounding_preview=SharepointGroundingToolParameters(
project_connections=[
ToolProjectConnection(
project_connection_id=sharepoint_connection.id
)
]
)
)
agent = project.agents.create_version(
agent_name=AGENT_NAME,
definition=PromptAgentDefinition(
model="gpt-4.1-mini",
instructions="""You are a helpful agent that can use SharePoint tools to assist users.
Use the available SharePoint tools to answer questions and perform tasks.""",
tools=[sharepoint_tool],
),
)
print(f"Agent created (id: {agent.id}, name: {agent.name}, version: {agent.version})")
with project.get_openai_client(agent_name=agent.name) as openai:
# Send initial request that will trigger the SharePoint tool
stream_response = openai.responses.create(
stream=True,
tool_choice="required",
input="Please summarize the last meeting notes stored in SharePoint.",
)
for event in stream_response:
if event.type == "response.created":
print(f"Follow-up response created with ID: {event.response.id}")
elif event.type == "response.output_text.delta":
print(f"Delta: {event.delta}")
elif event.type == "response.output_text.done":
print(f"\nFollow-up response done!")
elif event.type == "response.output_item.done":
if event.item.type == "message":
item = event.item
if item.content[-1].type == "output_text":
text_content = item.content[-1]
for annotation in text_content.annotations:
if annotation.type == "url_citation":
print(
f"URL Citation: {annotation.url}, "
f"Start index: {annotation.start_index}, "
f"End index: {annotation.end_index}"
)
elif event.type == "response.completed":
print(f"\nFollow-up completed!")
print(f"Full response: {event.response.output_text}")
Oczekiwane dane wyjściowe
Po uruchomieniu tego kodu zobaczysz dane wyjściowe podobne do następujących:
Agent created (id: asst_abc123, name: MyAgent, version: 1)
Sending request to SharePoint agent with streaming...
Follow-up response created with ID: resp_xyz789
Delta: Based
Delta: on
Delta: the
Delta: meeting
Delta: notes
...
URL Citation: https://contoso.sharepoint.com/sites/policies/Documents/meeting-notes.docx, Start index: 0, End index: 245
Follow-up response done!
Follow-up completed!
Full response: Based on the meeting notes from your SharePoint site, the last meeting covered the following topics: project timeline updates, budget review, and next quarter planning.
Hostowani agenci
W tym przykładzie użyto elementu FoundryChatClient z platformy Microsoft Agent Framework oraz wywołano get_sharepoint_tool(), aby dołączyć połączenie uziemiające z usługą SharePoint. Używa AIProjectClient do przekształcenia nazwy połączenia w identyfikator połączenia, a następnie iteruje po adnotacjach wiadomości, aby wypisać cytowania adresów URL. Zainstaluj pakiet za pomocą pip install agent-framework-foundry aiohttp, ustaw zmienne środowiskowe FOUNDRY_PROJECT_ENDPOINT i FOUNDRY_MODEL, a następnie zaloguj się za pomocą az login.
import asyncio
import os
from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from azure.ai.projects import AIProjectClient
from azure.identity import AzureCliCredential
SHAREPOINT_CONNECTION_NAME = "my-sharepoint-connection"
async def main() -> None:
credential = AzureCliCredential()
project = AIProjectClient(
endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
credential=credential,
)
sharepoint_connection_id = project.connections.get(SHAREPOINT_CONNECTION_NAME).id
agent = Agent(
client=FoundryChatClient(credential=credential),
instructions="You are a helpful agent. Use the SharePoint tool to answer questions.",
tools=[FoundryChatClient.get_sharepoint_tool(connection_id=sharepoint_connection_id)],
)
result = await agent.run("Please summarize the last meeting notes stored in SharePoint.")
print(f"Agent: {result.text}")
for message in result.messages:
for content in message.contents:
for annotation in getattr(content, "annotations", None) or []:
url = getattr(annotation, "url", None)
if url:
title = getattr(annotation, "title", None) or ""
print(f"URL Citation: [{title}]({url})")
if __name__ == "__main__":
asyncio.run(main())
Oczekiwane dane wyjściowe
Tekst odpowiedzi jest wyświetlany wraz z wszelkimi cytatami adresów URL zwróconymi przez narzędzie ugruntowujące SharePoint:
Agent: Based on the meeting notes from your SharePoint site ...
URL Citation: [Meeting notes](https://contoso.sharepoint.com/sites/policies/Documents/meeting-notes.docx)
Aby uzyskać więcej informacji na temat fabryk narzędzi Foundry dla platformy Agent Framework, zobacz przykłady dostawców platformy Foundry.
W poniższym przykładzie przedstawiono, jak utworzyć agenta, który używa narzędzia SharePoint do wspierania odpowiedzi danymi z zawartości witryny SharePoint. W tym przykładzie użyto metod synchronicznych dla uproszczenia. Aby zapoznać się z wersją asynchroniczną, zapoznaj się z przykładową dokumentacją agenta SharePoint w Azure SDK dla repozytorium .NET GitHub.
Aby umożliwić agentowi dostęp do SharePoint, użyj polecenia SharepointPreviewTool. Wybierz Prompt Agents, aby za pomocą zestawu SDK Azure AI Projects utworzyć po stronie serwera agenta opartego na monicie, lub Hosted Agents, aby za pomocą Microsoft Agent Framework utworzyć tymczasowego agenta działającego w procesie.
Pobudzaj agentów
using System;
using Azure.AI.Projects;
using Azure.AI.Extensions.OpenAI;
using Azure.Identity;
// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
var projectEndpoint = "your_project_endpoint";
var sharepointConnectionName = "my-sharepoint-connection";
// Create project client to call Foundry API
AIProjectClient projectClient = new(endpoint: new Uri(projectEndpoint), tokenProvider: new DefaultAzureCredential());
// Get connection ID from connection name
AIProjectConnection sharepointConnection = projectClient.Connections.GetConnection(connectionName: sharepointConnectionName);
// Use the SharePoint connection ID to initialize the SharePointGroundingToolOptions,
// which will be used to create SharepointPreviewTool. Use this tool to create an Agent.
SharePointGroundingToolOptions sharepointToolOption = new()
{
ProjectConnections = { new ToolProjectConnection(projectConnectionId: sharepointConnection.Id) }
};
DeclarativeAgentDefinition agentDefinition = new(model: "gpt-4.1-mini")
{
Instructions = "You are a helpful assistant.",
Tools = { new SharepointPreviewTool(sharepointToolOption), }
};
AgentVersion agentVersion = projectClient.AgentAdministrationClient.CreateAgentVersion(
agentName: "myAgent",
options: new(agentDefinition));
// Create the response and make sure we are always using tool.
ProjectResponsesClient responseClient = projectClient.ProjectOpenAIClient.GetProjectResponsesClientForAgent(agentVersion.Name);
CreateResponseOptions responseOptions = new()
{
ToolChoice = ResponseToolChoice.CreateRequiredChoice(),
InputItems = { ResponseItem.CreateUserMessageItem("What is Contoso whistleblower policy") }
};
ResponseResult response = responseClient.CreateResponse(options: responseOptions);
// SharePoint tool can create the reference to the page, grounding the data.
// Create the GetFormattedAnnotation method to get the URI annotation.
string annotation = "";
foreach (ResponseItem item in response.OutputItems)
{
if (item is MessageResponseItem messageItem)
{
foreach (ResponseContentPart content in messageItem.Content)
{
foreach (ResponseMessageAnnotation messageAnnotation in content.OutputTextAnnotations)
{
if (messageAnnotation is UriCitationMessageAnnotation uriAnnotation)
{
annotation = $" [{uriAnnotation.Title}]({uriAnnotation.Uri})";
}
}
}
}
}
// Print the Agent output and add the annotation at the end.
Console.WriteLine($"Response status: {response.Status}");
Console.WriteLine($"{response.GetOutputText()}{annotation}");
// After the sample is completed, delete the Agent we have created.
projectClient.AgentAdministrationClient.DeleteAgentVersion(agentName: agentVersion.Name, agentVersion: agentVersion.Version);
Oczekiwane dane wyjściowe
Po uruchomieniu tego kodu zobaczysz dane wyjściowe podobne do następujących:
The Contoso whistleblower policy outlines procedures for reporting unethical behavior confidentially. Employees can submit concerns through the ethics hotline or online portal. [Whistleblower Policy](https://contoso.sharepoint.com/sites/policies/Documents/whistleblower-policy.pdf)
Dane wyjściowe obejmują odpowiedź agenta uziemiona w zawartości SharePoint z linkiem cytatu do dokumentu źródłowego.
Hostowani agenci
W tym przykładzie użyto platformy Microsoft Agent Framework oraz wywołano AsAIAgent(...) na AIProjectClient wraz z FoundryAITool.CreateSharepointTool(...) z Microsoft.Agents.AI.Foundry. Zainstaluj pakiety Microsoft.Agents.AI.Foundry i Azure.AI.Projects, ustaw AZURE_AI_PROJECT_ENDPOINT, AZURE_AI_MODEL_DEPLOYMENT_NAME i SHAREPOINT_PROJECT_CONNECTION_ID zmiennych środowiskowych i zaloguj się przy użyciu az login.
using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Foundry;
string sharepointConnectionId = Environment.GetEnvironmentVariable("SHAREPOINT_PROJECT_CONNECTION_ID")
?? throw new InvalidOperationException("SHAREPOINT_PROJECT_CONNECTION_ID is not set.");
string endpoint = Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT")
?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT is not set.");
string deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-5-mini";
const string AgentInstructions = """
You are a helpful agent that can use SharePoint tools to assist users.
Use the available SharePoint tools to answer questions and perform tasks.
""";
var sharepointOptions = new SharePointGroundingToolOptions();
sharepointOptions.ProjectConnections.Add(new ToolProjectConnection(sharepointConnectionId));
AIProjectClient aiProjectClient = new(new Uri(endpoint), new DefaultAzureCredential());
AIAgent agent = aiProjectClient.AsAIAgent(deploymentName,
instructions: AgentInstructions,
name: "SharePointAgent",
tools: [FoundryAITool.CreateSharepointTool(sharepointOptions)]);
AgentResponse response = await agent.RunAsync("List the documents available in SharePoint");
Console.WriteLine($"Response: {response.Text}");
// Print any URL citations returned by the SharePoint grounding tool.
foreach (AIAnnotation annotation in response.Messages
.SelectMany(m => m.Contents)
.SelectMany(c => c.Annotations ?? []))
{
if (annotation.RawRepresentation is UriCitationMessageAnnotation urlCitation)
{
Console.WriteLine($"URL Citation: [{urlCitation.Title}]({urlCitation.Uri})");
}
}
Oczekiwane dane wyjściowe
Tekst odpowiedzi jest drukowany wraz z dowolnymi cytatami adresu URL zwróconymi przez narzędzie SharePoint:
Response: Based on the documents in SharePoint ...
URL Citation: [Whistleblower Policy](https://contoso.sharepoint.com/sites/policies/Documents/whistleblower-policy.pdf)
Aby zapoznać się z pełnym przykładem, zobacz Agent_Step19_SharePoint.
Przykład użycia agenta z SharePoint
Uzyskiwanie tokenu dostępu:
export AGENT_TOKEN=$(az account get-access-token --scope "https://ai.azure.com/.default" --query accessToken -o tsv)
W poniższym przykładzie pokazano, jak utworzyć agenta, który korzysta z narzędzia SharePoint, aby odpowiedzi były oparte na zawartości z witryny SharePoint.
curl --request POST \
--url "$FOUNDRY_PROJECT_ENDPOINT/openai/v1/responses" \
-H "Authorization: Bearer $AGENT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"model": "'$FOUNDRY_MODEL_DEPLOYMENT_NAME'",
"input": "Please summarize the last meeting notes stored in SharePoint.",
"tool_choice": "required",
"tools": [
{
"type": "sharepoint_grounding_preview",
"sharepoint_grounding_preview": {
"project_connections": [
{
"project_connection_id": "'$SHAREPOINT_PROJECT_CONNECTION_ID'"
}
]
}
}
]
}'
Oczekiwane dane wyjściowe
Interfejs API zwraca odpowiedź JSON z odpowiedzią agenta i informacjami o cytowaniu.
{
"id": "resp_abc123xyz",
"object": "response",
"created_at": 1702345678,
"status": "completed",
"output": [
{
"id": "msg_abc123xyz",
"type": "message",
"role": "assistant",
"status": "completed",
"content": [
{
"type": "output_text",
"text": "Based on the meeting notes...",
"annotations": [
{
"type": "url_citation",
"url": "https://contoso.sharepoint.com/sites/policies/Documents/meeting-notes.docx",
"start_index": 0,
"end_index": 245
}
]
}
]
}
]
}
W tym przykładzie pokazano, jak utworzyć agenta sztucznej inteligencji z funkcjonalnościami SharePoint. Agent może wyszukiwać zawartość SharePoint i dostarczać odpowiedzi z odpowiednimi informacjami z witryn SharePoint. Aby zapoznać się z wersją języka JavaScript, odnieś się do przykładowej dokumentacji agenta SharePoint w repozytorium Azure SDK dla JavaScript na GitHub.
import { DefaultAzureCredential } from "@azure/identity";
import { AIProjectClient } from "@azure/ai-projects";
// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
const PROJECT_ENDPOINT = "your_project_endpoint";
const SHAREPOINT_CONNECTION_NAME = "my-sharepoint-connection";
export async function main(): Promise<void> {
// Create clients to call Foundry API
const project = new AIProjectClient(PROJECT_ENDPOINT, new DefaultAzureCredential());
const openai = project.getOpenAIClient();
// Get connection ID from connection name
const sharepointConnection = await project.connections.get(SHAREPOINT_CONNECTION_NAME);
// Create agent with SharePoint tool
const agent = await project.agents.createVersion("MyAgent", {
kind: "prompt",
model: "gpt-4.1-mini",
instructions:
"You are a helpful agent that can use SharePoint tools to assist users. Use the available SharePoint tools to answer questions and perform tasks.",
// Define SharePoint tool that searches SharePoint content
tools: [
{
type: "sharepoint_grounding_preview",
sharepoint_grounding_preview: {
project_connections: [
{
project_connection_id: sharepointConnection.id,
},
],
},
},
],
});
console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);
// Send initial request that will trigger the SharePoint tool
const streamResponse = await openai.responses.create(
{
input: "Please summarize the last meeting notes stored in SharePoint.",
stream: true,
},
{
body: {
agent_reference: { name: agent.name, type: "agent_reference" },
tool_choice: "required",
},
},
);
// Process the streaming response
for await (const event of streamResponse) {
if (event.type === "response.created") {
console.log(`Follow-up response created with ID: ${event.response.id}`);
} else if (event.type === "response.output_text.delta") {
process.stdout.write(event.delta);
} else if (event.type === "response.output_text.done") {
console.log("\n\nFollow-up response done!");
} else if (event.type === "response.output_item.done") {
if (event.item.type === "message") {
const item = event.item;
if (item.content && item.content.length > 0) {
const lastContent = item.content[item.content.length - 1];
if (lastContent.type === "output_text" && lastContent.annotations) {
for (const annotation of lastContent.annotations) {
if (annotation.type === "url_citation") {
console.log(
`URL Citation: ${annotation.url}, Start index: ${annotation.start_index}, End index: ${annotation.end_index}`,
);
}
}
}
}
}
} else if (event.type === "response.completed") {
console.log("\nFollow-up completed!");
}
}
// Clean up resources
await project.agents.deleteVersion(agent.name, agent.version);
}
main().catch((err) => {
console.error("The sample encountered an error:", err);
});
Oczekiwane dane wyjściowe
Po uruchomieniu tego kodu zobaczysz dane wyjściowe podobne do następujących:
Creating agent with SharePoint tool...
Agent created (id: asst_abc123, name: MyAgent, version: 1)
Sending request to SharePoint agent with streaming...
Follow-up response created with ID: resp_xyz789
Based on the meeting notes from your SharePoint site, the last meeting covered the following topics: project timeline updates, budget review, and next quarter planning.
Follow-up response done!
URL Citation: https://contoso.sharepoint.com/sites/policies/Documents/meeting-notes.docx, Start index: 0, End index: 245
Follow-up completed!
Cleaning up resources...
Agent deleted
SharePoint agent sample completed!
Używanie integracji SharePoint w agencie języka Java
Dodaj zależność do swojego elementu pom.xml:
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-ai-agents</artifactId>
<version>2.4.0</version>
</dependency>
Utwórz agenta na podstawie SharePoint
import com.azure.ai.agents.AgentsClient;
import com.azure.ai.agents.AgentsClientBuilder;
import com.azure.ai.agents.ResponsesClient;
import com.azure.ai.agents.models.*;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.openai.models.responses.Response;
import com.openai.models.responses.ResponseCreateParams;
import java.util.Arrays;
import java.util.Collections;
public class SharePointGroundingExample {
public static void main(String[] args) {
// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
String projectEndpoint = "your_project_endpoint";
String sharepointConnectionId = "your_sharepoint_connection_id";
AgentsClientBuilder builder = new AgentsClientBuilder()
.credential(new DefaultAzureCredentialBuilder().build())
.endpoint(projectEndpoint);
AgentsClient agentsClient = builder.buildAgentsClient();
ResponsesClient responsesClient = builder.buildResponsesClient();
// Create SharePoint grounding tool with connection configuration
SharepointPreviewTool sharepointTool = new SharepointPreviewTool(
new SharepointGroundingToolParameters()
.setProjectConnections(Arrays.asList(
new ToolProjectConnection(sharepointConnectionId)
))
);
// Create agent with SharePoint tool
PromptAgentDefinition agentDefinition = new PromptAgentDefinition("gpt-4.1-mini")
.setInstructions("You are a helpful assistant that can search through SharePoint documents.")
.setTools(Collections.singletonList(sharepointTool));
AgentVersionDetails agent = agentsClient.createAgentVersion("sharepoint-agent", agentDefinition);
System.out.printf("Agent created: %s (version %s)%n", agent.getName(), agent.getVersion());
// Create a response
AgentReference agentReference = new AgentReference(agent.getName())
.setVersion(agent.getVersion());
Response response = responsesClient.createAzureResponse(
new AzureCreateResponseOptions().setAgentReference(agentReference),
ResponseCreateParams.builder()
.input("Find the latest project documentation in SharePoint"));
System.out.println("Response: " + response.output());
// Clean up
agentsClient.deleteAgentVersion(agent.getName(), agent.getVersion());
}
}
Ograniczenia
- Narzędzie SharePoint obsługuje tylko uwierzytelnianie tożsamości użytkowników. Uwierzytelnianie tylko dla aplikacji (jednostki usługi) nie jest obsługiwane.
- Witryna SharePoint i agent Microsoft Foundry muszą znajdować się w tej samej dzierżawie.
- Można dodać tylko jedno narzędzie SharePoint dla każdego agenta.
- Bazowy interfejs API pobierania Microsoft Copilot zwraca fragmenty tekstu. Nie obsługuje pobierania z zawartości nietekstowej, w tym obrazów i wykresów.
- W przypadku wyszukiwania semantycznego i hybrydowego interfejs API usługi Microsoft Copilot Retrieval obsługuje typy plików
.doc,.pdf,.aspx,.docx,.pptxi.one. Aby uzyskać szczegółowe informacje, zobacz interfejs API Microsoft Copilot. - Podstawowy interfejs API pobierania zwraca co najwyżej 25 wyników i umożliwia 200 żądań na użytkownika na godzinę. Ciąg zapytania może zawierać co najwyżej 1500 znaków.
Jak to działa
Narzędzie SharePoint umożliwia bezproblemowe integrowanie agentów sztucznej inteligencji i dokumentów biznesowych przechowywanych w SharePoint. Ta funkcja jest obsługiwana przez interfejs API usługi Microsoft Copilot. Aby zarządzać dokumentami SharePoint, wprowadź witryny lub foldery, z którymi chcesz nawiązać połączenie. Narzędzie SharePoint wykorzystuje wbudowane funkcje indeksowania w celu ulepszenia środowiska wyszukiwania i pobierania, w tym inteligentne indeksowania, przetwarzania zapytań i fragmentowania zawartości.
Aby uzyskać więcej informacji na temat delegowanego dostępu i przekazywania tożsamości w rozwiązaniu Foundry, zobacz Pojęcia dotyczące tożsamości agenta w rozwiązaniu Microsoft Foundry.
Zamiast wymagać od deweloperów eksportowania zawartości SharePoint, tworzenia niestandardowego indeksu semantycznego, zarządzania kontrolkami ładu i konfigurowania logiki odświeżania, ta funkcja automatyzuje cały potok pobierania. Dynamicznie indeksuje dokumenty, dzieli zawartość na znaczące fragmenty i stosuje zaawansowane przetwarzanie zapytań w celu uwidocznienia najbardziej odpowiednich informacji. Korzystając z tego samego korporacyjnego mechanizmu wyszukiwania i pobierania danych, który stanowi podstawę działania Microsoft Copilot, ta możliwość zapewnia, że odpowiedzi agenta AI opierają się na najbardziej aktualnych i odpowiednich kontekstowo treściach.
Klienci korzystają z zabezpieczeń danych w SharePoint w celu uzyskiwania dostępu do dokumentów, tworzenia i udostępniania dokumentów za pomocą elastycznej kontroli dostępu na poziomie dokumentu. Funkcje przedsiębiorstwa, takie jak przekazywanie tożsamości (W imieniu) uwierzytelniania, zapewniają właściwą kontrolę dostępu. Użytkownicy końcowi otrzymują odpowiedzi wygenerowane na podstawie SharePoint dokumentów, do których mają uprawnienia dostępu. Używając uwierzytelniania OBO, agent usługi Foundry wykorzystuje tożsamość użytkownika końcowego do autoryzacji i pobierania odpowiednich dokumentów SharePoint, tworząc odpowiedzi dostosowane do specyficznych użytkowników końcowych.
Rozwiązywanie problemów
| Problematyka | Przyczyna | Rezolucja |
|---|---|---|
AuthenticationError: AppOnly OBO tokens not supported by target service |
Używanie tożsamości aplikacji zamiast tożsamości użytkownika | Narzędzie SharePoint wymaga tożsamości użytkownika (przekazywanie tożsamości). Nie używaj uwierzytelniania tylko dla aplikacji. |
Forbidden: Authorization Failed - User does not have valid license |
Nieposiadanie licencji Microsoft 365 Copilot lub modelu płatności według rzeczywistego użycia | Przypisz licencję Microsoft 365 Copilot do użytkownika lub włącz płatność zgodnie z rzeczywistym użyciem. Zobacz Wymagania wstępne. |
| Błędy 401 lub uwierzytelniania | Próba dostępu między najemcami | Upewnij się, że użytkownik w rozwiązaniu Foundry i Microsoft 365 znajduje się w tej samej dzierżawie. |
| Narzędzie nie zwraca żadnych wyników | Użytkownik nie ma dostępu do zawartości SharePoint | Sprawdź, czy użytkownik ma dostęp do odczytu do witryn SharePoint i dokumentów, których dotyczy zapytanie. |
| Powolne czasy odpowiedzi | Duży zakres wyszukiwania dokumentów | Zawęź zakres wyszukiwania, określając określone witryny lub biblioteki. Rozważ użycie bardziej szczegółowych zapytań wyszukiwania. |
| Pobieranie niekompletnego dokumentu | Zawartość nieindeksowana | Upewnij się, że zawartość SharePoint jest indeksowana przez Microsoft Search. Ostatnio dodana zawartość może wymagać czasu na indeksowanie. |
Resource not found Błędy |
Nieprawidłowa ścieżka witryny lub biblioteki | Sprawdź, czy adres URL witryny i ścieżki biblioteki witryny SharePoint są poprawne i dostępne dla użytkownika. |
| Niespójne wyniki wyszukiwania | Opóźnienie synchronizacji indeksu semantycznego | Poczekaj na zsynchronizowanie indeksu semantycznego. Propagowanie dużych zmian zawartości może zająć trochę czasu. Zobacz Indeksowanie semantyczne dla Microsoft Copilot. |