JamJet

REST API 参考

JamJet 运行时的完整 HTTP API 参考文档 — 工作流、执行、代理、审计和租户。

REST API 参考

JamJet 运行时默认在 http://localhost:7700 上暴露 REST API。所有请求和响应均使用 JSON 格式。

身份验证

受保护的端点需要 Bearer 令牌:

Authorization: Bearer <token>

令牌通过 CLI 或操作员 API 创建。运行时仅存储哈希值——明文仅在创建时返回一次。

角色

角色读取写入管理
operator是是是
developer是是否
reviewer是否否
viewer是否否

写操作(POST、PUT、DELETE)需要 developer 或 operator 角色。租户管理需要 operator 角色。

健康检查

GET /health

无需身份验证。

{ "status": "ok", "version": "0.1.1" }

工作流

POST /workflows

注册工作流定义(编译后的 IR)。

请求:

{
  "ir": {
    "workflow_id": "research-agent",
    "version": "0.1.0",
    "state_schema": { ... },
    "nodes": { ... },
    "edges": [ ... ]
  }
}

响应 201 Created:

{
  "workflow_id": "research-agent",
  "version": "0.1.0"
}

提示: 大多数用户不会直接调用此端点。jamjet run workflow.yaml 会自动编译并提交 IR。

执行

POST /executions

启动新的工作流执行。

请求:

{
  "workflow_id": "research-agent",
  "workflow_version": "0.1.0",
  "input": {
    "query": "Latest AI agent frameworks?"
  }
}

workflow_version 为可选参数——默认使用最新注册的版本。

响应 201 Created:

{
  "execution_id": "exec_a1b2c3d4"
}

CLI 等效命令: jamjet run workflow.yaml --input '{"query": "..."}'

GET /executions

列出执行记录，支持可选过滤。

查询参数：

参数类型默认值描述
statusstring—过滤：running、paused、completed、failed、cancelled
limitint50最大结果数
offsetint0分页偏移量

响应：

{
  "executions": [
    {
      "execution_id": "exec_a1b2c3d4",
      "workflow_id": "research-agent",
      "status": "completed",
      "created_at": "2026-03-12T10:00:00Z",
      "completed_at": "2026-03-12T10:00:04Z"
    }
  ]
}

GET /executions/:id

获取单个执行记录的完整状态。

响应：

{
  "execution_id": "exec_a1b2c3d4",
  "workflow_id": "research-agent",
  "status": "completed",
  "state": {
    "query": "Latest AI agent frameworks?",
    "answer": "..."
  },
  "steps_executed": 3,
  "created_at": "2026-03-12T10:00:00Z",
  "completed_at": "2026-03-12T10:00:04Z"
}

CLI 等效命令： jamjet inspect exec_a1b2c3d4

GET /executions/:id/events

获取执行记录的事件时间线。

响应：

{
  "events": [
    {
      "sequence": 1,
      "kind": "WorkflowStarted",
      "node_id": null,
      "created_at": "2026-03-12T10:00:00.000Z"
    },
    {
      "sequence": 2,
      "kind": "NodeCompleted",
      "node_id": "search",
      "created_at": "2026-03-12T10:00:00.200Z"
    },
    {
      "sequence": 3,
      "kind": "NodeCompleted",
      "node_id": "synthesize",
      "created_at": "2026-03-12T10:00:02.040Z"
    }
  ]
}

事件类型： WorkflowStarted、NodeScheduled、NodeCompleted、ApprovalReceived、ExternalEventReceived、ToolCallCompleted、WorkflowCancelled

CLI 等效命令： jamjet events exec_a1b2c3d4

POST /executions/:id/cancel

取消正在运行的执行。

响应：

{
  "execution_id": "exec_a1b2c3d4",
  "status": "cancelled"
}

POST /executions/:id/approve

为人工审核节点发送批准决策。

请求：

{
  "decision": "approved",
  "node_id": "manager-review",
  "user_id": "user-42",
  "comment": "Looks good, proceed.",
  "state_patch": {
    "priority": "high"
  }
}

仅 decision 为必填项。有效值："approved"、"rejected"。

响应：

{
  "execution_id": "exec_a1b2c3d4",
  "accepted": true
}

POST /executions/:id/external-event

注入外部事件以唤醒暂停的执行。

请求：

{
  "correlation_key": "payment-received",
  "payload": {
    "amount": 500,
    "currency": "USD"
  }
}

响应：

{
  "execution_id": "exec_a1b2c3d4",
  "accepted": true
}

Agents

POST /agents

使用 Agent Card 注册一个 agent。

请求：

{
  "id": "research-agent",
  "uri": "http://localhost:7701",
  "name": "Research Agent",
  "description": "Searches the web and synthesizes reports.",
  "version": "0.1.0",
  "capabilities": {
    "skills": [
      {
        "name": "research",
        "description": "Deep research on any topic",
        "input_schema": { "type": "object", "properties": { "query": { "type": "string" } } },
        "output_schema": { "type": "object", "properties": { "report": { "type": "string" } } }
      }
    ],
    "protocols": ["a2a"],
    "tools_provided": ["web_search"],
    "tools_consumed": []
  },
  "autonomy": "guided",
  "auth": { "type": "bearer_token" }
}

响应 201 Created：

{
  "agent_id": "research-agent"
}

GET /agents

列出 agents，支持可选过滤。

查询参数：

参数类型描述
statusstringregistered、active、paused、deactivated
skillstring按技能名称过滤
protocolstringmcp、a2a、anp

CLI 等效命令： jamjet agents list

GET /agents/:id

获取完整的 agent 详细信息，包括 Agent Card。

CLI 等效命令： jamjet agents inspect <agent_id>

POST /agents/discover

通过 URL 发现远程 agent。获取 /.well-known/agent.json 并注册该 agent。

请求：

{
  "url": "https://remote-agent.example.com"
}

响应 201 Created：完整的 agent 对象。

CLI 等效命令： jamjet agents discover <url>

POST /agents/:id/activate

激活已注册的 agent。

响应：

{
  "agent_id": "research-agent",
  "status": "active"
}

POST /agents/:id/deactivate

停用代理。

POST /agents/:id/heartbeat

代理存活心跳。

响应：

{
  "agent_id": "research-agent",
  "ok": true
}

审计日志

GET /audit

查询不可变审计日志。

查询参数：

参数类型默认值描述
execution_idstring—按执行筛选
actor_idstring—按操作者/用户筛选
event_typestring—按操作类型筛选
limitint50最大结果数（最大200）
offsetint0分页偏移量

响应：

{
  "items": [
    {
      "id": "audit_001",
      "execution_id": "exec_a1b2c3d4",
      "event_type": "node_completed",
      "actor_id": "agent:research-agent",
      "created_at": "2026-03-12T10:00:02Z"
    }
  ],
  "total": 42,
  "limit": 50,
  "offset": 0
}

租户

租户管理需要 operator 角色。

POST /tenants

创建新租户。

请求：

{
  "id": "acme",
  "name": "Acme Corp"
}

响应 201 Created：

{
  "tenant_id": "acme"
}

GET /tenants

列出所有租户。

GET /tenants/:id

获取租户详情。

PUT /tenants/:id

更新租户配置。

请求：

{
  "name": "Acme Corporation",
  "status": "active",
  "policy": { ... },
  "limits": { ... }
}

所有字段均为可选。

Workers

GET /workers

列出活跃的运行时 worker。

联邦

GET /.well-known/did.json

用于 A2A 联邦的 W3C DID 文档。无需身份验证。返回运行时的去中心化标识符及活跃 agent 的服务端点。

错误响应

所有错误都会返回带有相应 HTTP 状态码的 JSON：

状态含义示例
400错误请求{ "error": "bad request: ir.workflow_id is required" }
401未授权{ "error": "invalid or expired token" }
403禁止访问{ "error": "insufficient role — developer or operator required" }
404未找到{ "error": "not found: execution exec_abc123" }
500内部错误{ "error": "internal error: ..." }

配置

环境变量默认值说明
JAMJET_BIND127.0.0.1绑定地址
JAMJET_PORT7700HTTP 端口
JAMJET_PUBLIC_URLhttp://{bind}:{port}用于联邦的公开 URL
DATABASE_URL.jamjet/runtime.dbSQLite 或 PostgreSQL 连接字符串
JAMJET_TOKEN—默认 API 令牌（供客户端使用）
RUST_LOGinfo日志级别

CLI 到 API 映射

CLI 命令API 端点
jamjet run <wf> --input <json>POST /executions
jamjet inspect <exec_id>GET /executions/:id + GET /executions/:id/events
jamjet events <exec_id>GET /executions/:id/events
jamjet agents listGET /agents
jamjet agents inspect <id>GET /agents/:id
jamjet agents activate <id>POST /agents/:id/activate
jamjet agents deactivate <id>POST /agents/:id/deactivate
jamjet agents discover <url>POST /agents/discover

注意： jamjet dev 在本地启动运行时服务器。jamjet validate 和 jamjet eval run 是客户端操作，不会调用 API。

A2A 集成

使用 Agent-to-Agent 协议委派给其他代理或为其他代理提供服务。

CLI 参考

jamjet 命令行界面的完整参考。

On this page

REST API 参考身份验证角色健康检查GET /health工作流POST /workflows执行POST /executionsGET /executionsGET /executions/:idGET /executions/:id/eventsPOST /executions/:id/cancelPOST /executions/:id/approvePOST /executions/:id/external-eventAgentsPOST /agentsGET /agentsGET /agents/:idPOST /agents/discoverPOST /agents/:id/activatePOST /agents/:id/deactivatePOST /agents/:id/heartbeat审计日志GET /audit租户POST /tenantsGET /tenantsGET /tenants/:idPUT /tenants/:idWorkersGET /workers联邦GET /.well-known/did.json错误响应配置CLI 到 API 映射