JiuwenSwarm is an intelligent AI Agent built on openJiuwen. It extends the powerful capabilities of large language models directly to your fingertips through various communication apps you use daily.
Python
#!/usr/bin/env python
"""自定义 Tool 示例:通过环境变量非侵入式注册(AGENT_EXTRA_TOOLS,仅企业版)。
使用方式:
export AGENT_EXTRA_TOOLS=examples.custom_extension_tool
# 多模块分号分隔:examples.custom_extension_tool;my.pkg.other_tools
# 然后启动 AgentServer;env 变更需重启进程生效
部署契约:
1. 本模块及其第三方依赖须预装在 AgentServer 运行时 Python 环境
(与 AGENT_EXTRA_RAILS 扩展同一部署链路);
2. register_tools() 返回模块级 @tool 单例——工具实例进程级共享,
不要在工厂里新建实例;
3. per-session 数据只经 contextvars 或工具参数传入,禁止模块级
可变状态缓存会话数据(并发会话下会串数据)。
本模块演示两个工具:
- query_system_api:渠道系统调用示例,演示安全契约——模型只能给
system_code/api_code,下游地址由模块内白名单解析;禁止把裸 url
暴露为模型可填参数(提示词注入可驱动服务端任意内网访问)。
- get_current_user:用户信息示例,演示契约 3——当前用户经
contextvars 注入读取(通常由客户自己的 AGENT_EXTRA_RAILS rail 在
before_tool_call 时 set),工具侧只读,不落任何全局可变状态。
"""
from __future__ import annotations
import asyncio
import contextvars
import json
import logging
from openjiuwen.core.foundation.tool import Tool, tool
logger = logging.getLogger(__name__)
# ---------------------------------------------------------------------------
# 契约 3:per-session 上下文只走 contextvar。注入点在调用链路(示例:客户
# 自定义 rail 的 before_tool_call 中 ``CURRENT_USER.set(run_context...)``),
# 工具侧只读。这里用 default="" 兜底,未注入时显式报错而不是串到别的会话。
# ---------------------------------------------------------------------------
CURRENT_USER: contextvars.ContextVar[str] = contextvars.ContextVar(
"current_user", default=""
)
# 模块级【不可变】白名单:允许的 (system_code, api_code) -> 下游地址。
# 这是常量注册表,不是会话状态;真实集成里换成签名客户端配置。
SYSTEM_API_REGISTRY: dict[tuple[str, str], str] = {
("core", "query_account_balance"): "https://core.example.internal/balance",
("core", "query_account_detail"): "https://core.example.internal/detail",
("channel", "submit_transaction"): "https://channel.example.internal/submit",
}
# 超时钳制:模型可填 timeout 参数,但不能给离谱值拖垮会话
_TIMEOUT_CLAMP_S = (1, 60)
@tool(
name="query_system_api",
description=(
"通过渠道系统调用第三方系统 API。传入 system_code 与 api_code,"
"返回下游系统响应 JSON 文本。仅支持白名单内的系统与接口。"
),
)
async def query_system_api(
system_code: str,
api_code: str,
payload: str = "{}",
timeout: int = 10,
) -> str:
"""调用白名单内的第三方系统接口。
Args:
system_code: 目标系统编码,如 core / channel。
api_code: 接口编码,如 query_account_balance。
payload: 业务请求报文(JSON 字符串)。
timeout: 超时秒数,范围 1-60,超范围自动钳制。
"""
url = SYSTEM_API_REGISTRY.get((system_code, api_code))
if url is None:
# 白名单外直接拒绝,不回显任何路由能力
return json.dumps(
{"error": f"unregistered system/api: {system_code}/{api_code}"},
ensure_ascii=False,
)
clamped = max(_TIMEOUT_CLAMP_S[0], min(_TIMEOUT_CLAMP_S[1], timeout))
# 真实集成:在此用 httpx/aiohttp + 签名客户端请求 url;
# 样例用 sleep 模拟网络往返,保持零第三方依赖、可直接挂载。
await asyncio.sleep(0.05)
logger.info(
"[custom_extension_tool] query_system_api user=%s system=%s api=%s timeout=%ss",
CURRENT_USER.get() or "anonymous",
system_code,
api_code,
clamped,
)
return json.dumps(
{
"system": system_code,
"api": api_code,
"endpoint": url,
"echo": payload,
},
ensure_ascii=False,
)
@tool(
name="get_current_user",
description="查询当前会话的用户信息。无需参数。",
)
async def get_current_user() -> str:
"""返回当前会话上下文中的用户信息(contextvars 注入,工具侧只读)。"""
user = CURRENT_USER.get()
if not user:
return json.dumps(
{"error": "当前调用链路未注入用户上下文"}, ensure_ascii=False
)
return json.dumps({"user_id": user}, ensure_ascii=False)
def register_tools() -> list[Tool]:
"""AGENT_EXTRA_TOOLS 注册入口:返回要挂载的工具实例列表。
必须返回模块级 @tool 单例(上面的函数对象本身),不要在这里
构造新实例——实例被所有并发会话共享。
"""
return [query_system_api, get_current_user]