sandbaseai/managed-agents
GitHub: sandbaseai/managed-agents
一个开源的 CMA 兼容企业级 AI agent 运行时，提供本地多 Agent 系统运行、治理与可观测性所需的全套基础设施。
Stars: 196 | Forks: 9
# managed-agents
**SandBase managed-agents 是面向企业 AI agent 的安全、本地优先的 runtime 层。**
`managed-agents` 提供了用于 session、工具、审批、沙盒执行、memory、credential vaults、audit trails、可重放事件以及运维可见性的 runtime 基础设施，帮助团队将 AI agent 从演示阶段推向生产环境。它公开了与 Claude Managed Agents 兼容的 Console 和 `/v1` 资源 API，同时默认将 runtime 元数据保存在项目外部的 SQLite 中。
使用它可以构建和运行自托管 AI agent、本地开发者 agent、桌面端 agent runtime、支持 MCP 的 workflow 以及企业概念验证，而无需将您的 runtime 层绑定到单一模型提供商。
## 为什么选择 managed-agents？
Agent SDK 非常适合编写 agent 循环。但生产级 agent 需要更多内容：状态、session 历史记录、工具治理、沙盒边界、credential 处理、memory、可审计性，以及供人类检查发生了什么的 Console。
`managed-agents` 专注于该 runtime 层。它不是可视化的 workflow 构建器，也不是另一个模型 SDK。它是一个开源的控制平面，用于在本地或自托管环境中运行、观察和治理 AI agent。
## 功能
- Claude Managed Agents 风格的 Console 和 `/v1` 资源 API
- 基于 SQLite 的 agent、skill、session、environment、credential vault、memory store、API key 和文件元数据
- 可恢复的 Server-Sent Events，用于 session 时间线、调试、审计和重放
- 文件资源、memory store、credential vault 和 environment 模板
- 用于共享本地 runtime 的本地 API key 和 bearer-token 身份验证
- 可选的 `agents/*.yaml` 和 `skills/*/SKILL.md` seed/import 文件夹
- 支持本地、Docker 和自托管 sandbox provider
- MCP 工具集、内置工具、权限策略和 skill 包
- 兼容 OpenAI、兼容 Ollama 和 Anthropic 的模型 adapter
- 可选的 TypeScript 便捷 SDK，位于 `managed-agents/sdk`
## 常见用例
- 运行本地 Claude Managed Agents 风格的 Console 以进行 agent 开发
- 构建具有可审计 session 和工具调用的自托管企业 AI agent
- 构建客户支持、事件响应、研究、数据分析和软件工程 agent 的原型
- 打包可重用的 agent 模板、MCP 连接器、权限策略和 skill 以用于现场部署
- 将 agent runtime 嵌入未来的桌面应用程序或私有内部平台中
## 要求
- Node.js 22 或更高版本
- npm 10 或更高版本
- 已配置的模型供应商 API key 或本地兼容 OpenAI 的 endpoint
Docker 是可选的，仅在您需要 Docker 支持的 sandbox 时才需要。
## 安装
通过 `npx` 使用 CLI：
```
npx managed-agents init
npx managed-agents start
```
或者全局安装：
```
npm install -g managed-agents
managed-agents init
managed-agents start
```
对于源码构建：
```
git clone git@github.com:sandbaseai/managed-agents.git
cd managed-agents
npm ci
npm run build
```
然后在源码检出目录之外创建并运行一个 agent 工作区：
```
mkdir ../my-agents
cd ../my-agents
node ../managed-agents/dist/index.js init
node ../managed-agents/dist/index.js start
```
## 运行工作区
创建一个工作区：
```
mkdir my-agents
cd my-agents
npx managed-agents init
```
如果您是从源码检出运行的，请将 `npx managed-agents` 替换为 `node /path/to/managed-agents/dist/index.js`。
启动 runtime：
```
npx managed-agents start
# source checkout:
# node /path/to/managed-agents/dist/index.js start
```
打开 Dashboard：
```
http://127.0.0.1:3000/dashboard
```
打开 `Settings > Models` 并配置单一工作区模型供应商：vendor、可选的 base URL 和 API key。Dashboard 将 Settings V2 存储在用户数据目录下的 runtime SQLite 数据库中。使用 `model: default` 的 agent 将通过该配置的供应商运行；具体的模型 ID 仍然是 adapter 所有的实现细节。正常的本地使用不需要修改源码控制的文件。
API 可在以下地址访问：
```
http://127.0.0.1:3000/v1
```
在 Dashboard 中，打开 `Settings > API reference` 以查看 Claude 风格的开发者参考页面。它显示了活动的 base URL、身份验证模式、分组的 endpoint、参数描述、返回字段，以及根据您正在运行的 runtime 生成的可复制的 `curl` 和 TypeScript SDK 示例。
## 工作区布局
```
my-agents/
+-- agents/ # Optional seed agent definitions
| +-- assistant.yaml
+-- skills/ # Optional seed skill packages
| +-- example-skill/
| +-- SKILL.md
+-- managed-agents.config.yaml
```
默认情况下，Runtime 状态存储在仓库外部：
```
~/.managed-agents/-/
+-- data.db # SQLite metadata store
+-- files/ # Uploaded file bytes
+-- skills/ # Uploaded custom skill package assets
+-- snapshots/ # Session workspace snapshots
+-- sandbox/ # Local session workspaces
```
设置 `MANAGED_AGENTS_HOME` 或传递 `--data-dir` 以覆盖此位置。
## Agent 定义
Agent 使用以下 Claude Managed Agents 风格的结构。Console/API 会生成稳定的 `agent_...` ID。`name` 是人类可读的标签，而不是文件系统路径或唯一性键。
```
name: Incident commander
description: Triages alerts, opens incident tickets, and coordinates status updates.
model: default
system: |-
You are an on-call incident commander. Be decisive, cite the evidence you used,
and recommend rollback when confidence is high.
mcp_servers:
- name: sentry
type: url
url: https://mcp.sentry.dev/mcp
- name: linear
type: url
url: https://mcp.linear.app/mcp
tools:
- type: agent_toolset_20260401
default_config:
enabled: true
permission_policy:
type: always_ask
configs:
- name: read
enabled: true
- name: grep
enabled: true
- name: bash
enabled: true
permission_policy:
type: always_ask
- type: mcp_toolset
mcp_server_name: sentry
default_config:
permission_policy:
type: always_allow
- type: mcp_toolset
mcp_server_name: linear
default_config:
permission_policy:
type: always_allow
skills:
- type: anthropic
skill_id: pdf
metadata:
template: incident-commander
```
在常规路径下使用 `model: default`。工作区的 Settings 页面会将该名称映射到配置的供应商，并且每个供应商的 adapter 拥有其默认的具体模型 ID。Runtime 设置存储在 runtime 数据目录下的 SQLite 中。当 API 客户端需要诸如 `speed` 之类的额外控制时，它们也可以发送模型配置对象。
## Dashboard
Dashboard 提供了一个本地 Console，用于：
- 创建和编辑 agent
- 启动 session 并查看记录
- 检查 session 调试事件
- 创建 environment
- 管理 credential vault
- 上传文件
- 创建和编辑 memory store
- 上传 skill
- 创建和归档本地 API key
- 阅读有关 `/v1` endpoint、SDK 片段和 Skill 上传示例的内置 API 参考
- 查看 Settings 中的 model、循环引擎行为、存储、sandbox、API key、API 参考、日志和监控
- 重启 runtime 并从 Settings 中查看最近的结构化日志
在 Dashboard 中打开 `Settings > API reference` 可查看活动的 base URL、身份验证模式、核心服务 endpoint、可复制的 `curl` 示例、SDK 片段以及所需的 Skill 包结构。
## CLI
```
managed-agents init
managed-agents start --host 127.0.0.1 --port 3000
managed-agents list
managed-agents reload
managed-agents chat --message "hello"
managed-agents template list
managed-agents template install
managed-agents template create
```
## API 示例
创建一个 agent：
```
curl -X POST http://127.0.0.1:3000/v1/agents \
-H "Content-Type: application/json" \
-d '{
"name": "Incident commander",
"description": "Triages alerts and coordinates incident response.",
"model": "default",
"system": "You are an on-call incident commander.",
"tools": [{ "type": "agent_toolset_20260401" }],
"metadata": { "template": "incident-commander" }
}'
```
响应包含用于 session 的稳定 `agent_...` ID。Agent 名称是显示标签；通过 Console/API 创建的 agent 会接收服务器生成的 ID，并且不依赖从名称派生的标识符。
创建一个 environment：
```
curl -X POST http://127.0.0.1:3000/v1/environments \
-H "Content-Type: application/json" \
-d '{
"name": "Default cloud",
"config": {
"type": "cloud",
"networking": {
"type": "limited",
"allow_mcp_servers": true,
"allow_package_managers": true,
"allowed_hosts": ["api.github.com"]
},
"packages": {
"type": "packages",
"pip": ["pytest"],
"npm": ["typescript"]
}
}
}'
```
响应包含用于 session 的稳定 `env_...` ID。Environment 名称是显示标签，不需要唯一。
创建一个 memory store：
```
curl -X POST http://127.0.0.1:3000/v1/memory_stores \
-H "Content-Type: application/json" \
-d '{
"name": "Incident notes",
"description": "Long-lived incident context and follow-up notes.",
"metadata": { "team": "platform" }
}'
```
上传一个 Skill 包：
```
zip -r code-review-assistant.zip code-review-assistant
curl -X POST http://127.0.0.1:3000/v1/skills \
-F "files=@code-review-assistant.zip"
```
该归档文件必须包含一个顶层目录和一个根 `SKILL.md` 文件：
```
code-review-assistant/
+-- SKILL.md
+-- references/
+-- checklist.md
```
`SKILL.md` 必须以包含 `name` 和 `description` 的 YAML frontmatter 开头。服务器会生成稳定的 `skill_...` ID；Skill 名称从包元数据中读取，然后可以附加到 agent 上：
```
skills:
- type: custom
skill_id: skill_...
```
Memory store 名称是供人类和提示使用的标签；它们不需要是唯一的。将 store 挂载到 session 中时，请使用返回的 `memstore_...` ID。
创建一个 credential vault 并添加一个 credential：
```
curl -X POST http://127.0.0.1:3000/v1/credential-vaults \
-H "Content-Type: application/json" \
-d '{ "name": "production-tools" }'
curl -X POST http://127.0.0.1:3000/v1/credential-vaults/vlt_.../credentials \
-H "Content-Type: application/json" \
-d '{
"name": "github-token",
"auth_type": "environment_variable",
"variable_name": "GITHUB_TOKEN",
"value": "ghp_example",
"network": {
"type": "limited",
"allowed_hosts": ["api.github.com"]
},
"injection_locations": ["request_headers"]
}'
```
Credential 记录使用 `mcp_oauth`、`bearer_token` 或 `environment_variable` 作为 `auth_type` 值。Secret 值在静态存储时加密，绝不会通过列表或检索响应返回。
创建一个 session：
```
curl -X POST http://127.0.0.1:3000/v1/sessions \
-H "Content-Type: application/json" \
-d '{
"agent": "agent_...",
"environment_id": "env_...",
"title": "Sentry alert triage",
"resources": [
{
"type": "memory_store",
"memory_store_id": "memstore_...",
"access": "read_write",
"instructions": "Use this store for incident timelines and decisions."
}
]
}'
```
发送一个用户事件：
```
curl -X POST http://127.0.0.1:3000/v1/sessions/SESSION_ID/events \
-H "Content-Type: application/json" \
-d '{
"events": [
{
"type": "user.message",
"content": [{ "type": "text", "text": "Investigate SENTRY-123." }]
}
]
}'
```
恢复事件流：
```
curl -N http://127.0.0.1:3000/v1/sessions/SESSION_ID/events/stream \
-H "Last-Event-ID: 42"
```
## SDK 用法
公共 API 旨在遵循 Claude Managed Agents 的资源结构。当您的 SDK 支持 managed-agent beta 资源时，请使用 `baseURL` 将官方 Anthropic SDK 指向本地 runtime：
```
import Anthropic from '@anthropic-ai/sdk';
const client = new Anthropic({
apiKey: process.env.MANAGED_AGENTS_API_KEY ?? 'local-dev-key',
baseURL: 'http://127.0.0.1:3000',
});
const session = await client.beta.sessions.create({
agent: 'agent_...',
environment_id: 'env_...',
title: 'SDK smoke test',
});
await client.beta.sessions.events.send(session.id, {
events: [
{
type: 'user.message',
content: [{ type: 'text', text: 'Hello' }],
},
],
});
```
对于仅限本地的辅助工具（例如消息流式传输的便捷方法），该包还导出了一个基于相同 HTTP API 的小型 TypeScript wrapper：
```
import { ManagedAgentsClient } from 'managed-agents/sdk';
const client = new ManagedAgentsClient({
baseUrl: 'http://127.0.0.1:3000',
});
const session = await client.sessions.create({
agent: 'agent_...',
environment_id: 'env_...',
title: 'SDK smoke test',
});
for await (const event of client.sessions.chat(session.id, 'Hello')) {
if (event.type === 'agent.message_chunk') {
process.stdout.write(event.delta ?? '');
}
}
```
## 身份验证
本地开发默认是开放的。当存在至少一个 API key 时，身份验证就会开启。您可以从 Console/API 创建托管密钥，或配置静态密钥：
```
export MANAGED_AGENTS_API_KEY=sk-local-example
```
静态密钥也可以在 `managed-agents.config.yaml` 中配置：
```
api_keys:
- ${MANAGED_AGENTS_API_KEY}
```
通过 API 创建托管密钥：
```
curl -X POST http://127.0.0.1:3000/v1/api-keys \
-H "Content-Type: application/json" \
-d '{ "name": "Local Console" }'
```
然后客户端发送：
```
Authorization: Bearer sk-local-example
```
## 文档
- [安装说明](docs/installation.md)
- [使用指南](docs/usage.md)
- [API 参考](docs/api.md)
- [技能](docs/skills.md)
- [架构](docs/spec/architecture.md)
- [技术设计](docs/spec/design.md)
- [贡献指南](CONTRIBUTING.md)
## 项目关键词
`enterprise-ai-agents`, `ai-agent-runtime`, `managed-agents`,
`claude-managed-agents`, `self-hosted-ai`, `local-first`, `mcp`,
`sandboxed-execution`, `agent-memory`, `credential-vaults`, `audit-log`,
`session-replay`, `typescript`, `sqlite`
## 开发
```
npm ci
npm run typecheck
npm test
npm run build
```
在开发期间运行 runtime 和 Dashboard：
```
npm run dev
npm run dev:console
```
Dashboard 的 `Settings > Logs` 页面可以重启由 CLI 管理的服务器，并显示当前的进程日志缓冲区。Runtime 配置组织在 `Settings > Models`、`Settings > Loop engine`、`Settings > Storage`、`Settings > Memory` 和 `Settings > Sandbox` 下。每个页面都会编辑同一个版本化的 Settings V2 文档，支持 Form 和 JSON 模式，并且可以在保存之前验证或测试本地功能。只有在更改后的候选配置成功通过验证后，才会启用保存功能；如果需要重启，则保存的设置将在重启后成为有效的 runtime 配置。相同的日志控制也可通过 `POST /v1/x/restart` 和 `GET /v1/x/logs` 使用。
## 发布检查
在发布版本之前：
```
npm ci
npm run typecheck
npm test
npm run build
```
对示例项目进行冒烟测试：
```
cd examples/basic
npx managed-agents start --config managed-agents.config.yaml --agents-dir agents --skills-dir skills
```
## 许可证
[Apache-2.0](LICENSE)
标签：AI智能体, DLL 劫持, MCP, MITM代理, 企业级, 大语言模型, 本地部署, 自动化攻击, 请求拦截, 运行时