SUPER AGENT

SUPER AGENT is a conversational AWS and Kubernetes operations assistant that uses the Amazon Bedrock Converse API. It can inspect resources, investigate metrics and logs, and perform guarded operations after explicit approval.

How to run

python -m pip install super-power-bedrock
super-power

Ask a one-off question:

super-power "List EKS clusters in us-west-2"

Or start an interactive session:

super-power --interactive

Check this machine's AWS identity, Bedrock model access, and Kubernetes client readiness before starting work:

super-power --preflight

Interactive sessions run this credential-safe check at startup. Use --skip-preflight only when you deliberately want to suppress its display; it does not disable runtime safety checks. Within an interactive session, run /doctor to repeat the check.

Choose a model or AWS Region when needed:

super-power --model <model-or-profile-id> --region eu-west-1 "Show EC2 instances"

Cross-account operations

Cross-account is a first-class workflow. Select the target account and Super Power assumes its CrossAccountAgentRole by default, verifies the resulting STS identity is in that exact account, and displays the target in the terminal footer and audit log.

super-power --account-id 123456789012
super-power --account-id 123456789012 --role-name Platform/CrossAccountAgentRole
super-power --account-id 123456789012 --external-id your-trust-policy-value --preflight

--assume-role remains available for an explicit role ARN. The source role must be allowed to call sts:AssumeRole, and the target role's trust policy must allow the source role. An account mismatch stops the session before any Bedrock or infrastructure operation begins.

Inside an interactive session, switch safely without exiting:

/account 219826436331

You can also type switch account to 219826436331. SUPER AGENT asks for approval, verifies the newly assumed identity, then clears the previous conversation and Kubernetes connection so evidence from two accounts cannot mix.

JEV tool safety

JEV is the local validation layer between the model and AWS. It blocks unknown or sensitive APIs so a model cannot guess an invalid operation or read a secret just because it is technically a “read” call. The catalog expands through reviewed typed tools and validated capabilities. It includes CloudTrail event lookup for “who created this?” investigations and CloudWatch Logs group discovery; unsupported services are intentionally rejected with an explanation rather than executed blindly.

Development architecture

For contributors, the architecture guide explains the runtime flow, JEV boundaries, and the safe module-extraction order.

Requirements

• Python 3.9 or later
• AWS credentials supplied by a standard AWS profile, IAM Identity Center, environment variables, an EC2 instance profile, or an EKS web-identity role
• Amazon Bedrock model access and bedrock:InvokeModel permission for the selected model and Region

Install Kubernetes support when you need Kubernetes API tools:

python -m pip install "super-power[kubernetes]"

Safety

Read-only operations run without confirmation. Operations that create, change, restart, scale, delete, or send commands require approval. A built-in block list refuses destructive commands even when approval is supplied.

The tool does not create AWS credentials, enable Bedrock model access, or change account-level permissions. Never put credentials, access keys, or tokens into source code, memory files, or package configuration.

If Bedrock invocation is denied, preflight identifies the active AWS role, account, model or inference profile, and Region, then explains the smallest safe administrator checks. It never prints credential values. The readiness probe sends a fixed one-token request without conversation history solely to verify the selected model's Converse permission.

Troubleshooting documentation

For AWS and Kubernetes investigations, SUPER AGENT can retrieve concise, cited guidance from official AWS and Kubernetes documentation. It only contacts allowlisted HTTPS documentation domains, uses bounded response sizes and timeouts, and never sends credentials or cookies. If documentation is unavailable, it reports the official source link rather than inventing advice.

Interactive terminals use a color-aware Rich interface with a thinking/progress indicator. Set NO_COLOR=1 or redirect output for plain text; --json always emits machine-readable JSON only.

The interface uses a warm-coral #D97757 accent for the SUPER AGENT wordmark, section headings, table headers, borders, prompts, and status indicator. Green, amber, red, and dim text are reserved for semantic success, approval/warning, errors, and secondary information. Color is optional: plain text and JSON remain complete and readable.

Normal interactive use shows only a generic thinking indicator. Pass --verbose when you need sanitized tool names and activity diagnostics. Routine intermediate tool failures are kept out of the normal UI; the final answer explains only relevant evidence. Approval prompts show the requested action or command, rather than internal tool JSON.

The terminal UI uses no emoji and falls back to plain text when output is redirected or NO_COLOR is set. It deliberately uses the lightweight standard input path, avoiding raw-terminal dependencies that can degrade performance in minimal EC2 and container environments.

Use /help in an interactive session for /status, /details, /theme, /doctor, /clear, and /exit. Prefix an existing allowlisted local diagnostic with !, for example ! df -h; this is not a general shell escape.

For in-process history, slash-command completion, and keyboard navigation, install the optional UI extra. It is lazy-loaded and the normal input path is used automatically when the extra or a compatible terminal is unavailable.

python -m pip install "super-power-bedrock[ui]"

Audit log and fresh sessions

SUPER AGENT stores a sanitized append-only audit log named super_power.log in the directory where it is started. It records compact requests, outcomes, and tool status, but it is never sent to Bedrock as conversation history.

On the first 0.3.4 run, an existing ai_memory.dm is renamed to a dated ai_memory.dm.archived-... backup. This stops old conversations from causing the model to resume a previous investigation. /clear clears only the current in-process session; the audit log remains intact.

SES email identities

SUPER AGENT can create an Amazon SES email identity after explicit approval. That action asks AWS to send its verification email; it does not and cannot bypass the mailbox verification link. Ask the assistant to check the identity status after the link is used, then send email with a verified from_email or the EMAIL_FROM environment variable. Datadog is not part of this package.

EKS workload access

SUPER AGENT runs safe diagnostics directly on the host where it is started. It uses SSM only for an explicitly selected different managed instance. To inspect Kubernetes namespaces, pods, events, logs, and deployments, install the Kubernetes extra and allow the agent to create/update local kubeconfig for the chosen EKS cluster. This connects through the Kubernetes API; it does not open an interactive SSH, SSM, or pod-exec session.

Raw kubectl and raw aws eks update-kubeconfig commands are blocked by the deterministic JEV guard. After approved EKS connection, the agent uses typed Kubernetes API tools for Services, Ingresses, and Istio/Gateway API routing resources instead.

Generic AWS SDK reads are also constrained to a bundled JEV capability catalog. Before an AWS request, SUPER AGENT validates the selected service, operation, and input parameters against the installed botocore service model. Unsupported operations and missing required parameters are rejected locally; every allowed catalog operation includes an official AWS Boto3 reference URL in its structured result.

Capacity and quota assessments

Capacity and quota requests use a narrow, deterministic investigation plan. SUPER AGENT calculates EC2 vCPU and memory from DescribeInstanceTypes, reads the account's actual EC2 on-demand standard-vCPU quota from Service Quotas, and reads applied EKS quotas. After an approved EKS connection it calculates Kubernetes allocatable CPU, memory, pod slots, node conditions, and resource limit coverage through the typed Kubernetes API.

It does not guess AWS quota defaults or infer capacity from instance-type names. If a quota, Kubernetes connection, or live Metrics Server data is not available, the response labels it unavailable. Normal output is limited to verified failures, measured utilization at or above 80%, and unavailable data.

EBS volumes

SUPER AGENT can list EBS volumes with size, type, encryption, attachment, and attachment-time evidence. For a request such as “last usage,” it checks the most recent observed VolumeReadOps or VolumeWriteOps CloudWatch data in a bounded lookback period. This is reported as recent observed I/O, not as a permanent “last used” timestamp, because EBS does not provide one.

License

Apache-2.0. See LICENSE.