使用说明

集装箱化绞线代理商

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

特性

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

先决条件

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

快速开始

# Clone the repository
git clone <repo-url>
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`	将消息发送到代理（即发即弃），如果需要，创建代理
`get_messages`	获取对话历史记录（按需使用，不用于轮询）
`list_agents`	列出所有代理及其状态
`stop_agent`	停止代理的容器

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

工作流程：

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

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

配置

环境变量

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

服务器配置：

变量	默认值	描述
`CONTAINERIZED_STRANDS_DATA_DIR`	`./data`	持久性的基本目录
`AGENT_HOST_IDLE_TIMEOUT`	`720`	闲置集装箱停止前几分钟（12小时）
`CONTAINERIZED_AGENTS_SYSTEM_PROMPTS`	-	提示文件的逗号分隔路径
`CONTAINERIZED_AGENTS_TOOLS`	-	全局工具目录的路径
`CONTAINERIZED_AGENTS_MCP_CONFIG`	-	所有代理的默认mcp.json路径

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

变量	描述
`CONTAINERIZED_AGENTS_GITHUB_TOKEN`	GitHub PAT用于git推送访问
`OPENAI_API_KEY`	OpenAI API密钥（适用于OpenAI模型）
`GOOGLE_API_KEY`	Google/Gemini API密钥
`AWS_BEARER_TOKEN_BEDROCK`	用于Bedrock身份验证的AWS承载令牌

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存储库的代理：

创建一个细粒度个人访问令牌
选择“仅选择存储库”并选择您的存储库
授予“内容：读写”权限
集 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
    }
  }
}

配置优先级

mcp_config_file param（mcp.json的路径）
mcp_config param（内联字典）
代理的持久配置(.agent/mcp.json)
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-<agent-id>

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

许可证

麻省理工学院