Integrate Agent Copilot with third parties

Genesys Agent Copilot can hand over work to your own systems and to AI agents through third-party actions. Agent Copilot emits two event types: a suggestion action trigger event and a suggestion action result event. For each rule action, you can configure Agent Copilot to send a custom trigger event rather than run the action directly. If you integrate Amazon EventBridge with Agent Copilot, then you can subscribe to third-party action trigger events, filter these events, and route them to AWS targets such as Lambda, S3, SQS, or your own system. Third-party systems can listen for these events and perform the associated action within their own application. Third-party systems can also post the results back to the Agent Copilot suggestions panel. The process contains the following steps.

• Agent Copilot triggers a third-party action event and EventBridge delivers the event to your system.
• Your system processes the event (for example, using context.queryStatement or context.reformulatedQuery to generate an answer).
• Your system performs the associated action or posts the response back to Genesys against the originating conversation and suggestion.
• If your system posts a response to Agent Copilot, the suggestion appears in the Agent Copilot suggestions panel, where the agent can use it.

Before you make any changes, make sure to familiarize yourself with Genesys Cloud Amazon EventBridge integration. For more information, see About the Amazon EventBridge integration and Amazon EventBridge notifications.

Trigger third-party actions in Agent Copilot

1. Click Menu > Orchestration > AI Studio > Agent Copilots.
2. Click New Copilot or edit an existing one.
3. Click the Settings tab and configure the copilot.
4. Click the Natural Language Understanding tab and configure intents.
5. Click the Rules engine tab and configure a rule that allows Agent Copilot to trigger a third-party action. You can trigger a third-party action when a conversation starts, ends, or is transferred, when Agent Copilot detects an intent, or as a fallback action. For more information, see Configure Genesys Agent Copilot rules. 
   For example, you can set up a rule that triggers a third-party action when the customer or the agent intends to query specific information. You can scope the rule to listen for only the customer or only the agent. When Agent Copilot detects the relevant intent in the utterance, it becomes the active intent of the conversation.
   You can also attach a third-party action to the fallback rule. In this case, the third-party action triggers when no other action triggers on a detected intent. This setup can be useful for a generic AI agent, such as a knowledge RAG. To attach a third-party action to the fallback rule, edit the built-in No other rule applies rule.

Stream events to AWS with EventBridge

Amazon EventBridge can stream Genesys Cloud events, such as conversation events, presence changes, and analytics updates from the Notification Service into your AWS account. Genesys Cloud can publish through the Notification Service, which streams events into an EventBridge partner event bus in your account. In the event bus, EventBridge rules route matching events to targets, such as Lambda, S3, SQS, or external systems.

To receive third-party action events in AWS, you must configure the integration on the Genesys Cloud side, then connect the event bus, rule, and target on the AWS side.

Configure and activate EventBridge integration in Genesys Cloud

Create a Genesys EventBridge integration, and add the following data. For more information, see Configure the Amazon EventBridge integration.

• Your AWS Account ID
• Your AWS region
• An Event Source Suffix of your choice
• For Topic Filtering, select v2.conversations.{id}.suggestions.thirdpartyaction

After you add all the necessary data, click Save, then click Activate.

Set up EventBridge in AWS

1. Find your partner event source on the Partner event sources page in AWS EventBridge.
   The name uses the format aws.partner/genesys.com/cloud/{your organization id}/{suffix}.

   Note:The host segment reflects your Genesys Cloud environment. For example, a test region uses genesys.com.test. Confirm the exact value for your organization.
2. To associate the event source with an event bus, open the partner event source, click Associate with event bus, and follow the steps.
3. On the Partner event sources page, confirm that the associated bus appears with an Active status.
4. On the Rules page, select the event bus and click Add rule. Specify a meaningful name for the rule.
5. Under Build event pattern, choose Other as the source and Custom pattern (JSON editor) as the pattern. Define the pattern to match the events that you want. Adjust field paths to match the live schema. EventBridge patterns must mirror the actual structure of the event.
   For the full schema for v2.conversations.{id}.suggestions.thirdpartyaction, see Available topics (Developer Center). The following examples show typical event schemas and filtering patterns.
   
   Example event schemaClick to expand

   The following example schema shows the fields that a typical event contains. The example is not a complete event.

   {
     "detail": {
       "eventBody": {
         "conversationId": "…",
         "suggestionId": "…",
         "activeIntent": {
           "intent": "OrderConfirmation",
           "confidence": 0.9
         },
         "context": {
           "queryStatement": "What are today's mortgage rates?",
           "reformulatedQuery": "current mortgage rates"
         }
       }
     }
   }
   

   Example filtering patternClick to expand

   The following filter pattern example matches events with a triggered state when NLU recognizes a new active intent and the third-party action rule triggers.

   {
     "detail": {
       "eventBody": {
         "state": ["Triggered"],
         "context": {
           "assistantId": ["your-assistant-id"]
         },
         "triggerType": ["Intent"]
       }
     }
   }
   

   Example filtering patternClick to expand

   The following filter pattern matches events where the fallback action triggers for an Agent Copilot when it detects no new active intent. For example, you can use the fallback action to look up information from knowledge.

   {
     "detail": {
       "eventBody": {
         "state": ["Triggered"],
         "context": {
           "assistantId": ["your-assistant-id"]
         },
         "triggerType": ["Fallback"]
       }
     }
   }
   

6. Connect your target. To test the connection, send events to a CloudWatch log group by adding an AWS target and a new log group under /aws/events/.
7. Review and create the rule.

After the setup is complete, any third-party action event that triggers in Agent Copilot and that also satisfies your pattern arrives at the target.

Send suggestions back to Genesys

After your system or the AI agent produces a response, you must post it back to Genesys Cloud to allow it to appear in the Agent Copilot suggestions panel during a live conversation.

To update a suggestion with your content, make the following API call.

PATCH /api/v2/conversations/{conversationId}/suggestions/{suggestionId}

Both conversationId and suggestionId come directly from the trigger event. The suggestionId uniquely identifies the suggestion, which means that if you patch against it, it links the response back to the triggering event.

For more information about the request body, response, and the required OAuth scopes and permissions, see the API Explorer (Developer Center).