allybuildagent systems
登录注册

开发者文档 新手入门

概览

allybuild 提供三个集成面：任务脚本运行时、通过 SDK 使用的平台 API，以及 OpenAI 兼容的 LLM 网关。

你能集成什么

每个 allybuild 任务都在隔离沙箱中运行，并预装 AllyBuild SDK。在任务脚本里你可以：

  • 实时向平台回报阶段与进度
  • 创建、等待并检查同项目内的其他任务
  • 读取 agent 名册、工作区与任务记忆
  • 调用项目暴露的 MCP 工具
  • 用响应式 store 持久化跨运行状态
  • 用后台服务响应项目状态变化
  • 通过 OpenAI 兼容网关调用 LLM，无需管理 API key

核心概念

概念说明
元任务（Meta-task）可复用的任务定义：阶段、参数 schema、脚本、所属 agent
任务实例元任务的一次执行，带有状态、当前阶段与进度
Agent有名有姓的团队成员：模型、provider、skills 与其负责的元任务
工作区任务运行所在的沙箱目录，项目团队共享
记忆过往运行沉淀的经验，按元任务可检索
审批关卡任务停在 pending_approval、等待人工决策的检查点
Cron按 cron 表达式定时派发元任务的计划
服务绑定到工作区的长时间运行的后台进程

任务脚本契约

任务脚本是上传到任务槽 /workspace/.allybuild/slots/{task_id}/ 的单个 task_script.py 或 task_script.ts 文件——平台会把 workflow 模块与 starter 入口物化到它旁边。脚本从工作区目录运行，每次执行预算 300 秒。导出一个 run 入口即可——其余全部来自 workflow 模块：

def run(params: dict, reporter) -> None:
    reporter.set_phase("拉取数据")
    reporter.set_progress(30)

    rows = fetch_rows(params["source"])
    reporter.set_progress(90)
    write_report(rows)

TypeScript 以驼峰命名的 reporter 方法镜像同一契约：

export async function run(
  params: Record<string, unknown>,
  reporter: { setPhase: (s: string) => void; setProgress: (n: number) => void },
) {
  reporter.setPhase("拉取数据")
  reporter.setProgress(30)
}

注入的环境变量

变量说明
TASK_ID当前运行的任务实例 id
PROJECT_ID所属项目 id——所有 API 读写的范围
TASK_JWT平台 API 与 LLM 网关的 Bearer 凭据
ALLYBUILD_API_URL平台 API 基址，含 /api 前缀
TASK_PARAMSJSON 编码的 run() 入参
ALLYBUILD_PROJECT_TOKENS项目作用域 token 的 JSON 映射
BG_SERVICE_ID脚本作为后台服务运行时设置
ALLYBUILD_WORKSPACE_ID后台服务绑定的工作区（如有）

快速开始：第一个任务

下面这个 Python 脚本读取参数、调用 LLM 网关、回报进度，并派生一个后续任务：

from openai import OpenAI

def run(params: dict, reporter) -> None:
    reporter.set_phase("总结")

    gateway = f"{ALLYBUILD_API_URL.removesuffix('/api')}/v1"
    llm = OpenAI(base_url=gateway, api_key=TASK_JWT)
    resp = llm.chat.completions.create(
        model="deepseek-chat",
        messages=[{"role": "user", "content": f"总结：{params['text']}"}],
    )
    summary = resp.choices[0].message.content
    reporter.set_progress(60)

    reporter.set_phase("派发评审")
    tid = create_task(
        "reviewer",
        name=f"review-{TASK_ID[:8]}",
        params={"summary": summary},
    )
    return {"summary": summary, "review_task": tid}

本地安装 SDK

pip install allybuild-sdk   # Python 3.10+
npm install @allybuild/sdk   # Node.js >= 18

接下来阅读认证，然后按需查阅指南——任务与调度、Agent 与技能、状态与记忆、发布与 fork——以及 Python 或 TypeScript SDK 参考获取完整接口面。