Agentic virtual agents public APIs

AI-generated summary

Genesys Cloud provides a comprehensive preview feature for agentic virtual agents accessible through Menu > Orchestration > AI Studio > Agentic Virtual Agents, requiring Virtual Agent enablement and appropriate AI Studio permissions. The inbuilt preview widget enables validation of agent configurations including role, guidelines, data actions, knowledge configuration, start and exit behavior, and guardrails. Users can customize testing parameters such as language selection, channel choice (digital or voice), text-to-speech engine and voice configuration, variable assignments, and data action simulation. The interface supports real-time chat interactions and includes a Restart function that reinitializes sessions and loads updated agent configurations. Variable masking states are indicated through system icons for transparency. Testing capabilities extend through Architect integration after connecting agents to virtual agent flows for comprehensive quality assurance before production deployment. Genesys Cloud offers extensive documentation resources including the "Test and troubleshoot agentic virtual agents" guide, with related documentation covering agent creation, AI Studio integration, knowledge base connectivity, and guardrail configuration. A feedback mechanism allows users to report issues or provide feedback by organizational role. The Genesys Cloud Developer Center contains public API schemas for agentic virtual agents; however, the API documentation is partially documented due to limitations in rendering the discriminator pattern used by OpenAPI 2.0 contracts. The documentation is being migrated to OpenAPI 3.0 standard, which supports the discriminator pattern. Until migration is complete, direct public API clients can access the underlying OpenAPI 2.0 specification as a .json file, which contains complete definitions of all agentic virtual agent contracts including fields not currently displayed in the Developer Center documentation. Genesys Cloud implements a discriminator-based contract structure for agentic virtual agent tools that enables polymorphic type handling through a base type definition. The base "AgenticVirtualAgentTool" type declares a required discriminator property named "type" with enumerated values including KnowledgeSetting, KnowledgeBase, DataAction, and ExternalA2AServer. Required fields across all tool types include description, name, target, and type. Subtypes such as "AgenticVirtualAgentKnowledgeBaseTool" extend the base contract using the "allOf" composition pattern, which combines the base type reference with subtype-specific properties including inputs and inputValidation arrays. Each subtype is linked to its corresponding discriminator value through the x-discriminator-value vendor extension field, establishing the relationship between the enumerated type values and their concrete implementations. This architecture enables Genesys Cloud to support multiple tool types within a unified contract framework while maintaining type safety and extensibility for virtual agent configurations.

Genesys Cloud Developer Center contains the public API schemas for agentic virtual agents. For more information, see API Explorer.

Note: Due to a limitation in the Public API Developer Center Documentation, the agentic virtual agent API contracts are only partially documented. The documentation renderer does not support the discriminator pattern used by certain OpenAPI 2.0 contracts. As a result, some fields and subtypes are not displayed.

The API documentation is currently being migrated to the OpenAPI 3.0 standard, which supports the discriminator pattern. Until this migration is complete, direct public API clients for agentic virtual agent resources can use the underlying OpenAPI 2.0 specification below, which contains the complete definitions of all agentic virtual agent contracts. This specification also includes the fields that are not currently displayed in the Developer Center API documentation.

Agentic virtual agents OpenAPI 2.0 specification

You can download the agentic virtual agent APIs in the OpenAPI 2.0 specification as a .json file.

Example

The Tool contract has multiple subtypes, for example, one for a Data Action and another for a knowledge base tool. The discriminator pattern has two parts: the base contract and the subtype. Combine these two parts to form the complete contract.

The base type declares the discriminator

"AgenticVirtualAgentTool": {
  "type": "object",
  "required": ["description", "name", "target", "type"],
  "discriminator": "type",
  "properties": {
    "type": {
      "type": "string",
      "description": "Tool type discriminator.",
      "enum": ["KnowledgeSetting", "KnowledgeBase", "DataAction", "ExternalA2AServer"]
    },
    "name": { "type": "string", ... },
    "description": { "type": "string", ... },
    ...
  }
}

Notes:

"discriminator": "type" names the property whose value decides the concrete subtype.
The enum defined on the type property lists the allowed discriminator values. Each value corresponds to a subtype, which links back to the base through its x-discriminator-value (vendor extension) field, as shown after this.

The subtypes reference the base with “allOf”

"AgenticVirtualAgentKnowledgeBaseTool": {
  "allOf": [
    { "$ref": "#/definitions/AgenticVirtualAgentTool" },
    {
      "type": "object",
      "properties": {
        "inputs": { "type": "array", "items": {...} },
        "inputValidation": { "type": "array", "items": {...} }
      },
      "description": "Knowledge base tool."
    }
  ],
  "x-discriminator-value": "KnowledgeBase"
}

Notes:

allOf means that “this type is the base plus these additional properties.” The first element references the base contract, and the second adds subtype-specific fields.
x-discriminator-value links the enum from the base to this subtype.

[NEXT] Was this article helpful?

Get user feedback about articles.