Python 参考
导入入口
from axonx.app.core.application import Application
from axonx.app.config.loader import ConfigLoader
from axonx.app.steps.base import BaseStep
from axonx.app.components.registry import provider
from axonx.client.http import HttpClient, run_remote_job, stream_remote_job
from axonx.client.mcp import McpClient
from axonx.client.base import RemoteServiceError, RemoteConnectionError
from axonx.client.models import JobResponse, StagedFile
from axonx.client.events import ResultEvent使用 Python 3.12+。根包导出版本元数据,能力命名空间不集中导出所有实现。
嵌入 Application
import asyncio
from axonx.app.core.application import Application
async def main():
async with Application(log_to_console=False, log_to_file=False) as app:
print(app.is_started, app.workspace_path)
asyncio.run(main())此最小图不需要产品适配器,不启动 HTTP 监听。加载已配置 Job 时,用 ConfigLoader().resolve(config="default", log_config=False) 解析并传入结果。使用相关能力时由宿主注入 TaskCatalog、更新后端或定时启动器。Task 客户端本身不需要 Application,Application 不自动加载 .env。
Application 方法
start()、close() 按依赖管理生命周期。run_job(name, arguments=None, *, target=None) 返回 JobResponse;stream_job(...) 返回异步迭代器,不直接 await。两者要求应用已启动,转发目标必须列入 ApplicationConfig.targets。
HTTP 客户端
import asyncio
import os
from axonx.client.http import HttpClient
async def main():
async with HttpClient(
target="127.0.0.1:1024",
token=os.environ["AXONX_SERVICE_TOKEN"],
timeout=600.0,
) as client:
response = await client.run_job("cli", {"argv": [
"exec", "--task", "demo", "--task-name", "python-api",
"--x", "1", "--y", "2",
]})
if not response.success:
raise RuntimeError(str(response.answer))
assert response.answer["exit_code"] == 0
status = await client.run_job("status", {
"task_id": "base#demo#python-api", "detail": "full",
})
print(status.model_dump(mode="json"))
asyncio.run(main())方法为 run_job、stream_job、list_jobs、health、upload(Path, filename=None, directory=None)、upload_archive(Path)、discard_file(path)。构造参数为 target、timeout、token 和可选 HTTP transport。用 async with 管理连接,凭据需显式传入,库客户端不会自动读取 CLI token 环境变量。远程 answer 是解码数据,本地 answer 可能含模型对象,需要时用 model_dump(mode="json") 统一。
消费事件
from contextlib import aclosing
from axonx.client.events import ResultEvent
# Inside an async function with a started HttpClient named client:
async with aclosing(client.stream_job("stream_task", {"task_id": task_id})) as events:
async for event in events:
if isinstance(event, ResultEvent):
print(event.response().model_dump(mode="json"))
elif event.kind == "log":
print(event.content, end="")文件上传
upload 返回含 path、size、绝对 location 的 StagedFile。目标机插件安装使用 location,清理和同步使用 path。确认命令结束后在 finally 中调用 discard_file;命令结果不明时保留上传文件。完整远程安装示例见插件管理。
MCP 客户端
McpClient 使用服务基础地址,通过 /mcp 提供 run_job、list_jobs、health,返回普通 Job 响应。实时事件使用 HTTP SSE,上传使用 HTTP。
一次性远程函数
await run_remote_job("version", {}, target=..., token=...) 打开并关闭一个 HTTP 客户端。stream_remote_job 是异步生成器,提前停止消费时用 aclosing 关闭。辅助函数不做 CLI 值转换。
错误与清理
RemoteConnectionError 表示无法连接或连接超时,RemoteServiceError 表示协议/HTTP 失败并含可选 status_code。另行检查 JobResponse.success。命令流中断可能无法判断是否已接受执行,重试前检查 Task 启动时间。取消会关闭客户端连接。默认 cli Job 继续执行;服务关闭仍会终止其手动命令进程组。
源码:Application、HTTP、MCP。