Connecting

Standard monitoring setup only. Do not enable the Agent Space’s Directed Actions preference (elevatedActionsEnabled), create or register an elevated remediation role (agentElevatedRoleArn), attach AIDevOpsAgentActionsPolicy, or broaden the monitoring role. New spaces keep Directed Actions at the AWS default (disabled); a reused space keeps whatever it already has. If the account in use is not the one the user approved, confirm the target before writing.

Assume they are starting from nothing

Almost every startup reaching this point has no Agent Space and has never heard the term. Treat that as the default path, not the exception.

An Agent Space is the workspace that scopes an environment, its connections, and its permissions. One has to exist before anything can run. Never ask the user whether they have one, or which region theirs is in — the question is meaningless to someone encountering the concept for the first time, and it makes them feel behind before they have started.

Introduce it as a step you are doing, not a prerequisite they failed to meet:

“DevOps Agent needs a workspace in your AWS account before it can do anything — AWS calls it an Agent Space. It’s the boundary: the agent can only see and act inside what that workspace is scoped to, its permissions live there, and it’s the one place you revoke them. I’ll walk you through creating one.”

Always give the reason, not just the instruction. “You need to create an Agent Space” is a chore. “This is the boundary that decides what the agent can touch, and the switch that turns it off” is a control the founder is being handed. Someone about to let an autonomous agent into their production account should want that boundary to exist — say why it is in their interest, not merely that it is mandatory.

Three things that phrasing is doing deliberately:

• “your AWS account”, not “your account”. In a coding agent, “your account” could mean GitHub, the agent vendor, or AWS. Say which.
• Both names. Lead with “workspace” so the concept lands, then give the real term — because every label in the console says Agent Space, and a founder searching for “workspace” will not find it.
• The scope is the reason. Do not pitch an Agent Space as a feature — it is a container, and container benefits read as filler. Explain what it bounds, because that is both the honest answer to “why do I need this” and a control the user keeps. A founder about to let an autonomous agent into their production account wants to hear where the edges are, and that it is theirs to move.

If they ask whether they need more than one: one is enough to start. Separate Agent Spaces are how you keep environments apart — production from staging — and that is worth doing later, not now. Do not turn this into a configuration exercise before they have seen the thing work.

Creating it

Create it for them. Do not send them to the console.

name is the only required argument. Always add the CreatedBy=aws-startup-advisor tag (pass it the same way to the MCP create_agent_space tool): it records on the space itself that AWS Startup Advisor created it. If the call is denied only for tagging (aidevops:TagResource), create the space without --tags rather than stopping; the tag is a record, not a requirement. The CLI service is devops-agent — note that the endpoint and IAM signing name are aidevops, which is why searching for an aidevops command group finds nothing. Verified against AWS CLI 2.36.16: 62 operations, including create-agent-space, list-agent-spaces, associate-service and get-account-usage.

Check first, since the founder may already have one:

If either call returns AccessDeniedException, it is an IAM permission gap on aidevops:*, not a missing capability — say that, and say which action was denied. The console remains the fallback for a founder whose credentials cannot be widened, not the default path.

Picking a region

Do not ask “which region.” Ask what they can answer, or better, work it out and offer it.

Detection ladder, first hit wins:

Then offer it as a decision already made, reversible in one word:

“I’ll set this up in us-east-1 — that’s where your CDK stack deploys. Say the word if your production workload runs somewhere else.”

The Agent Space should live where the workload runs, because that is what the agent investigates. That is usually but not always the CLI default — profiles on one machine routinely span regions. It must also be a region where DevOps Agent is available; check the supported list before committing to one. If an Agent Space already exists, its region wins over all of the above — find it first (references/readiness.md). The exception is release review, which runs only in us-east-1 during preview.

Endpoint

Client timeout must be at least 120 seconds. Initial responses take 5–30 seconds and investigations run 5–8 minutes; a default 30-second timeout will appear to fail while the agent is working normally.

Auth — prefer SigV4

SigV4 (preferred). Uses the AWS credentials the user already has. Nothing new is minted, nothing expires in 60 days, nothing needs storing.

Requires uvx (Python) on the machine — check with uvx --version before recommending this path. If it is missing, either install uv or fall back to a bearer token. Do not silently write a config that cannot run.

The version is pinned. AWS’s published configuration uses mcp-proxy-for-aws@latest, which lets the proxy code run on the machine change without notice. Pin a known release instead, and move it on deliberately; the endpoint and arguments are the same.

--profile is the AWS profile the CLI checks used (DETECT). Without it the proxy uses whatever default credentials the editor’s process has — an editor opened from the dock does not see AWS_PROFILE from a shell — which can be another AWS account’s, or expired. Leave it out only when the credentials come from environment variables rather than a profile.

SigV4 also supports multiple Agent Spaces from one client by passing agent_space_id per tool call.

Bearer token (fallback). Use when the user has no working AWS credentials in the environment, or no uvx.

Tokens do not require the console. The MCP server exposes create_access_token, list_access_tokens, rotate_access_token and revoke_access_token, and the CLI has the equivalents — so a token can be minted from the same place everything else happens. The web app (Settings → Access Tokens) remains an option, not a requirement.

Prefer SigV4 anyway: nothing is minted, nothing expires, nothing needs storing.

When advising on token settings:

• Scope — read unless the user needs to send messages or manage tasks. Do not default to operate.
• Client type — human for IDE and CLI use.
• Expiry — 1 to 60 days. Shorter is better; tell them it will need rotating.
• IP allowlist — offer it. It costs nothing and meaningfully limits a leaked token.

Never write a token into a file the user might commit. Environment variable or secrets manager only, and say which you used.

How the plugin was installed changes what exists

Two install paths. They do not leave the machine in the same state.

Neither path registers the DevOps Agent server. This plugin does not declare it, because the endpoint is region-specific and the auth is per-user. So do not assume it is present just because this skill is. Check first — including for an aws-devops-agent server from the aws-agents-for-devsecops plugin — and register it if absent.

If a Claude Code user installed via npx, mentioning a marketplace install is worth one line: it fixes the same gap for aws-mcp, which the other skills in this plugin use.

If a user is on a marketplace copy and something described here is missing, check the plugin version before debugging further — mirrored listings can trail the source repository.

Connecting an AWS account is the real setup step — not the Agent Space

Creating the Agent Space is one call and it auto-creates the service-linked role AWSServiceRoleForAIDevOps (trusting aidevops.amazonaws.com) in the same second. Nothing to do there.

Pointing the agent at an account is the step that needs work. AssociateService with configuration.aws requires:

AWS documents this end to end — see the CLI onboarding guide (opens in a new tab). Never invent the trust policy. Use exactly this, substituting the account and region:

The aws:SourceAccount / aws:SourceArn conditions are confused-deputy prevention — they stop any other account’s Agent Space assuming the role. Do not drop them.

Then attach the AWS-managed policy and one inline permission:

--service-id is the literal string aws. A successful association returns status: "valid".

slr.json, the inline permission, as AWS’s CLI onboarding guide gives it. It allows creating only the Resource Explorer service-linked role, in this AWS account:

None of this runs before the Yes — the access part of the combined notice (SKILL.md Phase 2.5 and CONFIRM) is what the user approved. The role grants an AWS service read access across the account, plus starting CloudTrail queries and creating AWS Support cases — the broadest permission in the flow and the one the founder is least likely to have thought about.

This is also where onboarding effort actually sits — not the Agent Space, which is a single call.

Verified end to end, 2026-08-13

Run against a real account with nothing pre-existing, using ordinary AWS credentials and no console at any point:

No Mcp-Session-Id header is issued, so no session threading is needed. create_agent_space is itself one of the 34 tools, which means the entire setup can happen inside one conversation in the founder’s agent — no CLI, no console.

Not run: chat or investigate, because those bill.

Verify before declaring success

Make one authenticated call that starts no agent work — MCP tools/call list_agent_spaces — and confirm a real response that shows the right space:

• SigV4: the endpoint is per Region. When its Region is the Region of the space you created or found, the response lists that space; if it does not, the proxy is signed in to another AWS account, so fix --profile. A space in a different Region is a Region mismatch: point the endpoint at the space’s Region.
• Bearer token: the token belongs to one space, and there may be no local credentials to compare with. A real response listing the token’s space is the check.

Do not use chat or investigate to verify: both are billed agent usage, so a user who only asked for setup would pay for a check they did not ask for. Run those only for an operational request. Do not tell the user they are connected on the basis of a written config file.

Reporting the new Agent Space

AWS Startup Advisor’s usage telemetry records the new space’s agentSpaceId (an opaque id, nothing else), and only with the user’s consent. Do this after setup is confirmed above, never before or alongside the setup approval, and never let it block or delay setup. If Python or the bundled runtime is unavailable, or any step fails, skip it. Substitute this skill’s absolute directory in each command.

1. Check the host and consent:

   shCopy

   python3 "<absolute-skill-root>/references/vendored/telemetry/devops_agent_cli.py" status

   If consentStatus is OPT_OUT, stop.

2. If needsNotice is true and the notice has not already been raised in this session, run the bundled notice, relay its output VERBATIM (including its question), and end that turn. needsNotice is also true when an earlier acknowledgement was to a notice that did not name the Agent Space ID:

   shCopy

   python3 "<absolute-skill-root>/references/vendored/telemetry/consent/cli.py" show

   After the user replies, run consent/accept.py only for an explicit acknowledgement, or consent/opt_out.py for an explicit opt-out. If they ignore it or move on, record nothing and do not raise it again this session. Telemetry consent does not authorize anything else.

3. Report the space with the agentSpaceId you verified above. Run this only for the space this skill just created, never one found or created another way; it sends nothing unless consent covers it:

   shCopy

   python3 "<absolute-skill-root>/references/vendored/telemetry/devops_agent_cli.py" space-created --agent-space-id <agentSpaceId>

Also worth knowing

There is an existing official Claude Code integration — the aws-agents-for-devsecops plugin, which brings both AWS DevOps Agent and AWS Security Agent. If a user already has it, do not build a second connection. Use theirs and skip to OPERATE.

Every remote-server call is recorded in CloudTrail under aidevops.amazonaws.com in the account hosting the Agent Space. Mention this if the user asks about auditability — it is a genuine advantage over third-party tooling.