Share via

I can't seem to upload an Agent (zip file) on M365 Admin Center page (Copilot) due to "Invalid Declarative Agent Document"

Edward 21 Reputation points
2026-04-06T19:21:04.85+00:00

Hello,

We have an Agent created by another user (via the "Agent Builder" aka "Create Agent" button on Copilot chat page). We were looking to deploy this and publish it to few groups on M365 Admin Center page -> Copilot -> Agents.

When we attempted uploading, the zip file, it would run into the following error:

User's image

After checking the json files in the zip file and testing with other Agents with various knowledge/sources, it looks like this happens if a (local) file was uploaded. For agents that used a local file, its declarativeAgent_0.json has the attribute "additional_search_terms" and set to null. Other agents which didn't use a local file have that attribute missing.

User's image

Microsoft Copilot | Microsoft 365 Copilot | Development

2 answers

Sort by: Most helpful
Most helpful Newest Oldest
  1. Sayali-MSFT 5,281 Reputation points Microsoft External Staff Moderator
    2026-04-07T08:49:04.29+00:00

    Hello Edward,
    This issue is caused by a schema mismatch between Agent Builder exports and the M365 Admin Center upload validator when local files are used as knowledge sources. The exported agent JSON includes an unsupported additional_search_terms field (set to null), which the Admin Center schema does not recognize, resulting in a validation error during upload. Agents without local files work because the field is omitted, and manually removing it resolves the issue.
    This behavior indicates a platform bug rather than a configuration problem, with current workarounds being manual JSON cleanup or avoiding local file uploads.

    We have reported this as a bug for further investigation. 

    We will keep you updated as soon as we receive further information. Thank you for bringing this to our attention! 

    0 comments
  2. Q&A Assist
    2026-04-06T19:21:46.6133333+00:00
    AI generated content. This question contains an answer created with AI from Q&A Assist. Learn more

    Invalid Declarative Agent Document during upload means the ZIP package does not match the schema that Microsoft 365 admin center expects for declarative agents.

    From the provided details, the failure is triggered by the additional_search_terms member in declarativeAgent_0.json. Admin center validates the declarative agent document and rejects unrecognized or invalid properties. When a local file is added as a knowledge source, Agent Builder is currently generating an additional_search_terms property that is either null or otherwise not supported in the upload schema, so the manifest fails validation.

    To successfully upload and deploy the agent via Microsoft 365 admin center:

    1. Regenerate the ZIP package without embedded/local files
      • In Agent Builder, remove any uploaded local file knowledge sources from the agent.
      • Ensure only supported knowledge sources (for example, SharePoint, Teams, websites, or other configured sources) remain.
      • Download a fresh ZIP package for deployment.
      • Upload this new ZIP in Microsoft 365 admin center → Copilot → Agents → All agents → Upload custom agent.
    2. Use supported ZIP packages for deployment
      • For agents created in Agent Builder, the ZIP package is intended for sideloading into Microsoft Teams and for admin upload only when it conforms to the supported schema. The documentation explicitly notes that deployment ZIPs cannot include embedded files.
      • If the agent must use local content, move that content into a supported knowledge source (for example, upload the files to SharePoint or OneDrive and connect that location as a knowledge source), then rebuild and re-download the agent package.
    3. If the error persists after removing local files
      • Recreate the agent in Agent Builder using only supported knowledge sources and capabilities.
      • Download the new ZIP and upload again.

    Once the ZIP validates and uploads successfully, use the Copilot Control System in Microsoft 365 admin center to assign and deploy the agent to users or groups as needed.

    References:

Your answer

Answers can be marked as 'Accepted' by the question author and 'Recommended' by moderators, which helps users know the answer solved the author's problem.