Using Connect Agent#
This guide explains how to use Connect Agent, the AI assistant built into Adverity, to troubleshoot, check, and change your workspace by asking in plain language.
Introduction#
Instead of clicking through several pages to find out why a fetch failed, you can ask:
Why did Facebook Ads - EU fail last night?
Connect Agent checks the fetch history and the error, explains what went wrong, and suggests a fix. If the fix changes something, such as retrying the fetch, it shows you the change first and makes it only after you approve it.
- What can Connect Agent work with?
Most of what you manage in Adverity: datastreams and fetches, authorizations, destinations, transformations, data mapping and mapping table entries, datastream assignments to monitors, data extracts and errors, workspaces, and the data in your Data Warehouse. It also answers questions about Adverity from this documentation. Administrators in the root workspace can also manage users and notifications.
- What can Connect Agent access?
Connect Agent acts with your own permissions in the current workspace and its child workspaces. It sees and changes only what you can see and change, and some changes need a higher role than in the interface: for example, changing mapping table entries needs the Workspace manager or Administrator role. If your role does not allow changes, you can still look things up and ask questions. For more information, see Managing user permissions.
- How does Connect Agent relate to Adverity MCP?
Connect Agent uses the Adverity MCP tools, with no setup. To use these tools from your own AI assistant instead, see Using Adverity MCP.
Important
Connect Agent is part of Adverity’s AI features. It is not available for accounts whose contracts prohibit AI processing. For details of the AI model used and the data it processes, see Use of general-purpose AI models in Adverity.
Limitations#
Connect Agent comes with the following limitations:
It cannot work with dashboards or widgets.
It does not ask for credentials in the conversation, and it cannot complete a sign-in through a provider’s login page. You finish these steps on the Authorizations or Destinations page. For more information, see Keeping credentials out of the conversation.
It queries only the data that Adverity has loaded into the Data Warehouse for your workspace, and one query returns at most 100 rows. It cannot query other tables or databases.
It cannot create or delete mapping tables, and it cannot delete workspaces.
A message can contain up to 8,000 characters, and one answer can take only a limited number of steps. Split large tasks into smaller requests.
Opening Connect Agent#
To open Connect Agent, follow these steps:
Go to a page in your workspace.
In the top navigation panel, click Connect Agent, or press Cmd+J on Mac or Ctrl+J on Windows and Linux.
The shortcut does not work while you are typing in a code editor.
As a result, Connect Agent opens in a floating panel. The page stays usable behind it, so you can keep working while it answers.
Note
If you do not see Connect Agent in the top navigation panel, it is not enabled for you in this workspace. Connect Agent is also not available on the Administration pages or while you clone datastreams or workspaces.
Drag the left edge, top edge, or top-left corner to resize the panel, and Adverity remembers the size in your browser. To give the conversation more room, click Open full page, and click Open as floating panel to go back. To close the panel, click Close assistant, press Esc while you are in the panel, or press the shortcut again.
Asking Connect Agent#
Type your question and press Enter, or select one of the suggested prompts. Connect Agent shows what it is working on, then answers. Links in the answer open the related page. When it has looked several things up, it folds them into a short summary above the answer.
The following examples show the kinds of jobs Connect Agent handles.
Troubleshooting failures#
Find out what failed, why, and what to do about it:
“Which fetches failed recently?”
“Why did Facebook Ads - EU fail last night?”
“Retry the failed fetches for Facebook Ads - EU.”
Checking your setup#
Get an overview without opening every item:
“Show me my datastreams and their status.”
“Check my authorizations for problems.”
“Which datastreams are disabled?”
Changing configuration#
Describe the change, and Connect Agent prepares it for your approval:
“Rename this datastream to Facebook Ads - EU.”
“Change the schedule of Facebook Ads - EU to every day at 6:00.”
“Disable the datastreams I selected.”
Setting up something new#
Connect Agent creates the items and tells you which steps to finish in the interface:
“Create a Google Ads datastream.”
“How do I connect a BigQuery destination?”
Looking at your data#
Ask about the data in your Data Warehouse and data extracts:
“Which campaigns had the most clicks last week?”
“Show me a few rows from the latest data extract of Facebook Ads - EU.”
Asking about the page you are on#
Connect Agent knows where you are, so you do not have to name everything:
On a detail page, such as a datastream or authorization, it knows which item is open. Open a failing datastream and ask “Why is this one failing?”
On the Datastreams page, it knows which datastreams you have selected. Select a few and ask “Which of these have not fetched this week?”
On other pages, it knows the name of the page.
In the message field, Connect Agent shows what it is using, for example Using this page: Facebook Ads - EU or Using your selection: 3 datastreams. To ask without it, click the close icon next to it. Connect Agent still knows the address of the page. The context comes back when you go to another page or change your selection.
Note
Page context works in the floating panel, not on the full page.
Approving changes#
Connect Agent never changes anything on its own. For every change, it first shows an approval card with what will change, and for an update, the current and the new value. If your request involves several changes, it asks for them one at a time. Some changes, such as requeuing several data extracts, are approved together on one card.
To approve or cancel a change, follow these steps:
Read the approval card.
To see the request details, click View raw arguments. Passwords, tokens, and keys are masked.
Click Approve to make the change, or Cancel to discard it.
For deletions, the button is called Delete.
As a result, the card collapses to a short summary of the outcome. If the change fails, the card shows the reason, and nothing is changed.
Warning
If the card says that the change may have been applied, Adverity did not receive a result for it. Check the item before you ask Connect Agent to try again.
While an approval card is waiting for you, you cannot send new messages.
Keeping credentials out of the conversation#
Your messages are sent to an AI provider and kept in the conversation, so Connect Agent never asks for passwords, API keys, or tokens. When a task needs one, it links to the right form on the Authorizations or Destinations page. Enter the credential there, then tell Connect Agent to continue.
Warning
Do not paste credentials into the conversation. If you do, Connect Agent uses the credential to finish the task and asks you to rotate it. Change the credential on the Authorizations or Destinations page, and start a new conversation to delete it from the conversation.
Getting better answers#
- Name the item
“The Facebook Ads - EU datastream” works better than “my Facebook one”.
- Use the page
On a detail page, say “this”. On the Datastreams page, select rows first and say “these”.
- Ask for one job at a time
For a large clean-up, ask Connect Agent to list what it would change first, then pick the items.
- Use the suggested follow-ups
Below an answer, Connect Agent can suggest next steps that you select instead of typing.
- Check important results
Connect Agent can make mistakes. Check answers and changes that matter before you rely on them.
Managing the conversation#
Connect Agent keeps one conversation per user in each workspace. The conversation stays when you close the panel or reload the page.
To stop an answer, click Stop generating.
If an answer fails or you stopped it, click Retry on the latest answer.
To start over, click Start new conversation in the panel header and confirm. This deletes the current conversation, and you cannot restore it.
In a long conversation, Connect Agent takes only the most recent messages into account, and a conversation has a length limit. When you switch to a new topic, start a new conversation.