Running Scripts Inside Copilot Studio Skills: Understanding the New Agent Sandbox

Copilot Studio agents can now do more than generate text. With the new agent experience, a Skill can include executable scripts, templates, reference files, and other resources. Python code can perform calculations, process documents, validate data, and generate complete files inside an isolated execution environment.

From the SharePoint Sandbox to the Copilot Studio Agent Sandbox

For experienced SharePoint developers, the term sandbox is not new. SharePoint Server introduced sandboxed solutions as a way to execute custom code outside the main SharePoint IIS worker process. Instead of loading an assembly into w3wp.exe, SharePoint executed it in the separate and monitored SPUCWorkerProcess.exe process. Quotas, throttling, and a reduced API surface helped prevent custom code from destabilizing the entire farm.

The new Copilot Studio Agent Sandbox follows a similar architectural principle: custom or AI-generated code should not execute directly inside the core service. It runs in a separate, controlled environment with clearly defined boundaries.

The technologies are otherwise completely unique. The SharePoint sandbox was designed for deploying restricted .NET solutions to SharePoint Server. The Copilot Studio sandbox is a temporary working environment in which an agent can inspect files, execute scripts, calculate exact results, and create new artifacts.

Why script execution is important for AI Agents

Large language models are excellent at understanding instructions, interpreting unstructured information, and selecting an appropriate approach. However, they are not deterministic calculation or file-generation engines.

For example, asking a language model to manually construct a complex PDF, calculate totals across thousands of spreadsheet rows, or produce a byte-perfect Office document can lead to inconsistent results. A Python script can execute the same operation in a predictable and testable way.

Agents powered by the GitHub Copilot harness can use a managed sandbox containing a Python runtime, local file storage, preinstalled libraries, and command-line tools. The agent can write code, execute it, inspect the results, correct problems, and run it again. A Copilot Studio skill can also package an already reviewed script so that the agent does not need to generate the implementation each time.

This creates two different execution patterns:

Agent-generated code: The agent dynamically creates Python code for a new or unfamiliar task. This is flexible, but the implementation can vary between executions.
A packaged skill script: A tested Python script is included in the skill package. This approach is preferable for repeatable business processes that require consistent behavior.

A skill can be uploaded as a ZIP package containing a SKILL.md file together with optional folders such as scripts, assets, and references. The skill description acts as routing information: when a request matches the description, the agent loads the skill and follows its instructions.

Useful Scenarios for Python Scripts in Skills

Script execution opens many practical scenarios that previously required a separate Azure Function or another externally hosted component.

1. Reliable business calculations

Calculate working days while considering weekends and regional holidays.
Calculate prorated bonuses, discounts, taxes, interest, or depreciation.
Validate formulas and compare calculated results against business rules.
Run simulations and what-if analyses with different input values.

2. Spreadsheet processing

Clean and normalize imported CSV or Excel data.
Remove duplicates and detect missing or invalid values.
Calculate totals, averages, trends, and grouped summaries.
Create charts or a new formatted workbook.
Compare two exports and generate a difference report.

3. PDF and document generation

Populate a PDF form with user or workflow data.
Create invoices, leave requests, certificates, or inspection reports.
Extract text and metadata from PDF files.
Compare Word documents and produce a redlined version.
Validate that required fields and sections exist in a document.

4. Data extraction and transformation

Extract identifiers, dates, addresses, or reference numbers from text.
Convert data between CSV, JSON, XML, and other formats.
Transform an export into the schema expected by another application.
Generate QR codes, charts, diagrams, or other image-based outputs.

5. Quality and compliance checks

Validate naming conventions and required metadata.
Check documents against a defined checklist.
Scan HTML for broken structures or accessibility issues.
Generate a machine-readable validation report with exact findings.

How the isolated execution model works

The sandbox should be treated as a temporary local workspace assigned to an agent execution. A typical skill run follows this sequence:

The agent determines that a skill matches the request.
The skill instructions and required resources are loaded.
The script runs inside the managed sandbox.
The script reads local input files or bundled templates.
The script creates an output file in the sandbox file system.
The agent inspects or validates the result.
The result is returned to the user or handed to an approved external tool.

The sandbox is not permanent storage. Files should not be expected to remain available after the execution or conversation ends. Agent Memory can preserve facts and conversational context, but it does not preserve sandbox files.

Generated files are also subject to platform limits. Microsoft currently documents a maximum size of 10 MB per file created during an agent turn. Larger files are not returned to the user.

The most important restriction: No outbound network access

Python code running inside the Copilot Studio sandbox does not have a general outbound network path. A script cannot directly call Microsoft Graph, send an email, connect to an external REST API, or upload a document to SharePoint.

This remains true even if a Python HTTP library such as requests is available. Importing an HTTP client does not remove the network boundary.

External communication must take place through governed capabilities configured for the agent, including:

Power Platform connectors
Agent Flows or Power Automate flows
Model Context Protocol servers
Custom connectors
Other tools explicitly assigned to the agent

This distinction is important for administrators. The Microsoft 365 and Copilot network requirements define which endpoints must be reachable from users' devices and organizational networks. For example, Microsoft requires the relevant Microsoft 365 endpoints and WebSocket connectivity to domains such as *.cloud.microsoft and *.office.com. Agent authoring can additionally require access to *.api.powerplatform.com.

Allowing these endpoints in the corporate firewall does not enable arbitrary network access from a Python script running inside the sandbox. Client connectivity and sandbox egress are two separate security boundaries.

Why an Access Token does not solve the problem

A Python script cannot directly upload a generated file to SharePoint merely because it knows the SharePoint URL. It would normally require a Microsoft Entra access token containing the appropriate Microsoft Graph or SharePoint permissions.

However, an access token should not be passed into a skill or written to a sandbox file. More importantly, even if a token were supplied, the sandbox's network isolation would still prevent the script from calling the SharePoint or Microsoft Graph endpoint.

Authentication should therefore be handled outside the script by a governed tool, connector, Power Automate connection, managed identity, or registered application. The skill should concentrate on local processing; the integration component should handle authentication and external communication.

A PDF-generation skill as an example

A skill that generates a completed leave-request PDF illustrates both the power of script execution and the current integration boundary.

The skill contains:

A fillable PDF template.
A Python script that populates and verifies the form.
A SKILL.md file describing the required inputs and output contract.

The script receives information such as the employee name, department, leave dates, duration, state, and manager email address. It uses a PDF library to populate the fields, writes the completed document to a local output path, reopens the result, and verifies that the values and page count are correct.

It can also return useful integrity information:

{
  "status": "success",
  "output": "/sandbox/output/generated-document.pdf",
  "media_type": "application/pdf",
  "size_bytes": 162955,
  "sha256": "..."
}

This is an excellent use of a script because the result must be a valid binary PDF rather than a text approximation generated by the language model.

However, the local output path is only meaningful inside the sandbox. It is not automatically a file reference that SharePoint, Power Automate, or a Copilot Studio workflow can resolve.

Chat mode vs. workflow invocation

A file-generating skill can behave differently depending on how the agent is invoked.

Execution mode	Behavior	File-handling consequence
Interactive agent chat	The agent, sandbox, generated file, and configured tools participate in the same conversational turn.	The agent can return the generated document to the user and may be able to pass the active artifact to a compatible upload tool.
Agent called from a Copilot Studio workflow	The workflow invokes the agent as a processing node and waits for its configured response.	The workflow receives text or structured fields, but not direct access to the agent's temporary sandbox file system.

In chat mode, the active agent harness can maintain the relationship between the generated document and a subsequent tool call. The file remains an artifact of the current agent turn, allowing the agent to return it or hand it to a compatible tool.

When the published agent is called from a Copilot Studio workflow, the agent node behaves more like a function. Microsoft currently exposes three workflow output shapes:

Text response
Structured output
Custom structured output based on a JSON schema

A native file output is not currently listed for this workflow node. Consequently, a local value /sandbox/output/generated-document.pdfis only a path within the agent sandbox. It is not a portable file reference that the surrounding workflow or a later SharePoint action can resolve.

The `folder_path` problem

This difference becomes visible when an agent contains a SharePoint Create file tool. The operation may work when the agent is used interactively in chat, but it fails when the same agent is invoked from a workflow.

The upload operation cannot access the sandbox's folder_path or local file path from the surrounding workflow context. The path identifies a location inside the temporary sandbox container. It is not:

A SharePoint folder URL
A workflow-accessible file identifier
A downloadable public URL
The binary content of the generated document
A durable reference that remains valid after the agent finishes

Passing the path as text does not transfer the file itself. This approach is similar to returning C:\Temp\document.pdf from one computer and expecting a cloud flow running on another machine to open it.

Important: The precise folder_path behavior is an observed limitation of this workflow scenario. Microsoft documents the temporary sandbox, its lack of outbound network access, and the workflow node's text and structured outputs, but the specific path error is not currently described as a formal product limitation.

General design challenges for file-generating skills

The PDF scenario is only one example. The same challenges apply when a skill generates Word documents, Excel workbooks, presentations, images, ZIP archives, reports, or other binary artifacts.

A path is not a file: Returning a local sandbox path does not transfer the binary content to another service.
Sandbox files are temporary: A later workflow step must not assume that the sandbox or its files still exist.
Different invocation modes expose different contracts: A file that can be returned in chat might not be available as a workflow output.
External uploads require a governed bridge: SharePoint, OneDrive, Dataverse, and other services must be accessed through tools, connectors, flows, or external APIs.
Dependencies must be available locally: Scripts should not assume that missing Python packages can be downloaded from public repositories.
Binary content should not be printed into the model context: Large base64 strings increase token usage and can be truncated or rejected.
File-size limits still apply: Documents must remain within the limits of the agent, connector, workflow, and destination service.

Alternative Solution 1: Return data and let Power Automate create the document

One of the most reliable low-code designs is to separate reasoning from document generation.

The agent extracts and validates the required information.
The agent returns a structured object containing the validated values.
The workflow passes these values to a Power Automate flow.
The flow populates a Word template or another supported document template.
The flow converts the generated document to PDF when required.
The destination connector creates the file in SharePoint, OneDrive, or another system.

This avoids transporting a sandbox path entirely. Authentication remains inside the connector connection, and the workflow owns the durable file.

The following video demonstrate this approach.

The disadvantage is that an existing PDF template or specialized Python implementation might need to be replaced or redesigned.

Alternative Solution 2: Use a File-Aware Agent Flow as a Bridge

Copilot Studio and Power Automate can pass files using an object containing the filename and content, for example:

{
  "name": "generated-document.pdf",
  "contentBytes": "<binary or Base64 content>"
}

A bridge flow can accept this file object and use a SharePoint, OneDrive, Outlook, or another connector to store or transmit it. Some connector scenarios require converting Base64 with base64ToBinary().

This pattern is suitable only if the active invocation channel can bind the generated sandbox artifact to a genuine file input. Supplying the local path as contentBytes does not work. It is therefore important to test the complete route from the skill to the tool, not merely the flow in isolation.

Large base64 strings should not be printed into the agent response or copied through the language-model context. Besides increasing token consumption, this approach is fragile and can exceed output limits.

Alternative sSolution 3: Move document generation to an Azure bridge

For a robust production architecture, an Azure Function, Azure Container App, or similar API can perform the deterministic file generation outside the agent sandbox.

The agent or workflow sends validated structured data to the bridge through a custom connector or tool.
The bridge loads the required template and executes the document-generation code.
The bridge uploads the result to the destination by using a managed identity or application registration.
The bridge returns a durable file ID, URL, filename, byte size, and optional hash.

This provides complete control over Python packages, runtime versions, monitoring, retry logic, file sizes, and authentication. It is particularly suitable for automatically generating documents from workflows without an interactive chat session.

Alternative Solution 4: Use an MCP Server or Custom Connector

An MCP server or custom connector can expose a dedicated operation such as generateAndStoreDocument. The operation receives structured business data, generates the requested file, uploads it to the destination, and returns a durable result.

From the sandbox's perspective, the request is an approved tool invocation rather than a direct network request. Authentication and authorization remain in the external integration layer.

This approach is useful when multiple agents need the same document-generation capability or when the operation should be governed and versioned as a reusable enterprise service.

Requirement	Recommended design
Interactive chat with a downloadable result	Generate the file inside the skill and return it as an artifact of the current agent turn.
Interactive chat with immediate upload	Generate the file inside the skill and invoke a compatible upload tool during the same turn, after validating the complete binary handoff.
Automated Copilot Studio workflow	Return structured business data and let the workflow generate and store the document.
An existing PDF or specialized template must be preserved.	Move the generation script to an Azure Function, custom connector, or MCP-based bridge.
Multiple agents need the same capability.	Create a reusable document service that combines generation, validation, storage, and audit logging.
Large files or special libraries are required.	Use an externally hosted service with controlled runtime, storage, package management, and scaling.

Security and design recommendations

Never place client secrets, access tokens, or destination credentials inside a Skill package.
Do not pass authentication tokens to Python through command-line parameters or temporary files.
Treat sandbox paths as internal implementation details, not integration contracts.
Use tools and connectors for every external action.
Prefer managed identities or certificate-based application authentication for custom bridge services.
Validate filenames, file types, and target folders before uploading.
Restrict bridge services to approved sites, libraries, and storage locations.
Retain the generated file's byte size and hash when document integrity matters.
Test chat and workflow invocation separately; success in the test chat does not guarantee success inside a workflow.
Use Copilot Studio evaluations and workflow test runs to validate tool selection, output structure, and error handling.

Conclusion

Executable scripts in Copilot Studio skills represent a significant advancement. An agent can now combine language understanding with deterministic code execution: it can extract information, run an approved Python script, generate a real PDF or Office document, verify the result, and return a finished artifact.

The sandbox's restrictions are part of the design, not an accidental inconvenience. Code is isolated, storage is temporary, and scripts have no direct outbound network access. External actions must pass through governed tools.

The PDF-generation scenario in the above video illustrates why this boundary must be considered during architecture design. Generating a file inside a skill can work very well, and returning it during an interactive chat can also work. Calling the same agent from a workflow introduces another execution boundary: a local folder_path is not a transferable file, and the workflow node currently returns text or structured data rather than direct access to the sandbox file system.

For reliable file and document generation, design an explicit handoff. Let a Power Automate flow create the document from structured data, pass the binary through a supported file-aware tool, or move document generation and storage to a secured bridge service. With this separation, skills provide the procedural intelligence, scripts provide deterministic processing, and connectors provide controlled access to enterprise systems.

Dieses Blog durchsuchen

Mein Blick auf SharePoint & M365 & .NET aus der Sicht eines Full-Stack Entwicklers