Skip to main content

AWS connector

For Studio users who can create an AWS Identity and Access Management (IAM) role in the account an agent should reach, or hand the trust policy to someone who can. No access keys are pasted or stored: the role trusts your deployment's platform principal under an External ID Studio generates ("You decide exactly what agents can access through the role's IAM policies").

Before you start: there is no discovery for AWS; "The Connector Guide you wrote above is the only thing telling agents what this role can do", so write it with the scope in mind.

Steps​

  1. Open Data Connectors, click Create Connector, choose AWS and fill Connector Name, Description and Connector Guide.
  2. In Connection Configuration, enter the Default AWS Region (placeholder us-east-1): the region the agent's AWS clients default to; it does not restrict the role.
  3. Click Generate Role Setup. Four blocks appear, each with Copy: Platform principal (who your role must trust); ExternalId (unique to this connector; required in the trust condition); Trust policy (paste as the role's trust relationship), allowing sts:AssumeRole for the principal when sts:ExternalId equals that value; and Example permission policy (guidance only; you decide the actual scope), a read-only Amazon S3 example to replace with the access you intend ("that's entirely your call; least privilege recommended").
  1. In the AWS account, create the role with that trust policy, attach your permission policies and paste its Amazon Resource Name (ARN) into IAM Role ARN (placeholder arn:aws:iam::123456789012:role/alphaagent-access).
  2. Click Test Connection. Studio assumes the role with the External ID and verifies the identity; a tick names it, a cross shows the AWS error. Nothing is saved.
  3. Click Create Connector (v1), enabled only after a passing test with name, description, guide, region and ARN filled. Regenerate Role Setup issues a new External ID; update the trust policy before testing again.
  4. Open the agent, choose Configure, and add the connector (Agents: configure and activate).
  5. Open the connector from the list: Verify access shows Last verified (see below).

What you should see​

The list shows AWS "(v1)", Active. The detail page opens with Verify access: Last verified and the time (or "Never verified"), Test connection ("Assume the role with this connector's ExternalId") and Copy buttons for the platform principal, External ID and trust policy. Configuration shows the role ARN, region and session duration; on Update, Credentials reads "AWS connectors use short-lived STS credentials minted at runtime via the IAM role above".

Before an API-started run​

The panel says it: "API runs need a passing test: a workflow run started through the programmatic API that reads from this connector is refused until Test connection has passed here." Last verified is stamped by this button and by the test Studio runs when it saves the connector (at creation, or after a role or credential change), so a connector created with a passing test is ready at once; until a pass is recorded the API answers 409 workflow_not_ready and tells the caller to press Test connection here. A failed test shows "Last test failed <time>: <error>" until the next pass.

How agents use it​

  • Session duration: the lifetime of the temporary credentials Studio requests from AWS Security Token Service (STS) when it assumes the role. Not a form field; new connectors use 3,600 seconds. The value must be between 900 and 43,200 seconds and cannot exceed the role's maximum session duration; when the deployment assumes the role through its platform principal in two steps, AWS limits the second step to 3,600 seconds.
  • S3 in the sandbox: no bucket, prefix or object browser, and no S3 operation run by Studio on the agent's behalf. The agent's code uses the AWS SDK for Python in its execution environment with the temporary credentials and default region, exactly as far as the policy allows; on AccessDenied it reports the error rather than probing other services.
  • S3 prefix parameter: a workflow parameter of type S3 prefix names an AWS connector; at run time the objects under the prefix are copied into the run's inputs/ folder as that role. The connector must be Active and stamped Last verified (Workflows: run, schedule, approve, Patterns).
  • Sharing: a copy pulled from a Library carries the role ARN, region and External ID, but the recipient connects from a different principal, so the copy shows Needs Attention with the account to add to the trust policy (Libraries and sharing).

Notes​

  • Limits: IAM Role ARN arn:aws:iam::<12-digit account id>:role/<name or path/name>; External ID generated by Studio, up to 128 characters, stored in AWS Secrets Manager, never editable; session 900 to 43,200 seconds, default 3,600.
  • "external_id is required to test an AWS connector. Generate role setup info first.": click Generate Role Setup first. "role_arn must be a well-formed IAM role ARN": copy the ARN from the role's summary page.
  • An AWS access error on test: the trust policy does not match; check the principal, that sts:ExternalId is the current External ID (regenerating changes it), and the ARN.