Strands integration - package docs

strands-stigmer

The execution graph of AWS for Strands agents. Verified method contracts, least-privilege IAM policies, pre-flight authorization, a pre-action hook, and a scoped use_aws.

strands-stigmer gives Strands agents the Stigmer execution graph of AWS: verified method contracts with required parameters, IAM permissions, pagination contracts, call-chain links, and known traps. It is backed by an open MCP knowledge network with 30,000+ contracts across 380 services. No API keys, no accounts.

Install

pip install strands-stigmer

Usage

Add the tools to your agent, plus the pre-action hook to authorize AWS tool calls before they execute:

from strands import Agent
from strands_stigmer import stigmer_query, stigmer_policy, stigmer_authorize
from strands_stigmer.hooks import StigmerAuthHook

agent = Agent(
    tools=[stigmer_query, stigmer_policy, stigmer_authorize],
    hooks=[StigmerAuthHook()],
)

# Generate a least-privilege IAM policy for a workflow
agent("Generate the least-privilege policy for an S3 multipart upload with KMS encryption")

# Pre-flight check: is s3:PutObject allowed for the current role?
agent("Before you call S3, check whether I'm authorized to put objects")

Every use_aws tool call is now checked before execution. If AWS's own policy simulator reports the current identity is denied, the call is cancelled with the missing permissions listed. When the simulator cannot answer (unknown), the call passes through by default; pass StigmerAuthHook(fail_closed=True) to block unverifiable calls too.

Tools

stigmer_query

stigmer_query(query, library="")

Search verified method contracts: required params, IAM permissions, pagination contract, call-chain links, and known traps. library scopes to one SDK: "boto3" or "aws-sdk-js".

stigmer_policy

stigmer_policy(workflow="", operations="", description="")

Generate a least-privilege IAM policy. Pass one of a named workflow (see stigmer_list_workflows), explicit operations as IAM actions or SDK symbols, or a description in plain language. Returns a paste-ready policy grouped by service, with a confidence tier and any unresolved operations.

stigmer_list_workflows

stigmer_list_workflows()

List the curated named workflows available for policy generation.

stigmer_authorize

stigmer_authorize(operations="", workflow="", principal_arn="")

Pre-flight authorization check. Resolves the IAM actions an operation requires, then asks AWS's own policy simulator (SimulatePrincipalPolicy) whether the current role (or a given principal) allows them. Returns resolution (exact|partial|unresolved) and evaluation (allowed|denied|unknown) as separate fields, plus missing_permissions and the simulator's documented caveats. evaluation is populated only when the calling environment has AWS credentials; otherwise it is unknown with the reason.

stigmer_verify

stigmer_verify(workflow="", operations="", policy="")

Feed a generated policy back to AWS's own evaluator (SimulateCustomPolicy) and confirm it grants exactly the intended operations and nothing extra. Returns verified (True|False|unknown), grants_all, and grants_extra. verified is populated only when the calling environment has AWS credentials.

Pre-action hook

StigmerAuthHook

StigmerAuthHook(fail_closed=False)

A BeforeToolCallEvent hook that authorizes AWS tool calls before they execute. For each use_aws call it resolves the operation to its required IAM actions and asks AWS's own simulator whether the current identity allows them.

evaluation: denied cancels the call and lists the missing permissions; allowed passes through; unknown passes through by default, or blocks when fail_closed=True. It covers any tool with a service/operation shape, not just use_aws, with no upstream changes required.

Scoped use_aws

stigmer_use_aws

stigmer_use_aws(service_name, operation_name, parameters={}, region="us-west-2", profile_name=None, role_arn=None, session_policy=None)

A drop-in replacement for use_aws that adds per-call credential scoping. With role_arn and session_policy, the call runs against an sts:AssumeRole session whose effective permissions are the intersection of the role's policies and the supplied least-privilege policy.

Without them it behaves exactly like use_aws (ambient session). session_policy without role_arn raises a clear error, because the ambient session is fixed at process launch and cannot be narrowed, so scoping requires an assumed role.

Write back

Stigmer grows from agent contributions. If your agent hits a trap not in the network, register the fix so the next agent walks around it:

from strands import tool

@tool
def stigmer_register(action: str, symbol: str, error: str, fix: str) -> str:
    """Register a fix with Stigmer. action: 'confirm' | 'append_thread' | 'new_receipt'."""
    # Posts to the Stigmer MCP endpoint; see https://stigmer.network/mcp
    ...

Links