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:

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:

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