matrixlink (Agent Matrix)

⚡️ MatrixLink套件

*生产工具包 MatrixHub --在任何云上发现、选择和运行MCP服务器（编排器）和A2A代理。*

需要 Python 3.11+.图书馆出版为 matrixlink 在PyPI上。BFF/UI在上运行 :8080.

______________________________________________________________________

MatrixLink Suite为您提供了一个生产就绪的运行基础 MCP网关+编排器（MCP服务器）+A2A代理 在任何现代平台上（IBM代码引擎、Google Cloud Run、AWS App Runner、Azure容器应用程序、Knative/K8s、本地）。它包括：

• libs/matrixlink/ --用于MCP发现、A2A消息传递和编排器调用的PyPI就绪客户端
• apps/bff/ --前门（FastAPI）露出干净的 /api/* 带有管理员和MCP代理的表面
• ui/matrixhub-admin/ --MCP服务器和代理的最小React管理员（只读）
• infra/ce/ --用于应用程序和机密的IBM代码引擎脚本
• Makefile --开发和运营目标(make help)

所有服务都绑定到端口 8080.东西方呼唤使用 承载服务令牌 （可选mTLS）。

默认提供程序= local。本地运行BFF+UI不需要外部服务。

______________________________________________________________________

什么是MatrixHub和MatrixLink？

MatrixHub 是一个 *互联网规模中心* 搜索引擎（想想 用于AI代理和MCP服务器的PyPI).您可以通过以下方式使用它来发现高质量的代理/编排者 能力 （技能、流程）， 信任 （出版商、SBOM/认证），以及 健身 （成功率、延迟、区域）。使用权限将所选条目导入组织的私有目录 可见性 和 政策.

MatrixLink 是运行时连接器：一个小型客户端库加上一个可选的BFF 发现和调用便携 穿过云层。它允许您的代码：

• 通过以下方式发现代理商 技能 通过你的 MCP网关
• 使用简单的呼叫代理 A2A 合同(/message/send，可选SSE）
• 调用编排器(/invoke/)带有租赁标头和承载身份验证
• 通过环境变量自动解析服务端点（每个提供者无需进行代码编辑）

一起: *在全球范围内发现，在本地运行*。您从MatrixHub中选择构建块；MatrixLink将它们安全且可重复地连接到您的环境中。

______________________________________________________________________

建筑

flowchart TD
  subgraph EXT["External"]
    UI["Clients / Apps / Chat UI"]
  end

  subgraph EDGE["API Gateway / Front Door (public)"]
    APIGW["https://your-host/api/*"]
  end

  subgraph CTRL["Control Plane"]
    MCP["MCP Gateway (registry, discovery, health)"]
  end

  subgraph RUNTIME["Serverless / Containers (:8080)"]
    BFF["BFF (Front Door + MCP proxy)"]
    ORCH["Orchestrator(s) (MCP Servers)"]
    A1["A2A Agents (skills)"]
    A2["A2A Agents (skills)"]
    AX["… more Agents"]
  end

  UI --> APIGW
  APIGW -- "/api/health|/api/ready|/api/mcp/*|/api/admin/*" --> BFF
  APIGW -- "/api/chat or /api/flows/" --> ORCH

  BFF --> MCP
  ORCH -.->|discover by skill| MCP
  ORCH --> A1
  ORCH --> A2
  ORCH --> AX

公共API（边缘）：

______________________________________________________________________

存储库布局

matrixlink-suite/
├─ libs/
│  └─ matrixlink/               # PyPI client
│     ├─ pyproject.toml
│     └─ src/matrixlink/
│        ├─ __init__.py
│        ├─ config.py
│        ├─ providers.py
│        ├─ discovery.py
│        ├─ a2a.py
│        ├─ orchestrator.py
│        ├─ sse.py
│        └─ errors.py
├─ apps/
│  └─ bff/
│     ├─ Dockerfile
│     ├─ requirements.txt
│     └─ app/
│        ├─ main.py
│        ├─ auth.py
│        ├─ db.py
│        ├─ models.py
│        ├─ observability.py
│        └─ clients/
│           ├─ mcp.py
│           └─ agents.py
├─ ui/
│  └─ matrixhub-admin/
│     ├─ Dockerfile
│     ├─ package.json
│     └─ src/...
├─ infra/
│  ├─ ce/                       # IBM Code Engine scripts
│  └─ secrets/
├─ docs/                        # MkDocs site (see below)
├─ mkdocs.yml                   # MkDocs config
├─ .env.example
├─ Makefile
├─ LICENSE
└─ README.md

______________________________________________________________________

需求

• Python 3.10+
• 节点18+（UI）
• Docker（用于容器构建）
• 可选：用于代码引擎部署的IBM Cloud CLI

______________________________________________________________________

快速入门（本地）

1） 运行BFF（前门）

make install
# optional: point BFF to a local MCP Gateway (if you run one)
export MCP_BASE_URL="http://localhost:4444"
make run-bff
# → http://localhost:8080/api/health

2） 运行管理UI

make dev-ui
# → http://localhost:3000

对于本地测试，设置 export ADMIN_BEARER=changeme-admin-bearer-token 并在UI设置中使用相同的设置。

______________________________________________________________________

我什么时候需要MCP网关？

MatrixLink的BFF和UI运行良好 没有 MCP用于基本健康/管理。你会想要一个 MCP网关 当你需要：

• 运行时发现 按技能/标签分类的代理/编排者
• 中央登记处 + RBAC 和 可见性 每个团队/租户
• 健康与健身 信号（仅通往健康入口）
• 受控推出 （蓝色/绿色，金丝雀通过标签）

本地开发人员： 您可以在上运行轻量级MCP网关 http://localhost:4444.在云中，点 MCP_BASE_URL 到您的托管MCP实例（或通过解决 DOMAIN_SUFFIX+MCP_SERVICE_NAME).

______________________________________________________________________

环境变量

最好的朋友

• ADMIN_BEARER --守卫令牌 /api/admin/* 和 /api/mcp/*
• MCP_BASE_URL --MCP网关URL（默认为 http://localhost:4444 为了 CLOUD_PROVIDER=local)
• MCP_BEARER_TOKEN --调用MCP网关的服务令牌
• AGENTS_BASE_URL --代理的可选静态基座（扇入式主机）
• AGENTS_API_TOKEN --代理调用的东西方承载者

MatrixLink库

• CLOUD_PROVIDER — local （默认）， ce, gcrun, apprunner, aca, knative
• DOMAIN_SUFFIX --例如。 proj.region.codeengine.appdomain.cloud
• MCP_SERVICE_NAME --默认值 mcp-gateway
• ORCH_SERVICE_NAME --默认值 orchestrator
• AGENTS_DOMAIN_PREFIX --默认值 agents
• MCP_BASE_URL, ORCH_BASE_URL, AGENTS_BASE_URL --显式覆盖
• MCP_BEARER_TOKEN, A2A_SERVICE_TOKEN, TENANT_HEADER, REQUEST_TIMEOUT

______________________________________________________________________

使用MatrixLink（Python）

从repo本地安装：

cd libs/matrixlink
pip install -e .

或者从PyPI（发布后）：

pip install matrixlink

通过技能发现代理（通过MCP网关）

from matrixlink import MCPClient

mcp = MCPClient()  # reads MCP_BASE_URL or DOMAIN_SUFFIX + service name
agents = mcp.discover_agents(skill="report.generate")
print(agents[0]["endpoint"])  # https://agents.../agent-synth

向A2A代理发送数据

from matrixlink import A2AClient

a2a = A2AClient()  # uses A2A_SERVICE_TOKEN if set
endpoint = "https://agents.example.com/agent-synth"  # or from discovery
resp = a2a.send_message(endpoint, {"title": "Weekly Status", "bullets": ["A", "B", "C"]})
print(resp)

调用编排器（MCP服务器）流

from matrixlink import OrchestratorClient

orch = OrchestratorClient("https://orchestrator.example.com")
result = orch.invoke("hr.orchestrate", {"candidates":[{"id":"c1","skills":["py","sql"]}]})
print(result)

______________________________________________________________________

API管理员（BFF）

安全=需要 Authorization: Bearer ${ADMIN_BEARER}.

______________________________________________________________________

码头工人

最好的朋友

docker build -f apps/bff/Dockerfile -t local/bff:dev .
docker run --rm -p 8080:8080 \
  -e CLOUD_PROVIDER=local \
  -e ADMIN_BEARER=changeme-admin-bearer-token \
  -e MCP_BASE_URL=http://host.docker.internal:4444 \
  local/bff:dev

管理用户界面

docker build -f ui/matrixhub-admin/Dockerfile -t local/matrixhub-admin:dev ui/matrixhub-admin
docker run --rm -p 8081:8080 local/matrixhub-admin:dev
# open http://localhost:8081

______________________________________________________________________

在IBM代码引擎上部署（示例）

1. 创建秘密 （先填写令牌）：

./infra/secrets/create-secrets.sh

1. 构建和推送图像:

make docker-build-bff docker-build-ui make docker-push-bff docker-push-ui

1. 创建应用程序:

make ce-create-bff make ce-create-ui

1. API网关路由:

- /api/health|/api/ready|/api/admin/*|/api/mcp/* ->BFF - /api/chat （或 /api/flows/)->编排器（单独的仓库/应用程序）

______________________________________________________________________

其他提供者（环境预设）

谷歌云运行 （建议使用自定义域）

CLOUD_PROVIDER=gcrun
MCP_BASE_URL=https://mcp-gateway.example.com
ORCH_BASE_URL=https://orchestrator.example.com
AGENTS_BASE_URL=https://orchestrator.example.com
MCP_BEARER_TOKEN=...
A2A_SERVICE_TOKEN=...

AWS应用程序运行程序

CLOUD_PROVIDER=apprunner
MCP_BASE_URL=https://
ORCH_BASE_URL=https://
AGENTS_BASE_URL=https://

Azure容器应用

CLOUD_PROVIDER=aca
DOMAIN_SUFFIX=myenv.azurecontainerapps.io
MCP_SERVICE_NAME=mcp-gateway
ORCH_SERVICE_NAME=orchestrator
AGENTS_DOMAIN_PREFIX=agents

Knative/K8s

CLOUD_PROVIDER=knative
DOMAIN_SUFFIX=apps.example.internal
MCP_SERVICE_NAME=mcp-gateway
ORCH_SERVICE_NAME=orchestrator
AGENTS_DOMAIN_PREFIX=agents

本地/Docker作曲+Traefik

CLOUD_PROVIDER=local
MCP_BASE_URL=http://localhost:4444

______________________________________________________________________

安全与运营

• 秘密：将令牌存储在提供商秘密存储中；从未出现在图像中
• 认证：边缘的OIDC/JWT /api/chat; ADMIN_BEARER 用于管理代理；服务熊为东-西
• 可观测性：结构化日志 X-Request-ID / X-Tenant-Id；如果需要，添加OTEL出口商
• 上海证券交易所：确保API网关不缓冲 /stream 回应
• 扩展：BFF和MCP网关 minScale=1；编排器/代理可以扩展到0
• 数据库：BFF使用SQLite进行开发；通过prod-via切换到托管数据库 DATABASE_URL

______________________________________________________________________

制定目标

make help              # list targets
make install           # venv + deps + install local matrixlink into BFF venv
make run-bff           # run BFF at :8080 (local)
make dev-ui            # run Admin UI at :3000 (Vite dev)
make build-ui          # build Admin UI static
make build-lib         # build matrixlink (wheel/sdist)
make docker-build-bff  # build BFF container
make docker-build-ui   # build UI container
make docker-push-bff   # push BFF image
make docker-push-ui    # push UI image
make ce-create-secrets # create CE secrets
make ce-create-bff     # create BFF app on CE
make ce-create-ui      # create UI app on CE

______________________________________________________________________

故障排除

• ModuleNotFoundError: matrixlink 在本地运行BFF时→ run make install.
• 未设置MCP基本URL → set MCP_BASE_URL 或使用 CLOUD_PROVIDER + DOMAIN_SUFFIX + MCP_SERVICE_NAME.
• 跨域资源共享 → set CORS_ALLOW_ORIGINS 在BFF中（例如。， http://localhost:3000).
• 401在管理路线上 → set ADMIN_BEARER 并通过 Authorization: Bearer 从UI。

______________________________________________________________________

许可证

Apache 2.0——请参阅 LICENSE.