Skip to main content

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-agent-bedrock
super-agent

Ask a one-off question:

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

Or start an interactive session:

super-agent --interactive

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

super-agent --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-agent --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 AGENT 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-agent --account-id 123456789012
super-agent --account-id 123456789012 --role-name Platform/CrossAccountAgentRole
super-agent --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. If verification fails, the previous account stays active.

Cross-account requests inside the agent

You don't need to switch accounts first. Ask in plain language and the agent addresses each account per tool call:

list EKS clusters in account 333333333333
compare running EC2 vCPU in 222222222222 and 333333333333
who deleted the bucket logs-archive in account 333333333333 yesterday?

Every AWS tool accepts an optional account_id. For each call SUPER AGENT assumes <account>:role/<--role-name> (with --external-id if set), checks through STS that it landed in that exact account, and tags the result and audit record with account_id. Write approvals always name the account.

  • Accounts in --allowed-accounts (or SUPER_AGENT_ALLOWED_ACCOUNTS), the active account, and the source account need no extra prompt.
  • Any other account needs your approval once per interactive session. In one-shot mode it is refused unless allowlisted or --approve is given.
  • aws_account_context shows the agent which accounts are available, and organizations.list_accounts resolves account names when the source identity is an Organizations management or delegated-admin account.

Bedrock is invoked with the source credentials, so target accounts do not need their own Bedrock model access. Use --bedrock-in-target-account for the previous behavior.

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-agent-bedrock[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-agent-bedrock[ui]"

Audit log and fresh sessions

SUPER AGENT stores a sanitized append-only audit log named super_agent.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 approve an EKS connection. The agent builds the EKS bearer token in-process from the verified account session (no kubeconfig file or AWS CLI needed), so clusters in other accounts work too. The role needs an EKS access entry on the cluster. This connects through the Kubernetes API; it does not open an interactive SSH, SSM, or pod-exec session.

Local diagnostics only run directly when the input is clearly a command (ls -la, df -h) or uses the ! prefix. Questions such as "find stopped instances" go to the agent. Local commands never receive AWS credentials.

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.

Metadata

Release files for super-agent-bedrock 0.6.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for super-agent-bedrock 0.6.0
File Size Uploaded Provenance Actions
super_agent_bedrock-0.6.0.tar.gz 76.9 kB Without provenance Details for super_agent_bedrock-0.6.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for super-agent-bedrock 0.6.0
File Interpreter ABI Platform Actions
super_agent_bedrock-0.6.0-py3-none-any.whl Python 3 none any Details for super_agent_bedrock-0.6.0-py3-none-any.whl

Total release size: 139.6 kB

Release files / super_agent_bedrock-0.6.0.tar.gz

Download URL super_agent_bedrock-0.6.0.tar.gz
Size 76.9 kB
Tags Source
SHA-256 checksum
How to use checksums
d7f43faa8494e00e5e1dbf690cd5d5115ea970b1fd67c8052c65064174fb331b
BLAKE2b-256 checksum
How to use checksums
765268149c997629d53a5f707ad5b32b80045f5da48237a4915b4a58d15e5904
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.3

Release files / super_agent_bedrock-0.6.0-py3-none-any.whl

Download URL super_agent_bedrock-0.6.0-py3-none-any.whl
Size 62.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
37f9d08e0f818929272324c5b0834fbc37c1c197b35299281834b9894b7e43fd
BLAKE2b-256 checksum
How to use checksums
d0a1bb3428ed29123be42283f5ddf284bf26a0e0a6ba04a57984b9a52ad97e20
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.3

Security for super-agent-bedrock 0.6.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.6.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page