Uso de SharePoint herramienta con la API del agente (versión preliminar)

En el ejemplo siguiente se muestra cómo crear un agente que use la herramienta de SharePoint para basar las respuestas en el contenido de un sitio de SharePoint. Seleccione Prompt Agents para usar Azure AI Projects SDK y crear un agente de indicaciones del lado del servidor, o Hosted Agents para usar el Agent Framework FoundryChatClient y crear un agente efímero dentro del proceso.

Agentes rápidos

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"
SHAREPOINT_CONNECTION_NAME = "my-sharepoint-connection"

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# 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="MyAgent",
    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})")

# 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.",
    extra_body={"agent_reference": {"name": agent.name, "type": "agent_reference"}},
)

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}")

Salida esperada

Al ejecutar este código, verá una salida similar a la siguiente:

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.

Agentes hospedados

En este ejemplo se usa FoundryChatClient del Microsoft Agent Framework y se llama a get_sharepoint_tool() para asociar una conexión de puesta a tierra de SharePoint. Usa AIProjectClient para resolver el nombre de conexión a un identificador de conexión y, a continuación, itera las anotaciones de mensaje para imprimir citas de dirección URL. Instale el paquete con pip install agent-framework-foundry aiohttp, establezca las FOUNDRY_PROJECT_ENDPOINT variables de entorno y FOUNDRY_MODEL e inicie sesión con 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())

Salida esperada

El texto de la respuesta se imprime junto con las citas de dirección URL que devolvió la herramienta de base de 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)

Para obtener más información sobre las factorías de herramientas de Agent Framework Foundry, consulte los ejemplos del proveedor Foundry.

En el ejemplo siguiente se muestra cómo crear un agente que use la herramienta de SharePoint para basar las respuestas en el contenido de un sitio de SharePoint. En este ejemplo se usan métodos sincrónicos para simplificar. Para obtener una versión asincrónica, consulte la documentación de ejemplo del agente de SharePoint en el SDK de Azure para el repositorio de .NET GitHub.

Para permitir que el agente acceda a SharePoint, use SharepointPreviewTool. Seleccione Prompt Agents para usar el SDK de proyectos de IA de Azure para crear un agente de mensajes del lado servidor o Agentes hospedados para usar el marco del agente de Microsoft para crear un agente efímero en proceso.

Agentes rápidos

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);

Salida esperada

Al ejecutar este código, verá una salida similar a la siguiente:

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)

La salida incluye la respuesta del agente basada en el contenido de SharePoint, con un enlace de cita al documento de origen.

Agentes hospedados

En este ejemplo se usa el Microsoft Agent Framework y se realiza una llamada a AsAIAgent(...) en AIProjectClient junto con FoundryAITool.CreateSharepointTool(...) desde Microsoft.Agents.AI.Foundry. Instale los paquetes y , establezca el , y las variables de entorno /> .

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})");
    }
}

Salida esperada

El texto de la respuesta se imprime junto con cualquier cita URL que devuelva la herramienta SharePoint:

Response: Based on the documents in SharePoint ...
URL Citation: [Whistleblower Policy](https://contoso.sharepoint.com/sites/policies/Documents/whistleblower-policy.pdf)

Para obtener el ejemplo completo, consulte Agent_Step19_SharePoint.

Ejemplo para el uso de un agente con SharePoint

Obtención de un token de acceso:

export AGENT_TOKEN=$(az account get-access-token --scope "https://ai.azure.com/.default" --query accessToken -o tsv)

En el ejemplo siguiente se muestra cómo crear un agente que use la herramienta de SharePoint para basar las respuestas en contenido de un sitio de 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'"
          }
        ]
      }
    }
  ]
}'

Salida esperada

La API devuelve una respuesta JSON con la respuesta y la información de cita del agente:

{
  "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
            }
          ]
        }
      ]
    }
  ]
}

En este ejemplo se muestra cómo crear un agente de IA con funcionalidades de SharePoint. El agente puede buscar contenido de SharePoint y proporcionar respuestas con información relevante de sitios de SharePoint. Para obtener una versión de JavaScript, consulte la documentación de ejemplo del agente SharePoint en el repositorio de SDK de Azure para JavaScript 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);
});

Salida esperada

Al ejecutar este código, verá una salida similar a la siguiente:

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!

Uso de SharePoint como fundamento en un agente de Java

Agregue la dependencia a pom.xml:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-ai-agents</artifactId>
    <version>2.4.0</version>
</dependency>

Crear un agente con base en 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());
    }
}