平台、MCP 与本地服务¶
平台提供记忆、知识与 CLI 能力。默认的 bailian 平台封装百炼 CLI 与
MCP 服务;local 将一切保存在磁盘上。AgenticX 也可以向其他 MCP
客户端暴露自身工具(agenticx mcp-server),并提供基于 token 认证的
localhost HTTP API(agenticx serve)。
安装与使用参见安全、平台与 MCP。
平台协议¶
MemoryProvider
¶
Bases: Protocol
add
async
¶
add(
messages: list[dict[str, str]],
custom_content: str = "",
metadata: dict | None = None,
) -> list[MemoryNode]
Source code in src/dashscope_agenticx/platforms/base.py
104 105 106 107 108 109 110 | |
search
async
¶
search(
query: str | list[dict[str, str]],
top_k: int = 5,
min_score: float = 0.3,
) -> list[MemoryNode]
Source code in src/dashscope_agenticx/platforms/base.py
112 113 114 115 116 117 118 | |
list
async
¶
list(
page_num: int = 1, page_size: int = 10
) -> list[MemoryNode]
Source code in src/dashscope_agenticx/platforms/base.py
120 121 122 123 124 125 | |
delete
async
¶
delete(node_id: str) -> bool
Source code in src/dashscope_agenticx/platforms/base.py
127 128 | |
update
async
¶
update(node_id: str, content: str) -> bool
Source code in src/dashscope_agenticx/platforms/base.py
130 131 | |
MemoryNode
dataclass
¶
MemoryNode(
id: str,
content: str,
created_at: str = "",
updated_at: str = "",
score: float = 0.0,
metadata: dict = dict(),
)
MemoryLibrary
dataclass
¶
MemoryLibrary(memory_id: str, description: str = '')
SearchResult
dataclass
¶
SearchResult(
title: str,
content: str,
link: str,
media: str = "",
publish_date: str = "",
)
KBProvider
¶
Bases: Protocol
list_indices
¶
list_indices(
page_number: int = 1, page_size: int = 20
) -> list[IndexInfo]
Source code in src/dashscope_agenticx/platforms/base.py
135 136 137 138 139 140 | |
retrieve
¶
retrieve(
index_id: str,
query: str,
top_k: int = 5,
min_score: float = 0.3,
) -> list[RetrieveNode]
Source code in src/dashscope_agenticx/platforms/base.py
142 143 144 145 146 147 148 149 | |
create_index
¶
create_index(
name: str,
category_ids: list[str] | None = None,
document_ids: list[str] | None = None,
chunk_size: int = 500,
overlap_size: int = 100,
) -> str
Source code in src/dashscope_agenticx/platforms/base.py
151 152 153 154 155 156 157 158 159 | |
delete_index
¶
delete_index(index_id: str) -> bool
Source code in src/dashscope_agenticx/platforms/base.py
161 162 | |
submit_index_job
¶
submit_index_job(index_id: str) -> str
Source code in src/dashscope_agenticx/platforms/base.py
164 165 | |
get_index_job_status
¶
get_index_job_status(index_id: str, job_id: str) -> dict
Source code in src/dashscope_agenticx/platforms/base.py
167 168 | |
add_documents_to_index
¶
add_documents_to_index(
index_id: str,
category_ids: list[str] | None = None,
document_ids: list[str] | None = None,
) -> str
Source code in src/dashscope_agenticx/platforms/base.py
170 171 172 173 174 175 176 | |
list_index_documents
¶
list_index_documents(
index_id: str, page_number: int = 1, page_size: int = 20
) -> list[IndexDocument]
Source code in src/dashscope_agenticx/platforms/base.py
178 179 180 181 182 183 184 | |
delete_index_documents
¶
delete_index_documents(
index_id: str, document_ids: list[str]
) -> bool
Source code in src/dashscope_agenticx/platforms/base.py
186 187 188 189 190 191 | |
DataProvider
¶
Bases: Protocol
upload_file
¶
upload_file(
file_path: str, category_id: str = "default"
) -> FileInfo
Source code in src/dashscope_agenticx/platforms/base.py
195 196 197 198 199 200 | |
list_files
¶
list_files(
category_id: str = "default", max_results: int = 20
) -> list[FileInfo]
Source code in src/dashscope_agenticx/platforms/base.py
202 203 204 205 206 207 | |
delete_file
¶
delete_file(
file_id: str, category_id: str = "default"
) -> bool
Source code in src/dashscope_agenticx/platforms/base.py
209 210 211 212 213 214 | |
list_categories
¶
list_categories(
category_type: str = "UNSTRUCTURED",
) -> list[Category]
Source code in src/dashscope_agenticx/platforms/base.py
216 217 218 219 220 | |
add_category
¶
add_category(
name: str, category_type: str = "UNSTRUCTURED"
) -> Category
Source code in src/dashscope_agenticx/platforms/base.py
222 223 224 225 226 227 | |
PromptProvider
¶
Bases: Protocol
list
¶
list(
name: str | None = None,
type: str | None = None,
max_results: int = 20,
) -> list[PromptTemplate]
Source code in src/dashscope_agenticx/platforms/base.py
231 232 233 234 235 236 237 | |
get
¶
get(template_id: str) -> PromptTemplate
Source code in src/dashscope_agenticx/platforms/base.py
239 240 | |
create
¶
create(name: str, content: str) -> PromptTemplate
Source code in src/dashscope_agenticx/platforms/base.py
242 243 | |
update
¶
update(
template_id: str,
name: str | None = None,
content: str | None = None,
) -> bool
Source code in src/dashscope_agenticx/platforms/base.py
245 246 247 248 249 250 251 | |
delete
¶
delete(template_id: str) -> bool
Source code in src/dashscope_agenticx/platforms/base.py
253 254 | |
render
¶
render(template_id: str, variables: dict[str, str]) -> str
Source code in src/dashscope_agenticx/platforms/base.py
256 257 | |
工厂函数¶
get_memory_provider
¶
get_memory_provider(config) -> MemoryProvider | None
Always use local file-based memory storage.
Source code in src/dashscope_agenticx/platforms/__init__.py
49 50 51 52 53 54 55 56 57 58 59 60 61 | |
get_cli_provider
¶
get_cli_provider(config)
Return a BailianCLIClient when the bl binary is on PATH, else None.
bl handles its own auth state (bl auth login or env), but we forward
config.tongyi_api_key as the --api-key fallback so a one-config setup just
works.
Source code in src/dashscope_agenticx/platforms/__init__.py
64 65 66 67 68 69 70 71 72 73 74 | |
百炼(Bailian)¶
BailianCLIClient
¶
BailianCLIClient(
binary: str = "bl",
api_key: str = "",
region: str = "",
base_url: str = "",
timeout: int = 180,
)
Subprocess wrapper around the bl binary.
Source code in src/dashscope_agenticx/platforms/bailian/cli.py
56 57 58 59 60 61 62 63 64 65 66 67 68 | |
available
¶
available() -> bool
Source code in src/dashscope_agenticx/platforms/bailian/cli.py
72 73 | |
export_schemas_sync
¶
export_schemas_sync() -> list[dict]
Synchronous variant — used at startup tool-registration time when we're already inside an event loop and can't spin up another.
Source code in src/dashscope_agenticx/platforms/bailian/cli.py
75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 | |
run
async
¶
run(
args: list[str],
stdin: str = "",
inject_globals: bool = True,
) -> CLIResult
Run bl <args> and capture stdout/stderr.
Source code in src/dashscope_agenticx/platforms/bailian/cli.py
101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 | |
invoke
async
¶
invoke(command_path: list[str], params: dict) -> str
Translate {kw: val} into --kebab-case <value> flags and
call bl.
- bool=True → --flag
- bool=False → omitted
- list → repeat --flag
- str/number → --flag
- None → omitted
Source code in src/dashscope_agenticx/platforms/bailian/cli.py
150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 | |
CLIResult
dataclass
¶
CLIResult(code: int, stdout: str, stderr: str)
BailianCLIError
¶
Bases: Exception
MCPClient
¶
MCPClient(service: str, api_key: str, url: str = '')
MCP Client using SSE transport.
Flow: 1. GET /sse — opens SSE stream, server sends 'endpoint' event with POST URL 2. POST to that endpoint — send JSON-RPC requests 3. Server responds via SSE 'message' events on the GET stream
Source code in src/dashscope_agenticx/platforms/bailian/mcp.py
31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 | |
initialize
async
¶
initialize() -> bool
Source code in src/dashscope_agenticx/platforms/bailian/mcp.py
207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 | |
list_tools
async
¶
list_tools() -> list[dict]
Source code in src/dashscope_agenticx/platforms/bailian/mcp.py
255 256 257 258 259 | |
list_prompts
async
¶
list_prompts() -> list[dict]
Discover available prompts/skills. Returns [] if not supported.
Source code in src/dashscope_agenticx/platforms/bailian/mcp.py
261 262 263 264 265 266 267 268 269 270 271 | |
call_tool
async
¶
call_tool(tool_name: str, arguments: dict) -> str
Source code in src/dashscope_agenticx/platforms/bailian/mcp.py
273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 | |
close
async
¶
close()
Source code in src/dashscope_agenticx/platforms/bailian/mcp.py
296 297 298 299 300 301 302 303 304 305 306 | |
MCPError
¶
Bases: Exception
MCP 服务端模式¶
通过 MCP stdio 暴露 AgenticX 工具(agenticx mcp-server):
tools_to_mcp_schema
¶
tools_to_mcp_schema() -> list[dict[str, Any]]
Convert registered tools to MCP tool schema format.
Each tool becomes
{ "name": "...", "description": "...", "inputSchema": { ... JSON schema ... } }
Source code in src/dashscope_agenticx/mcp_server.py
26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 | |
handle_mcp_request
async
¶
handle_mcp_request(
request: dict[str, Any], executor: Any = None
) -> dict[str, Any]
Handle a single MCP JSON-RPC request.
Supports
tools/list: return all registered toolstools/call: execute a tool by name
Returns a JSON-RPC response dict.
Source code in src/dashscope_agenticx/mcp_server.py
48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 | |
run_stdio_server
async
¶
run_stdio_server(executor: Any = None) -> None
Run the MCP server on stdio (JSON-RPC over stdin/stdout).
Reads line-delimited JSON requests from stdin, writes responses to stdout.
Source code in src/dashscope_agenticx/mcp_server.py
124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 | |
main
¶
main() -> None
Entry point for agenticx mcp-server: run the MCP stdio server.
Registers the builtin tools (same set the CLI imports at startup) and serves JSON-RPC over stdin/stdout. There is no interactive user at the console in this mode, so the executor auto-approves tool calls.
Source code in src/dashscope_agenticx/mcp_server.py
156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 | |
StdioMCPClient
¶
StdioMCPClient(
command: str,
args: list[str] | None = None,
timeout: float = 30.0,
)
MCP client that drives a local server over stdio.
The server process is spawned with command + args; requests
and responses are single-line JSON documents. A background reader
matches response ids to pending request futures; server notifications
(messages without an id) are ignored.
Source code in src/dashscope_agenticx/mcp_stdio.py
38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 | |
initialize
async
¶
initialize() -> bool
Spawn the server, run the MCP initialize handshake.
Source code in src/dashscope_agenticx/mcp_stdio.py
61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 | |
close
async
¶
close() -> None
Stop the reader, close stdin, terminate the subprocess.
Source code in src/dashscope_agenticx/mcp_stdio.py
102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 | |
list_tools
async
¶
list_tools() -> list[dict]
Source code in src/dashscope_agenticx/mcp_stdio.py
142 143 144 145 146 147 148 149 150 | |
list_prompts
async
¶
list_prompts() -> list[dict]
Discover prompts/skills; returns [] when unsupported.
Source code in src/dashscope_agenticx/mcp_stdio.py
152 153 154 155 156 157 158 159 160 161 162 | |
call_tool
async
¶
call_tool(tool_name: str, arguments: dict) -> str
Source code in src/dashscope_agenticx/mcp_stdio.py
164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 | |
本地 HTTP API¶
agenticx serve 仅绑定 localhost 并要求 bearer token;非 localhost
的绑定地址会被拒绝。
LocalAPI
¶
LocalAPI(
token: str,
*,
session_manager: SessionManager | None = None,
run_handler: RunHandler | None = None,
trace_dir: Path | None = None
)
Source code in src/dashscope_agenticx/server.py
72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 | |
authorized
¶
authorized(header: str) -> bool
Source code in src/dashscope_agenticx/server.py
89 90 91 92 93 94 | |
get
¶
get(path: str) -> tuple[int, dict[str, Any]]
Source code in src/dashscope_agenticx/server.py
96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 | |
post
¶
post(
path: str, payload: dict[str, Any]
) -> tuple[int, dict[str, Any]]
Source code in src/dashscope_agenticx/server.py
132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 | |
create_server
¶
create_server(
host: str = "127.0.0.1",
port: int = 8765,
*,
token: str,
api: LocalAPI | None = None
) -> ThreadingHTTPServer
Source code in src/dashscope_agenticx/server.py
153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 | |
serve
¶
serve(
host: str = "127.0.0.1",
port: int = 8765,
token: str = "",
) -> None
Source code in src/dashscope_agenticx/server.py
216 217 218 219 220 221 222 223 224 225 226 227 228 | |
generate_server_token
¶
generate_server_token() -> str
Source code in src/dashscope_agenticx/server.py
25 26 | |