Skip to main content

Connector versions, Test Connection and guides

For connector owners who rotate a credential, change a setting, review dependent agents, improve the guide or delete a connector. Every Update creates a new version; older versions stay alive until every agent has moved.

The detail page​

Click a row in Data Connectors. From top to bottom:

  • Header: Connector Name, ID, Type, Version ("v1"), Created and Updated, with Update, Share and Delete; then the Shared to strip and, on a pulled copy, "Pulled from <deployment> · library vN · <date>".
  • Needs attention banner, only when the status is Needs Attention, with the reason.
  • Verify access (AWS only): Last verified or "Never verified", Test connection, and the principal, External ID and trust policy with Copy (AWS connector).
  • Versions: one row per version (Version, Name, Type, Created, Status); the active one carries a green Current badge.
  • Configuration (the type's settings, read-only; secret-bearing ones read "Stored securely (values hidden). Use Update to replace values."), Credentials (each key masked with View / Hide; private keys and passphrases cannot be revealed; Snowflake shows only the Username) and Connector Guide (Expand / Collapse).
  • Data Connector Map: "Every agent that currently consumes this connector.", nodes reading "Agent vN · DC vN". Disassociate All removes the connector from every agent's active configuration; Re-associate All restores them. Empty: "No agents currently use this data connector in their active configuration."

Update a connector​

  1. Click Update. The header: "Saving creates v2 so existing agents and workflows continue to use the previous version until you publish." (with the next number).
  2. Change Connector Name and Description (required), Connector Guide (Optional) and the type's connection settings (REST re-validates with Validate OpenAPI and Enrich guide from OpenAPI; AWS keeps its role setup; Snowflake shows the setup facts). Connector Type is read-only.
  3. Rotate credentials only if needed:
TypeRule
SQL DatabaseEnter both Username and Password, or leave both blank to keep the stored pair.
REST API, MCP Server"Re-enter credential values to rotate secrets." A row with a key and no value keeps the stored value; a value replaces it.
AWSNothing to rotate: "AWS connectors use short-lived STS credentials minted at runtime via the IAM role above".
SnowflakeBlank keeps the stored token or key; a new one needs its username; switching method needs the complete credentials (Snowflake connector).
  1. Click Test Connection (SQL, MCP Server, AWS, Snowflake; REST uses Validate OpenAPI). It tests the form's values merged with the stored credentials for blank fields and saves nothing. SQL and MCP Server again need Explore Schema & Enrich Guide or Discover Tools & Enrich Guide and an accepted guide after a pass.
  2. Click Update Connector (v2) ("Saving creates v2"). Saving sets Active, except on a Needs Attention connector, which keeps its flag until the problem is fixed.

Test connection on an existing connector​

Only AWS has Test connection on the detail page (Verify access); the other types are tested from Update. A pass stamps Last verified, a fail shows "Last test failed <time>: <error>". An API-started run needs one recorded passing test on the connector, on any version; the test Studio runs when you create an AWS connector or update its role or credentials counts. Otherwise the API refuses with 409 workflow_not_ready: "connector '<name>' (<id>) has not passed Test connection. Open the connector's page and press Test connection, then start the run again."

Versions and pins​

"Each save creates a new immutable version. Agents and workflows pin to a specific version, so older versions stay alive until everything has migrated." An agent pins the version chosen in its Configure dialog and keeps v1 after you save v2 until you move it. Credentials are stored per connector, not per version, so a rotation applies to every version.

Writing the guide the agent follows​

The guide is the only description of the connector the agent has; Studio adds only a per-type "how to connect" note. It is required at creation and read on every turn ("Large guides cost more per turn." above 50,000 characters). Write for a capable colleague new to the system: what it holds and is for; the tables, endpoints or tools that matter, with fields to use and to ignore; units, currencies, time zones and date formats; what the agent must not do (no full-table pulls; aggregate first). For SQL, REST API and MCP Server start from the drafted guide; for AWS and Snowflake write it yourself ("make it count").

Delete a connector​

  1. Click Delete ("Checking..." while Studio checks active agent configurations).
  2. If any use it, Cannot Delete Data Connector lists the Affected Agents: Disassociate All first, then point the agents at another connector in their Configure dialog. Otherwise Delete Connector asks you to type the name, then Delete.

Notes​

  • Limits: name 80 characters; description 1,000; guide advisory above 50,000 characters; unlimited versions.
  • Update Connector disabled: a required field is empty, a counter is over its limit, a REST specification was not re-validated after an edit, or a credential rule is half met (a SQL username without its password).
  • The map shows an error: click Retry. A rotated credential reaches every version; if an agent seems not to get it, check the value you entered.