{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Strands Agents Integration","description":"Control the power of AI Agents in runtime.","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"strands-agents-integration","__idx":0},"children":["Strands Agents Integration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Connect agents built with ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://strandsagents.com"},"children":["Strands Agents"]},", AWS's open-source Python SDK, to Capsule Security for visibility into every prompt, tool call, and reply - with inline policy enforcement before the model call and before each tool runs, and an inventory of each agent's system prompt, model, and tools."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"overview","__idx":1},"children":["Overview"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This integration uses the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["capsule-strands"]}," Python package, a Strands plugin that runs in-process inside your agent. The plugin registers on the Strands hook system, forwards each event to your Capsule tenant over HTTPS, and applies the server's verdict on the hooks that support inline blocking."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Strands agents are operator-deployed - you run them in your own infrastructure, so there is no SaaS install. The only thing exchanged at install time is a signed token that scopes the plugin to your tenant and environment."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following hooks are configured:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Hook"},"children":["Hook"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["BeforeInvocationEvent"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Blocking"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The user's prompt before the model is called - can cancel the invocation"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["BeforeToolCallEvent"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Blocking"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The tool name and input before the tool runs - can cancel the tool call"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["AfterToolCallEvent"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Observation"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The tool result"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["AfterInvocationEvent"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Observation"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The agent's reply"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Session start"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Observation"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Sent on the first invocation of each agent session, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#session-start-data"},"children":["Session Start Data"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Blocking hooks wait for Capsule's verdict. When Capsule blocks a prompt, the invocation is cancelled and the agent returns the policy's reason instead of calling the model. When Capsule blocks a tool call, the call is cancelled and the model receives an error tool result carrying the reason. The deprecated ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Agent.structured_output()"]}," method is gated as well; a blocked prompt raises ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["capsule_strands.CapsuleBlockedError"]}," carrying the reason. Observation hooks are recorded for audit and never block. The session start is sent before the first prompt is judged; tool results and replies are posted from a background thread, in the order they happened, so they do not slow the agent down."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"session-start-data","__idx":2},"children":["Session Start Data"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["On the first invocation of each agent session, the plugin sends the agent's:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["ID and name"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Description"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["System prompt"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Model ID"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Registered tools"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Capsule uses this to build the agent's inventory entry."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"sessions-and-agent-identity","__idx":3},"children":["Sessions and Agent Identity"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Capsule groups events into a session using the first of these that is available:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["trace_attributes[\"session.id\"]"]},", if the agent sets it"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The session ID of the agent's session manager"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A random ID generated per ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Agent"]}," instance"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Capsule identifies an agent by its ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["agent_id"]},". When ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["agent_id"]}," is left at the Strands SDK default, the agent's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["name"]}," is used instead. Set an explicit ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["agent_id"]}," on every agent so its identity does not change if you rename it."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"prerequisites","__idx":4},"children":["Prerequisites"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before you begin, ensure you have:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A Python project that builds agents with ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Strands Agents"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["strands-agents"]}," 1.43 or later)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Capsule Security"]}," account with admin access"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Network access from the host running your agent to your Capsule agentsecurity endpoint (e.g. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://agents.capsule.security"]},")"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-1-generate-a-plugin-token","__idx":5},"children":["Step 1: Generate a Plugin Token"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Log in to the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Capsule Security"]}," portal."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Navigate to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Integrations"]}," and locate ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Strands Agents"]},"."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Install"]}," - Capsule generates a JWT scoped to your tenant and Strands environment. The token contains the tenant and environment claims required by the agentsecurity endpoint; treat it as a secret."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Copy the generated ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["endpoint"]}," and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["token"]},". You will set both in the next steps."]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-2-install-the-package","__idx":6},"children":["Step 2: Install the Package"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Install ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["capsule-strands"]}," into the same Python environment that runs your agent:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"pip install capsule-strands\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The package requires ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["strands-agents"]}," 1.43 or later."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-3-configure-the-plugin","__idx":7},"children":["Step 3: Configure the Plugin"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The plugin reads its configuration from environment variables. Set the endpoint and token in the environment where the agent runs:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"export CAPSULE_STRANDS_ENDPOINT=https://agents.capsule.security/v1/strands/hooks/events\nexport CAPSULE_STRANDS_TOKEN=<token from Step 1>\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The same settings can be passed as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CapsulePlugin"]}," constructor arguments. A constructor argument takes precedence over the matching environment variable, which is used when the argument is omitted."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"configuration-options","__idx":8},"children":["Configuration Options"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Constructor Argument"},"children":["Constructor Argument"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Env Variable"},"children":["Env Variable"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Default"},"children":["Default"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["endpoint"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CAPSULE_STRANDS_ENDPOINT"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["string"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["(required)"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Capsule Strands hooks endpoint, e.g. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://agents.capsule.security/v1/strands/hooks/events"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["token"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CAPSULE_STRANDS_TOKEN"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["string"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["(required)"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["JWT generated in Step 1, scoped to your tenant and environment"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["block_on_risk"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CAPSULE_STRANDS_BLOCK_ON_RISK"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["boolean"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Apply server ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["block"]}," verdicts inline on prompts and tool calls. Set to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]}," to run in observe-only mode"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fail_open"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CAPSULE_STRANDS_FAIL_OPEN"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["boolean"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["When Capsule is unreachable or returns an error, allow the agent to proceed. Set to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]}," to fail closed"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["timeout_ms"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CAPSULE_STRANDS_TIMEOUT_MS"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["number"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["35000"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["How long to wait for a verdict, in milliseconds"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"token-storage","__idx":9},"children":["Token Storage"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Never commit the JWT to version control. Recommended approaches:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Keep the token in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CAPSULE_STRANDS_TOKEN"]}," environment variable of the process that runs the agent"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Source it from your secret manager (1Password, AWS Secrets Manager, HashiCorp Vault) at runtime"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Deliver it through the same channel that distributes the rest of your agent's deployment configuration"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-4-attach-the-plugin-to-your-agent","__idx":10},"children":["Step 4: Attach the Plugin to Your Agent"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CapsulePlugin()"]}," to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["plugins"]}," list of each agent you want Capsule to govern:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"from strands import Agent\nfrom capsule_strands import CapsulePlugin\n\nagent = Agent(\n    agent_id=\"support-agent\",\n    name=\"Acme Support Agent\",\n    system_prompt=\"You answer Acme billing questions.\",\n    tools=[...],\n    plugins=[CapsulePlugin()],\n)\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To set the behavior options in code, pass them as constructor arguments. They override the matching environment variables:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"plugin = CapsulePlugin(fail_open=False, timeout_ms=10000)\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Restart your agent so it loads the plugin and the environment variables."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-5-verify-the-installation","__idx":11},"children":["Step 5: Verify the Installation"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Run your agent and send it a prompt that calls a tool to generate activity."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Log in to the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Capsule Security"]}," portal."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Navigate to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Inventory > Agents"]}," and confirm your Strands agent appears with its system prompt, model, and tools."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Click on the agent and review the audit logs to verify events are captured:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Session start event"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The user prompt"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Tool calls and their results"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The agent's reply"]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"troubleshooting","__idx":12},"children":["Troubleshooting"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If events are not appearing:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Verify the endpoint is reachable"]}," from the host running your agent:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -sS -o /dev/null -w \"%{http_code}\\n\" https://agents.capsule.security/v1/strands/hooks/events\n","lang":"bash"},"children":[]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Verify the environment variables are set"]}," - ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CAPSULE_STRANDS_ENDPOINT"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CAPSULE_STRANDS_TOKEN"]}," must be present in the environment of the process that runs the agent, not only in your interactive shell. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CapsulePlugin()"]}," raises a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ValueError"]}," when either is missing."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Verify the plugin is attached"]}," - ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["plugins=[CapsulePlugin()]"]}," must be on the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Agent"]}," that handles the request. Run ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pip show strands-agents"]}," to confirm version 1.43 or later."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Check the agent identity"]}," - an agent appears under its ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["agent_id"]},", or under its ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["name"]}," when ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["agent_id"]}," is left at the SDK default. Set an explicit ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["agent_id"]}," to make it easy to find."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Check for timeouts"]}," - if your network has high latency to the Capsule endpoint, increase ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["timeout_ms"]}," or confirm ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fail_open"]}," is set appropriately."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Inspect the agent logs"]}," - the plugin logs every failed request to Capsule as a warning on the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["capsule_strands"]}," logger."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Contact Capsule Security support"]}," if issues persist."]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"not-supported-yet","__idx":13},"children":["Not Supported Yet"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["MCP server attribution"]}," - tools provided by an MCP server appear in Capsule as plain Strands tools, not attributed to their MCP server."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["End-user identity"]}," - events are not attributed to the end user of the agent."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"security-considerations","__idx":14},"children":["Security Considerations"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Capsule plugin runs in-process inside your agent and observes every prompt, tool call, tool result, and reply. Before deploying:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Protect the JWT"]}," - anyone with the token can post events on behalf of your tenant. Rotate it through the portal if it is exposed."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Choose ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fail_open"]}," deliberately"]}," - ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]}," (the default) prioritizes agent availability and lets actions through when Capsule is unreachable; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]}," prioritizes policy enforcement and blocks prompts and tool calls when Capsule cannot be reached."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["timeout_ms"]}," for your latency budget"]}," - blocking hooks wait up to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["timeout_ms"]}," for a verdict, so the default of 35 seconds can delay the agent when Capsule is slow to answer."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Pin a plugin version"]}," in production (for example ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["capsule-strands==<version>"]}," in your requirements file) and review changelogs before upgrading."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Use TLS-only endpoints"]},". The plugin sends a Bearer token on every request - never configure an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["http://"]}," endpoint outside local development."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"support","__idx":15},"children":["Support"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For help with this integration:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Email"]},": support@capsule.security"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Include"]},": Your organization ID, integration status, plugin version, and any error messages"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"references","__idx":16},"children":["References"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://strandsagents.com"},"children":["Strands Agents"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://pypi.org/project/capsule-strands/"},"children":["Capsule Strands Plugin on PyPI"]}]}]}]},"headings":[{"value":"Strands Agents Integration","id":"strands-agents-integration","depth":1},{"value":"Overview","id":"overview","depth":2},{"value":"Session Start Data","id":"session-start-data","depth":3},{"value":"Sessions and Agent Identity","id":"sessions-and-agent-identity","depth":3},{"value":"Prerequisites","id":"prerequisites","depth":2},{"value":"Step 1: Generate a Plugin Token","id":"step-1-generate-a-plugin-token","depth":2},{"value":"Step 2: Install the Package","id":"step-2-install-the-package","depth":2},{"value":"Step 3: Configure the Plugin","id":"step-3-configure-the-plugin","depth":2},{"value":"Configuration Options","id":"configuration-options","depth":3},{"value":"Token Storage","id":"token-storage","depth":3},{"value":"Step 4: Attach the Plugin to Your Agent","id":"step-4-attach-the-plugin-to-your-agent","depth":2},{"value":"Step 5: Verify the Installation","id":"step-5-verify-the-installation","depth":2},{"value":"Troubleshooting","id":"troubleshooting","depth":3},{"value":"Not Supported Yet","id":"not-supported-yet","depth":2},{"value":"Security Considerations","id":"security-considerations","depth":2},{"value":"Support","id":"support","depth":2},{"value":"References","id":"references","depth":2}],"frontmatter":{"seo":{"title":"Strands Agents Integration"}},"lastModified":"2026-11-01T08:56:27.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/strands","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}