Containerized Strands Agents

集装箱化绞线代理商

一个MCP服务器，在Docker容器中托管隔离的Strands AI代理。每个代理都使用自己的工作区独立运行，保存对话历史记录，并可以在重新启动后恢复。

特性

• 异步/非阻塞: send_message 立即返回（即发即弃）
• 隔离剂：每个代理都在自己的Docker容器中运行
• 会话保持：在容器重新启动时保存和恢复对话历史记录
• 自定义系统提示：通过文本或文件配置每个代理的系统提示
• MCP服务器支持：通过模型上下文协议将代理连接到外部工具
• GitHub集成：代理可以使用作用域访问令牌推送到存储库
• AWS配置文件支持：为不同的代理传递不同的AWS配置文件
• 重试逻辑：针对瞬态错误，采用指数回退自动重试
• 空闲超时：容器在可配置的不活动期后自动停止
• Web用户界面：用于管理代理和聊天的基于浏览器的界面

先决条件

• Python 3.11+
• Docker（正在运行）
• 在中配置的AWS凭据 ~/.aws/ 可以访问亚马逊基岩（克劳德模型）

快速开始

# Clone the repository
git clone 
cd containerized-strands-agents

# Install with web UI support
pip install -e ".[webui]"

# Start the web UI
containerized-strands-agents-webui

打开终端中显示的URL（通常http://localhost:8000)创建代理并与代理聊天。

安装

# Basic installation (MCP server only)
pip install -e .

# With web UI support
pip install -e ".[webui]"

# All features including dev tools
pip install -e ".[webui,dev]"

Docker镜像将在首次使用时自动构建。

用法

Web用户界面

containerized-strands-agents-webui
# or
python run_web_ui.py

服务器找到一个可用端口（从8000开始）并显示URL。使用web界面可以：

• 使用自定义系统提示创建新代理
• 与现有代理商聊天
• 查看代理状态和对话历史记录
• 停止空闲代理

作为MCP服务器（Kiro、Claude Desktop等）

添加到您的MCP配置中（例如。， ~/.kiro/settings/mcp.json):

{
  "mcpServers": {
    "containerized-strands-agents": {
      "command": "containerized-strands-agents-server",
      "env": {
        "CONTAINERIZED_AGENTS_GITHUB_TOKEN": "github_pat_xxxx",
        "CONTAINERIZED_AGENTS_MCP_CONFIG": "/path/to/mcp.json",
        "AWS_BEARER_TOKEN_BEDROCK": "optional-bearer-token"
      }
    }
  }
}

这 CONTAINERIZED_AGENTS_MCP_CONFIG env-var为该服务器生成的所有代理设置默认的mcp.json。您可以将其指向现有的Kiro配置或单独的配置。

MCP工具

send_message参数

send_message(
    agent_id="my-agent",
    message="Hello!",
    aws_profile="my-profile",               # Optional: AWS profile for Bedrock
    aws_region="us-west-2",                 # Optional (default: us-east-1)
    system_prompt="You are a pirate...",    # Optional: custom instructions
    system_prompt_file="/path/to/prompt",   # Optional (takes precedence over system_prompt)
    tools=["/path/to/tool.py"],             # Optional: per-agent tools
    data_dir="/path/to/project",            # Optional: custom data directory
    mcp_config_file="~/.kiro/settings/mcp.json",  # Optional: path to MCP config
    mcp_config={"mcpServers": {...}},       # Optional: inline MCP config
)

用于快照/还原的CLI命令

CLI提供创建和还原代理快照（备份）的命令：

创建快照

containerized-strands-agents snapshot --data-dir ./my-agent --output snapshot.zip

创建代理整个数据目录的zip存档，包括：

• 工作区文件
• 会话历史记录
• 系统提示
• 工具
• Runner文件

从快照还原

containerized-strands-agents restore --snapshot snapshot.zip --data-dir ./restored-agent

将快照提取到新（或现有）目录。恢复的代理立即准备运行。

示例：

# Backup an agent
containerized-strands-agents snapshot \
  --data-dir ./data/agents/my-project \
  --output backups/my-project-2024-01-01.zip

# Restore to a new location
containerized-strands-agents restore \
  --snapshot backups/my-project-2024-01-01.zip \
  --data-dir ./data/agents/my-project-restored

# Use with custom data directories
containerized-strands-agents snapshot \
  --data-dir ~/projects/agent-workspace \
  --output ~/backups/agent-snapshot.zip

笔记：

• 快照同时适用于默认数据目录(./data/agents/{id})以及定制
• CLI在创建快照之前验证目录结构
• 还原到现有目录将提示确认
• 恢复的代理可以使用MCP服务器或Web UI立即启动

从GitHub提取操作

containerized-strands-agents pull --repo owner/repo --run-id 12345 --data-dir ./my-agent

从GitHub Actions工件下载代理状态。可用于继续在CI中开始的工作。

选项：

• --repo （必填）：存储库位于 owner/repo 格式
• --run-id：从特定工作流运行中下载工件
• --artifact：按名称下载特定工件
• --data-dir：目标目录（默认： ./agent-data)
• --token：GitHub令牌（使用 GITHUB_TOKEN env-var（如果未提供）

示例：

# Pull from a specific run
containerized-strands-agents pull \
  --repo myorg/my-repo \
  --run-id 12345678 \
  --data-dir ./data/agents/from-gha

# Pull a specific artifact by name
containerized-strands-agents pull \
  --repo myorg/my-repo \
  --artifact agent-data-default-agent-42 \
  --data-dir ./restored-agent

# Uses gh CLI if available, otherwise GitHub API with token
export GITHUB_TOKEN="ghp_xxxx"
containerized-strands-agents pull --repo myorg/my-repo --run-id 12345

GitHub操作工作流

工作流模板提供于 templates/gha-agent-workflow.yml 在GitHub Actions中运行代理：

# Copy to your repo
cp templates/gha-agent-workflow.yml .github/workflows/run-agent.yml

工作流程：

1. 从以前的工件恢复代理状态（可选）
2. 使用您的消息运行代理
3. 将更新状态作为工件上传

触发方式 workflow_dispatch 通过消息输入。有关所需的机密（AWS凭据），请参阅模板。

配置

环境变量

这些变量配置MCP服务器。将它们设置在您的 mcp.json （根据 env)或者在运行web UI之前将它们导出到shell中。

服务器配置：

传递到集装箱 （代理人可以使用这些）：

web UI示例：

export CONTAINERIZED_AGENTS_GITHUB_TOKEN="github_pat_xxxx"
export AWS_BEARER_TOKEN_BEDROCK="your-token"  # Optional: alternative Bedrock auth
containerized-strands-agents-webui

AWS设置

代理商使用 亚马逊基岩 默认情况下使用Claude模型。您有两个选择：

选项1:AWS凭据（默认）

你的 ~/.aws/credentials 以只读方式安装到容器中。确保您的个人资料具有基岩访问权限。

# Verify AWS credentials
aws sts get-caller-identity

# Check Bedrock model access (us-east-1)
aws bedrock list-foundation-models --region us-east-1 --query "modelSummaries[?contains(modelId, 'claude')]"

选项2：不记名代币

集 AWS_BEARER_TOKEN_BEDROCK 作为基岩的替代认证方法。

GitHub令牌设置（可选）

对于需要推送到GitHub存储库的代理：

1. 创建一个 细粒度个人访问令牌
2. 选择“仅选择存储库”并选择您的存储库
3. 授予“内容：读写”权限
4. 集 CONTAINERIZED_AGENTS_GITHUB_TOKEN 环境变量

代理能力

每个代理都可以访问：

• file_read, file_write, editor -文件操作
• shell -执行shell命令
• python_repl -运行Python代码
• use_agent -Spawn子代理
• load_tool -动态加载其他工具
• GitHub工具-创建/更新问题和PR
• MCP工具 -来自已配置MCP服务器的任何工具

重要：代理人在 /data/workspace 在容器内。此目录在容器重新启动后仍然存在。

MCP服务器支持

代理可以连接到外部MCP（模型上下文协议）服务器以获取其他工具。这使用与Kiro/Claude Desktop相同的配置格式。

快速设置：使用现有配置

将代理指向您现有的Kiro mcp.json：

# Set as default for all agents
export CONTAINERIZED_AGENTS_MCP_CONFIG="~/.kiro/settings/mcp.json"
containerized-strands-agents-webui

或通过MCP工具按代理人：

send_message(
    agent_id="researcher",
    message="Search AWS docs for Lambda limits",
    mcp_config_file="~/.kiro/settings/mcp.json"
)

内联MCP配置

send_message(
    agent_id="docs-agent",
    message="What is Amazon S3?",
    mcp_config={
        "mcpServers": {
            "aws-docs": {
                "command": "uvx",
                "args": ["awslabs.aws-documentation-mcp-server@latest"]
            },
            "perplexity": {
                "command": "npx",
                "args": ["-y", "@anthropic-ai/mcp-server-perplexity"],
                "env": {"PERPLEXITY_API_KEY": "pplx-xxx"}
            }
        }
    }
)

配置格式

与Kiro/Claude桌面版相同：

{
  "mcpServers": {
    "server-name": {
      "command": "uvx",
      "args": ["package-name@latest"],
      "env": {"API_KEY": "..."},
      "disabled": false
    }
  }
}

配置优先级

1. mcp_config_file param（mcp.json的路径）
2. mcp_config param（内联字典）
3. 代理的持久配置(.agent/mcp.json)
4. CONTAINERIZED_AGENTS_MCP_CONFIG env-var（全局默认值）

MCP配置是每个代理持久化的，因此您只需要设置一次。发送给同一代理的后续消息将使用保存的配置。

支持的交通工具

• 标准 （默认）：本地命令行MCP服务器通过 uvx 或 npx
• 上海证券交易所：基于HTTP的远程MCP服务器

备注

• uvx 和 npx 预先安装在容器中-无需安装单个MCP服务器
• 配置中的环境变量（如 ${GITHUB_TOKEN})在运行时进行扩展
• 已禁用服务器("disabled": true)被跳过
• 打开失败：如果MCP服务器连接失败，代理仍将使用其他工具启动。检查容器日志中的连接错误。

数据持久层

data/
├── tasks.json              # Agent registry
└── agents/{agent_id}/
    ├── workspace/          # Agent's persistent files
    └── .agent/
        ├── session/        # Conversation history (FileSessionManager)
        ├── system_prompt.txt   # Custom system prompt
        ├── tools/          # Per-agent tools
        └── runner/         # Agent code for standalone execution

发展

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
python -m pytest tests/ -v

# Run only unit tests (no Docker required)
python -m pytest tests/test_agent_manager.py -v

# Rebuild Docker image after changes
./scripts/build_docker.sh

故障排除

找不到Docker映像：运行 ./scripts/build_docker.sh 手动地

基岩通道被拒绝：确保您的AWS凭据具有Bedrock权限，并且在您所在的地区启用了该模型

代理卡住处理：检查容器日志 docker logs agent-

端口已在使用中：web UI自动查找可用端口；检查终端输出中的实际URL

许可证

麻省理工学院