feat: add multi-tenant IM agent gateway

.github/workflows/multi-tenant-im-agent.yml

@@ -0,0 +1,49 @@
+name: Multi-Tenant IM Agent
+
+on:
+  push:
+    branches:
+      - "feature/**"
+    paths:
+      - "examples/multi_tenant_im_agent/**"
+      - ".github/workflows/multi-tenant-im-agent.yml"
+      - "pyproject.toml"
+  pull_request:
+    paths:
+      - "examples/multi_tenant_im_agent/**"
+      - ".github/workflows/multi-tenant-im-agent.yml"
+      - "pyproject.toml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install project and verification dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[multi-tenant-im]" pytest pytest-asyncio ruff fastapi httpx
+
+      - name: Lint and format check
+        run: |
+          ruff check examples/multi_tenant_im_agent
+          ruff format --check examples/multi_tenant_im_agent
+
+      - name: Unit and migration contract tests
+        run: python -m pytest examples/multi_tenant_im_agent/tests -q
+
+      - name: Black-box HTTP acceptance
+        run: python examples/multi_tenant_im_agent/scripts/judge_demo.py

.gitignore

@@ -22,6 +22,9 @@ coverage.xml
 test-ngtest-ut-trpc-agent-py.xml
 .pytest_cache
 
+# Local credentials for the multi-tenant IM Agent integration smoke test.
+examples/multi_tenant_im_agent/.env.private
+
 node_modules
 package-lock.json
 pyrightconfig.json

README.md

@@ -519,6 +519,7 @@ Recommended first:
 - [examples/a2a](./examples/a2a/README.md) / [examples/a2a_with_cancel](./examples/a2a_with_cancel/README.md) - A2A service and cancellation (a2a-sdk 0.3)
 - [examples/a2a_v1](./examples/a2a_v1/README.md) / [examples/a2a_v1_with_cancel](./examples/a2a_v1_with_cancel/README.md) - A2A service and cancellation (a2a-sdk 1.x)
 - [examples/agui](./examples/agui/README.md) / [examples/agui_with_cancel](./examples/agui_with_cancel/README.md) - AG-UI service and cancellation
+- [examples/multi_tenant_im_agent](./examples/multi_tenant_im_agent/README.md) - Multi-tenant Telegram/WeCom gateway with a real Runner, shared sessions, idempotency, audit, recovery, and one-command acceptance
 
 Related docs: [a2a.md](./docs/mkdocs/en/a2a.md) / [agui.md](./docs/mkdocs/en/agui.md) / [cancel.md](./docs/mkdocs/en/cancel.md)
 

README.zh_CN.md

@@ -520,6 +520,7 @@ skill_tool_set = SkillToolSet(repository=repository, run_tool_kwargs=tool_kwargs
 - [examples/a2a](./examples/a2a/README.md) / [examples/a2a_with_cancel](./examples/a2a_with_cancel/README.md) - A2A 服务与取消（a2a-sdk 0.3）
 - [examples/a2a_v1](./examples/a2a_v1/README.md) / [examples/a2a_v1_with_cancel](./examples/a2a_v1_with_cancel/README.md) - A2A 服务与取消（a2a-sdk 1.x）
 - [examples/agui](./examples/agui/README.md) / [examples/agui_with_cancel](./examples/agui_with_cancel/README.md) - AG-UI 服务与取消
+- [examples/multi_tenant_im_agent](./examples/multi_tenant_im_agent/README.zh_CN.md) - 多租户 Telegram/企业微信网关，包含真实 Runner、共享会话、幂等、审计、故障恢复与一键验收
 
 相关文档：[a2a.md](./docs/mkdocs/zh/a2a.md) / [agui.md](./docs/mkdocs/zh/agui.md) / [cancel.md](./docs/mkdocs/zh/cancel.md)
 

examples/multi_tenant_im_agent/.env.example

@@ -0,0 +1,17 @@
+# Never commit real values. Production should inject these from KMS/Vault/K8s Secrets.
+TENANT_CONFIG_FILE=/app/config/tenants.json
+CONTROL_PLANE_DB_URL=mysql+pymysql://agent:replace-me@mysql:3306/trpc_agent
+OFFLINE_ECHO_MODE=false
+AUTO_CREATE_SCHEMA=false
+REDIS_URL=redis://redis:6379/0
+TENANT_NAMESPACE_SECRET=replace-with-at-least-32-random-characters
+ADMIN_API_TOKEN=replace-with-a-random-admin-token
+ACME_MODEL_API_KEY=replace-me
+# Used only by scripts/real_model_smoke.py.
+REAL_MODEL_NAME=gpt-4o-mini
+REAL_MODEL_BASE_URL=https://api.openai.com/v1
+ACME_TELEGRAM_WEBHOOK_SECRET=replace-me
+ACME_TELEGRAM_BOT_TOKEN=replace-me
+ACME_WECOM_CALLBACK_TOKEN=replace-me
+ACME_WECOM_OUTBOUND_WEBHOOK=https://example.invalid/replace-me
+OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318

examples/multi_tenant_im_agent/.env.local.example

@@ -0,0 +1,9 @@
+# Local/offline demonstration values only. Never reuse them in production.
+OFFLINE_ECHO_MODE=true
+AUTO_CREATE_SCHEMA=true
+TENANT_CONFIG_FILE=examples/multi_tenant_im_agent/config.local.json
+CONTROL_PLANE_DB_URL=sqlite:///multi_tenant_im.local.db
+TENANT_NAMESPACE_SECRET=local-demo-namespace-secret-32-chars
+ADMIN_API_TOKEN=local-demo-admin-token
+ACME_TELEGRAM_WEBHOOK_SECRET=local-telegram-secret
+ACME_WECOM_CALLBACK_TOKEN=local-wecom-token