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 .

Manage agents with the API

Normally, you create and delete agents using the console. However, in certain advanced scenarios, you may find it easier to use the API.

Create an agent

The following examples show how to call the Create method for the Agent type.

Select a protocol and version for the Agent reference:

Protocol	V3	V3beta1
REST	Agent resource	Agent resource
RPC	Agent interface	Agent interface
C++	AgentsClient	Not available
C#	AgentsClient	Not available
Go	AgentsClient	Not available
Java	AgentsClient	AgentsClient
Node.js	AgentsClient	AgentsClient
PHP	Not available	Not available
Python	AgentsClient	AgentsClient
Ruby	Not available	Not available

REST

Before using any of the request data, make the following replacements:

PROJECT_ID : your Google Cloud project ID
REGION_ID : your region ID

HTTP method and URL:

POST https:// REGION_ID 
-dialogflow.googleapis.com/v3/projects/ PROJECT_ID 
/locations/ REGION_ID 
/agents

Request JSON body:

{
  "displayName": "My display name",
  "defaultLanguageCode": "en",
  "timeZone": "America/New_York"
}

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell , which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list .

Save the request body in a file named request.json , and execute the following command:

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "x-goog-user-project: PROJECT_ID 
" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https:// REGION_ID 
-dialogflow.googleapis.com/v3/projects/ PROJECT_ID 
/locations/ REGION_ID 
/agents"

PowerShell (Windows)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list .

Save the request body in a file named request.json , and execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = " PROJECT_ID 
" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https:// REGION_ID 
-dialogflow.googleapis.com/v3/projects/ PROJECT_ID 
/locations/ REGION_ID 
/agents" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "name": "projects/ PROJECT_ID 
/locations/ REGION_ID 
/agents/ AGENT_ID 
",
  "displayName": "My display name",
  "defaultLanguageCode": "en",
  "timeZone": "America/New_York",
  "startFlow": "projects/ PROJECT_ID 
/locations/ REGION_ID 
/agents/ AGENT_ID 
/flows/00000000-0000-0000-0000-000000000000",
  "advancedSettings": {
    "loggingSettings": {}
  }
}

Java

To authenticate to Dialogflow, set up Application Default Credentials. For more information, see Set up authentication for a local development environment .

  import 
  
 com.google.cloud.dialogflow.cx.v3. Agent 
 
 ; 
 import 
  
 com.google.cloud.dialogflow.cx.v3. Agent 
.Builder 
 ; 
 import 
  
 com.google.cloud.dialogflow.cx.v3. AgentsClient 
 
 ; 
 import 
  
 com.google.cloud.dialogflow.cx.v3. AgentsSettings 
 
 ; 
 import 
  
 java.io.IOException 
 ; 
 public 
  
 class 
 CreateAgent 
  
 { 
  
 public 
  
 static 
  
 void 
  
 main 
 ( 
 String 
 [] 
  
 args 
 ) 
  
 throws 
  
 IOException 
  
 { 
  
 // TODO(developer): Replace these variables before running the sample. 
  
 String 
  
 projectId 
  
 = 
  
 "my-project-id" 
 ; 
  
 String 
  
 displayName 
  
 = 
  
 "my-display-name" 
 ; 
  
 createAgent 
 ( 
 projectId 
 , 
  
 displayName 
 ); 
  
 } 
  
 public 
  
 static 
  
  Agent 
 
  
 createAgent 
 ( 
 String 
  
 parent 
 , 
  
 String 
  
 displayName 
 ) 
  
 throws 
  
 IOException 
  
 { 
  
 String 
  
 apiEndpoint 
  
 = 
  
 "global-dialogflow.googleapis.com:443" 
 ; 
  
  AgentsSettings 
 
  
 agentsSettings 
  
 = 
  
  AgentsSettings 
 
 . 
 newBuilder 
 (). 
 setEndpoint 
 ( 
 apiEndpoint 
 ). 
 build 
 (); 
  
 // Note: close() needs to be called on the AgentsClient object to clean up resources 
  
 // such as threads. In the example below, try-with-resources is used, 
  
 // which automatically calls close(). 
  
 try 
  
 ( 
  AgentsClient 
 
  
 client 
  
 = 
  
  AgentsClient 
 
 . 
 create 
 ( 
 agentsSettings 
 )) 
  
 { 
  
 // Set the details of the Agent to create 
  
 Builder 
  
 build 
  
 = 
  
  Agent 
 
 . 
 newBuilder 
 (); 
  
 build 
 . 
  setDefaultLanguageCode 
 
 ( 
 "en" 
 ); 
  
 build 
 . 
 setDisplayName 
 ( 
 displayName 
 ); 
  
 // Correct format for timezone is location/city 
  
 // For example America/Los_Angeles, Europe/Madrid, Asia/Tokyo 
  
 build 
 . 
 setTimeZone 
 ( 
 "America/Los_Angeles" 
 ); 
  
  Agent 
 
  
 agent 
  
 = 
  
 build 
 . 
 build 
 (); 
  
 String 
  
 parentPath 
  
 = 
  
 String 
 . 
 format 
 ( 
 "projects/%s/locations/%s" 
 , 
  
 parent 
 , 
  
 "global" 
 ); 
  
 // Calls the create agent api and returns the created Agent 
  
  Agent 
 
  
 response 
  
 = 
  
 client 
 . 
 createAgent 
 ( 
 parentPath 
 , 
  
 agent 
 ); 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 response 
 ); 
  
 return 
  
 response 
 ; 
  
 } 
  
 } 
 }

Node.js

To authenticate to Dialogflow, set up Application Default Credentials. For more information, see Set up authentication for a local development environment .

  const 
  
 parent 
  
 = 
  
 'projects/' 
  
 + 
  
 projectId 
  
 + 
  
 '/locations/global' 
 ; 
 const 
  
 api_endpoint 
  
 = 
  
 'global-dialogflow.googleapis.com' 
 ; 
 const 
  
 agent 
  
 = 
  
 { 
  
 displayName 
 : 
  
 displayName 
 , 
  
 defaultLanguageCode 
 : 
  
 'en' 
 , 
  
 timeZone 
 : 
  
 'America/Los_Angeles' 
 , 
 }; 
 const 
  
 { 
 AgentsClient 
 } 
  
 = 
  
 require 
 ( 
 ' @google-cloud/dialogflow-cx 
' 
 ); 
 const 
  
 client 
  
 = 
  
 new 
  
  AgentsClient 
 
 ({ 
 apiEndpoint 
 : 
  
 api_endpoint 
 }); 
 async 
  
 function 
  
 setAgentSample 
 () 
  
 { 
  
 const 
  
 request 
  
 = 
  
 { 
  
 agent 
 , 
  
 parent 
 , 
  
 }; 
  
 const 
  
 [ 
 response 
 ] 
  
 = 
  
 await 
  
 client 
 . 
 createAgent 
 ( 
 request 
 ); 
  
 console 
 . 
 log 
 ( 
 `response: 
 ${ 
 JSON 
 . 
 stringify 
 ( 
 response 
 , 
  
 null 
 , 
  
 2 
 ) 
 } 
 ` 
 ); 
  
 // Delete created agent resource 
  
 client 
 . 
 deleteAgent 
 ({ 
 name 
 : 
  
 response 
 . 
 name 
 }); 
 } 
 await 
  
 setAgentSample 
 ();

Python

To authenticate to Dialogflow, set up Application Default Credentials. For more information, see Set up authentication for a local development environment .

  from 
  
 google.cloud.dialogflowcx_v3.services.agents.client 
  
 import 
 AgentsClient 
 from 
  
 google.cloud.dialogflowcx_v3.types.agent 
  
 import 
 Agent 
 def 
  
 create_agent 
 ( 
 project_id 
 , 
 display_name 
 ): 
 parent 
 = 
 "projects/" 
 + 
 project_id 
 + 
 "/locations/global" 
 agents_client 
 = 
 AgentsClient 
 () 
 agent 
 = 
 Agent 
 ( 
 display_name 
 = 
 display_name 
 , 
 default_language_code 
 = 
 "en" 
 , 
 time_zone 
 = 
 "America/Los_Angeles" 
 , 
 ) 
 response 
 = 
 agents_client 
 . 
 create_agent 
 ( 
 request 
 = 
 { 
 "agent" 
 : 
 agent 
 , 
 "parent" 
 : 
 parent 
 }) 
 return 
 response

Delete an agent

The following examples show how to call the Delete method for the Agent type.

Select a protocol and version for the Agent reference:

Protocol	V3	V3beta1
REST	Agent resource	Agent resource
RPC	Agent interface	Agent interface
C++	AgentsClient	Not available
C#	AgentsClient	Not available
Go	AgentsClient	Not available
Java	AgentsClient	AgentsClient
Node.js	AgentsClient	AgentsClient
PHP	Not available	Not available
Python	AgentsClient	AgentsClient
Ruby	Not available	Not available

REST

Before using any of the request data, make the following replacements:

PROJECT_ID : your Google Cloud project ID
REGION_ID : your region ID
AGENT_ID : your agent ID, found in the agent creation response

HTTP method and URL:

DELETE https:// REGION_ID 
-dialogflow.googleapis.com/v3/projects/ PROJECT_ID 
/locations/ REGION_ID 
/agents/ AGENT_ID

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Execute the following command:

curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "x-goog-user-project: PROJECT_ID 
" \
"https:// REGION_ID 
-dialogflow.googleapis.com/v3/projects/ PROJECT_ID 
/locations/ REGION_ID 
/agents/ AGENT_ID 
"

PowerShell (Windows)

Execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = " PROJECT_ID 
" }

Invoke-WebRequest `
-Method DELETE `
-Headers $headers `
-Uri "https:// REGION_ID 
-dialogflow.googleapis.com/v3/projects/ PROJECT_ID 
/locations/ REGION_ID 
/agents/ AGENT_ID 
" | Select-Object -Expand Content

You should receive a successful status code (2xx) and an empty response.

Implement webhooks

Manage pages with the API

Manage agents with the API Stay organized with collections Save and categorize content based on your preferences.

Create an agent

REST

curl (Linux, macOS, or Cloud Shell)

PowerShell (Windows)

Java

Node.js

Python

Delete an agent

REST

curl (Linux, macOS, or Cloud Shell)

PowerShell (Windows)

Manage agents with the API