Some products and features are in the process of being renamed. Generative playbook and flow features are also being migrated to a single consolidated console. See the details.
Stay organized with collections
Save and categorize content based on your preferences.
You can
export and restore agents
in the JSON package file format.
This format is ideal for agent source control versioning,
because the version differences can easily be reviewed and compared.
Limitations
The JSON package format is only available for export and restore of an agent,
not export and restore of individual flows.
Directory structure
An agent export is a zip file that contains a hierarchy
of directories and JSON files.
The following describes the directory structure:
entityTypes: This directory contains your entity types.
<entity type name>: One or more of these directories exist,
and the directory names correspond to entity type display names.
entities: This directory contains entity entry files.
<language tag>.json: One or more of these files exist,
and the file names correspond to language tags.
Each file contains language-specific entity entries.
<excludedPhrases>: This directory contains
excluded phrase
files.
<language tag>.json: One or more of these files exist,
and the file names correspond to language tags.
Each file contains language-specific phrase exclusions.
<entity type name>.json: This file name corresponds
to an entity type display name.
The file contains entity-type-specific data
not found in other files.
flows: This directory contains your flow data.
<flow name>: One or more of these directories exist,
and the directory names correspond to flow display names.
pages: This directory contains the page data for the flow.
<page name>.json: One or more of these files exist,
and the file names correspond to page display names.
Each file contains page-specific data.
transitionRouteGroups: This directory contains your
route group
data for the flow.
<route group name>: One or more of these files exist,
and the file names correspond to route group display names.
Each file contains route-group-specific data.
<flow name>.json: This file name corresponds
to a flow display name.
The file contains flow-specific data not found in other files.
intents: This directory contains your intent data.
<intent name>: One or more of these directories exist,
and the directory names correspond to intent display names.
trainingPhrases: This directory contains training phrase data.
<language tag>.json: One or more of these files exist,
and the file names correspond to language tags.
Each file contains language-specific training phrases
for the intent.
<intent name>.json: This file name corresponds
to an intent display name.
The file contains intent-specific data not found in other files.
testCases: This directory contains your test case data.
<test case name>.json: One or more of these files exist,
and the file names correspond to test case display names.
Each file contains test-case-specific data.
webhooks: This directory contains your webhook data.
<webhook name>.json: One or more of these files exist,
and the file names correspond to webhook display names.
Each file contains webhook-specific data.
agentTransitionRouteGroups: This directory contains your agent-level transition route group data.
<agent transition route group name>.json: One or more of these
files exist, and the file names correspond to
agent transition route group display names.
Each file contains agent-transition-route-group-specific data.
agent.json: This file contains agent-specific data
not found in other files.
When restoring an agent,
you must provide a zip file as described above.
Be sure that the agent.json and other top-level directories described above
are at the root directory of the zip file.
For example:
Good
Bad
/agent.json
/xxx/agent.json
/entityTypes
/xxx/entityTypes
Resource names
Some folder and JSON file names correspond to resource display names.
If a display name contains characters that are not allowed in file names
($, <, >, and so on),
these characters are
URL encoded
for the directory or file name.
Any JSON field that contains a resource reference is set to the
corresponding resource display name,
rather than the full resource name that includes the resource ID.
For example,
Parameter.entityType is set to the display name of an entity type,
rather than
projects/<Project ID>/locations/<Location ID>/agents/<Agent ID>/entityTypes/<Entity Type ID>.
If you edit a JSON file to change the display name
of any referenced resource,
be sure to update all the references to the resource as well.
JSON content format
Each JSON file mentioned above has a representation that corresponds to a
Dialogflow REST API resource in JSON form.
For example,
Webhook A.json contains a JSON representation of the
JSON form of the webhook resource
with a display name of Webhook A.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-07 UTC."],[[["\u003cp\u003eAgents can be exported and restored using a JSON package file format, which is suitable for agent source control versioning.\u003c/p\u003e\n"],["\u003cp\u003eThe exported agent is a zip file containing a structured hierarchy of directories and JSON files, organized by categories like \u003ccode\u003eentityTypes\u003c/code\u003e, \u003ccode\u003eflows\u003c/code\u003e, \u003ccode\u003eintents\u003c/code\u003e, \u003ccode\u003etestCases\u003c/code\u003e, \u003ccode\u003ewebhooks\u003c/code\u003e, \u003ccode\u003eagentTransitionRouteGroups\u003c/code\u003e, and a root \u003ccode\u003eagent.json\u003c/code\u003e file.\u003c/p\u003e\n"],["\u003cp\u003eEach directory within the exported zip file corresponds to a specific resource type, and each JSON file contains data for that resource, such as entity entries, pages, training phrases, or webhook details.\u003c/p\u003e\n"],["\u003cp\u003eWhen restoring an agent from a zip file, the \u003ccode\u003eagent.json\u003c/code\u003e file and other top-level directories must be at the root of the zip file to ensure proper restoration.\u003c/p\u003e\n"],["\u003cp\u003eWhile resource names are often represented by their display names in JSON files, changing a resource's display name requires updating all references to it within the JSON files.\u003c/p\u003e\n"]]],[],null,["# JSON package export format\n\nYou can\n[export and restore agents](/dialogflow/cx/docs/concept/agent#export)\nin the JSON package file format.\nThis format is ideal for agent source control versioning,\nbecause the version differences can easily be reviewed and compared.\n| **Note:** It is not recommended to directly edit the JSON text files, because format or value mistakes may result in a bad agent state.\n\nLimitations\n-----------\n\n| **Warning:** We will no longer export raw value credentials for OpenAPI Tools and Webhooks, starting Aug 15, 2025. You should migrate to store your credentials in Secret Manager. See [Webhook](/dialogflow/cx/docs/concept/webhook#secret-manager-auth) and [Tool](/dialogflow/cx/docs/concept/playbook/tool#secret-manager-auth) documentations for instructions.\n\nThe JSON package format is only available for export and restore of an agent,\nnot export and restore of individual flows.\n\nDirectory structure\n-------------------\n\nAn agent export is a zip file that contains a hierarchy\nof directories and JSON files.\nThe following describes the directory structure:\n\n- `entityTypes`: This directory contains your entity types.\n - `\u003centity type name\u003e`: One or more of these directories exist, and the directory names correspond to entity type display names.\n - `entities`: This directory contains entity entry files.\n - `\u003clanguage tag\u003e.json`: One or more of these files exist, and the file names correspond to language tags. Each file contains language-specific entity entries.\n - `\u003cexcludedPhrases\u003e`: This directory contains [excluded phrase](/dialogflow/cx/docs/concept/entity-options#exclusion) files.\n - `\u003clanguage tag\u003e.json`: One or more of these files exist, and the file names correspond to language tags. Each file contains language-specific phrase exclusions.\n - `\u003centity type name\u003e.json`: This file name corresponds to an entity type display name. The file contains entity-type-specific data not found in other files.\n- `flows`: This directory contains your flow data.\n - `\u003cflow name\u003e`: One or more of these directories exist, and the directory names correspond to flow display names.\n - `pages`: This directory contains the page data for the flow.\n - `\u003cpage name\u003e.json`: One or more of these files exist, and the file names correspond to page display names. Each file contains page-specific data.\n - `transitionRouteGroups`: This directory contains your [route group](/dialogflow/cx/docs/concept/handler#route-group) data for the flow.\n - `\u003croute group name\u003e`: One or more of these files exist, and the file names correspond to route group display names. Each file contains route-group-specific data.\n - `\u003cflow name\u003e.json`: This file name corresponds to a flow display name. The file contains flow-specific data not found in other files.\n- `intents`: This directory contains your intent data.\n - `\u003cintent name\u003e`: One or more of these directories exist, and the directory names correspond to intent display names.\n - `trainingPhrases`: This directory contains training phrase data.\n - `\u003clanguage tag\u003e.json`: One or more of these files exist, and the file names correspond to language tags. Each file contains language-specific training phrases for the intent.\n - `\u003cintent name\u003e.json`: This file name corresponds to an intent display name. The file contains intent-specific data not found in other files.\n- `testCases`: This directory contains your test case data.\n - `\u003ctest case name\u003e.json`: One or more of these files exist, and the file names correspond to test case display names. Each file contains test-case-specific data.\n- `webhooks`: This directory contains your webhook data.\n - `\u003cwebhook name\u003e.json`: One or more of these files exist, and the file names correspond to webhook display names. Each file contains webhook-specific data.\n- `agentTransitionRouteGroups`: This directory contains your agent-level transition route group data.\n - `\u003cagent transition route group name\u003e.json`: One or more of these files exist, and the file names correspond to agent transition route group display names. Each file contains agent-transition-route-group-specific data.\n- `agent.json`: This file contains agent-specific data not found in other files.\n\nFor example: \n\n```\nfolder entityTypes\n ⤷ folder Entity Type A\n ⤷ folder entities\n ⤷ insert_drive_file en.json\n ⤷ insert_drive_file en-gb.json\n ⤷ insert_drive_file en-ca.json\n ⤷ folder excludedPhrases\n ⤷ insert_drive_file en.json\n ⤷ insert_drive_file en-gb.json\n ⤷ insert_drive_file en-ca.json\n ⤷ insert_drive_file Entity Type A.json\n ⤷ folder Entity Type B\n ⤷ folder entities\n ⤷ insert_drive_file en.json\n ⤷ insert_drive_file en-gb.json\n ⤷ insert_drive_file en-ca.json\n ⤷ folder excludedPhrases\n ⤷ insert_drive_file en.json\n ⤷ insert_drive_file en-gb.json\n ⤷ insert_drive_file en-ca.json\n ⤷ insert_drive_file Entity Type B.json\nfolder flows\n ⤷ folder Flow A\n ⤷ folder pages\n ⤷ insert_drive_file Page A.json\n ⤷ insert_drive_file Page B.json\n ⤷ insert_drive_file Page C.json\n ⤷ folder transitionRouteGroups\n ⤷ insert_drive_file Route Group A.json\n ⤷ insert_drive_file Route Group B.json\n ⤷ insert_drive_file Route Group C.json\n ⤷ insert_drive_file Flow A.json\n ⤷ folder Flow B\n ⤷ folder pages\n ⤷ insert_drive_file Page D.json\n ⤷ insert_drive_file Page E.json\n ⤷ insert_drive_file Page F.json\n ⤷ folder transitionRouteGroups\n ⤷ insert_drive_file Route Group D.json\n ⤷ insert_drive_file Route Group E.json\n ⤷ insert_drive_file Route Group F.json\n ⤷ insert_drive_file Flow B.json\nfolder intents\n ⤷ folder Intent A\n ⤷ folder trainingPhrases\n ⤷ insert_drive_file en.json\n ⤷ insert_drive_file en-gb.json\n ⤷ insert_drive_file en-ca.json\n ⤷ insert_drive_file Intent A.json\n ⤷ folder Intent B\n ⤷ folder trainingPhrases\n ⤷ insert_drive_file en.json\n ⤷ insert_drive_file en-gb.json\n ⤷ insert_drive_file en-ca.json\n ⤷ insert_drive_file Intent B.json\nfolder testCases\n ⤷ insert_drive_file Test Case A.json\n ⤷ insert_drive_file Test Case B.json\nfolder webhooks\n ⤷ insert_drive_file Webhook A.json\n ⤷ insert_drive_file Webhook B.json\nfolder agentTransitionRouteGroups\n ⤷ insert_drive_file Agent Transition Route Group A.json\n ⤷ insert_drive_file Agent Transition Route Group B.json\ninsert_drive_file agent.json\n```\n\nAgent restore guidance\n----------------------\n\nWhen restoring an agent,\nyou must provide a zip file as described above.\nBe sure that the `agent.json` and other top-level directories described above\nare at the root directory of the zip file.\nFor example:\n\nResource names\n--------------\n\nSome folder and JSON file names correspond to resource display names.\nIf a display name contains characters that are not allowed in file names\n(`$`, `\u003c`, `\u003e`, and so on),\nthese characters are\n[URL encoded](https://developer.mozilla.org/en-US/docs/Glossary/percent-encoding)\nfor the directory or file name.\n\nAny JSON field that contains a resource reference is set to the\ncorresponding resource display name,\nrather than the full resource name that includes the resource ID.\nFor example,\n`Parameter.entityType` is set to the display name of an entity type,\nrather than\n`projects/\u003cProject ID\u003e/locations/\u003cLocation ID\u003e/agents/\u003cAgent ID\u003e/entityTypes/\u003cEntity Type ID\u003e`.\n\nIf you edit a JSON file to change the display name\nof any referenced resource,\nbe sure to update all the references to the resource as well.\n\nJSON content format\n-------------------\n\nEach JSON file mentioned above has a representation that corresponds to a\nDialogflow REST API resource in JSON form.\nFor example,\n`Webhook A.json` contains a JSON representation of the\n[JSON form of the webhook resource](/dialogflow/cx/docs/reference/rest/v3/projects.locations.agents.webhooks)\nwith a display name of `Webhook A`."]]
