尧图网页设计 
人工智能AI AgentAgent 框架自主智能体【免费下载链接】axGoogles open agentic orchestration runtime项目地址https://gitcode.com/GitHub_Trending/ax11/ax点击查看免费下载导读本文以 DESIGN.md 为核心深入剖析 AXGoogle 开源的自主 Agent 编排运行时的整体架构设计与 gRPC 控制面 API。文章首先解释 AX 为何选择 Redis 而非 Kubernetes CRD 作为状态存储随后拆解ax、ax-server、ax-task-runner三个二进制组件的职责边界最后完整梳理ax.v1alpha1.AXgRPC 服务的全部 RPC 与健康检查约定。读者在阅读后将掌握 AX 控制面的数据流、分布式锁与直接协调机制以及通过 CLI 调用各 RPC 的实战路径。架构为什么是 Redis而不是 Kubernetes CRDDESIGN.md 开篇点明了 AX 架构决策的出发点将数以百万计的短生命周期任务存储为 Kubernetes CRD会让 etcd 超出其舒适区——个位数 GB 的存储上限、写速率瓶颈、控制面性能劣化三者叠加会拖垮整个集群。因此 AX 把状态存进 Redis并在细粒度分布式锁的保护下直接与 Agent Substrate 进行协调reconcile。ax apply -f task.yaml │ ▼ ax-server (gRPC API /healthz) │ ┌──────────────────────┴──────────────────────┐ ▼ ▼ Redis Agent Substrate (Resource Store, ┌───────────────────────────────┐ Locks, PubSub) │ • Atespace Provisioning │ │ • Actor Creation Activation │ │ • Worker Assignment │ └───────────────────────────────┘这张架构图完整勾勒出 AX 的三大组成客户端axCLIax apply -f task.yaml把清单解析后通过类型化 RPC 提交给服务端服务端永远不直接接触原始 YAMLax-server对外暴露 gRPC API 与/healthzHTTP 健康检查同时作为协调中枢——它持有 Redis 连接也持有 Agent Substrate 客户端数据与运行时两侧左侧 Redis 承担 Resource Store、Locks、PubSub 三个角色右侧 Agent Substrate 负责 Atespace Provisioning、Actor Creation Activation、Worker Assignment 等沙箱生命周期能力。Redis 的三重角色存储、锁与发布订阅从 internal/store/redis/store.go 的源码可以看出Redis Store 用统一前缀ax组织三类资源键任务键ax:task:atespace:name并配全局索引ax:tasks:index与按 atespace 分组的ax:tasks:atespace:atespace工作空间键ax:workspace:atespace:name对应索引ax:workspaces:index/ax:workspaces:atespace:atespace模型键ax:model:atespace:name对应索引ax:models:index/ax:models:atespace:atespace。对象以 protojson 序列化后落盘EmitUnpopulated: false保证零值字段不占空间同时保留 API 线格式的 camelCase 命名。Watch 事件通道同样复用 Redis Pub/Subax:pubsub:task:atespace:name是单任务的状态变更频道WatchTaskRPC 在服务端订阅该频道并把变更流式推给客户端详见下文 API 部分。分布式锁实现在 internal/lock/lock.go 的RedisLocker中锁键形如lock:kind:atespace:name加锁用SET NX PX默认 TTL 30 秒RedisLockerOptions.TTL可调并生成 16 字节随机 token 作持有者凭证。释放锁时通过一段 Lua 脚本原子地校验 token、删除键并向lock:chan:kind:atespace:name频道发布通知if redis.call(get, KEYS[1]) ARGV[1] then local res redis.call(del, KEYS[1]) redis.call(publish, KEYS[2], 1) return res else return 0 end这带来一个对短任务场景至关重要的特性竞争等待者能被锁释放通知立即唤醒而不是靠固定间隔轮询空转。RedisLocker.Lock实现分为快路径直接SetNX尝试与慢路径先订阅 Pub/Sub 频道再以 1 秒FallbackInterval兜底重试防止通知丢失或 TTL 静默过期。服务端无锁场景下例如单元测试或本地模式则由MemoryLocker进程内按kind/atespace/name键控的互斥锁兜底这正对应 internal/server/server.go 中NewServer的逻辑未注入 Locker 时自动使用lock.NewMemoryLocker()。直接协调跳过控制器循环传统 Kubernetes 风格的控制面会在控制器循环里反复观察-比较-收敛。AX 则不同——ax-server在处理 CreateTask、SuspendTask、ResumeTask、DeleteTask 等写操作时直接调用 reconciler 与 Agent Substrate 通信。以CreateTask为例internal/server/server.go 的调用链是v1alpha1.ValidateTask做清单校验非法输入直接返回InvalidArgument以atespace缺省default与任务名获取独占锁加锁失败返回Aborted检查同名任务是否已存在——存在则返回FailedPrecondition因为任务一经创建即不可变补全creationTimestamp把 phase 置为Suspended并SaveTask落库调用reconciler.Reconcile(ctx, task, workspaces...)在 Substrate 上完成 Atespace、Actor、ActorTemplate 的编排随后把协调结果写回状态协调失败则把 phase 置为Failed并持久化。这段源码也印证了架构图右侧 Substrate 的三项职责且每项在 internal/controller/reconciler.go 中都有对应实现Atespace ProvisioningEnsureAtespace失败即标记AtespaceCreationFailed条件Actor Creation ActivationEnsureActorResumeActor挂起用SuspendActoractor 名与任务名保持一致便于路由系统通过ate-target-actor: atespace/actor头寻址Worker AssignmentResumeActor返回 worker IP写入TaskStatus.WorkerIp并作为任务可寻址端点。协调器还会为任务注入运行环境AX_TASK_YAML携带剔除 Status 后的任务清单AX_WORKSPACES_YAML携带绑定工作空间的多文档 YAML 流两者由容器内的ax-task-runner消费见 cmd/ax-task-runner/main.go 的注释说明同时优先从 Kubernetes Secretgemini-api-secret的GEMINI_API_KEY键解析模型凭证注入容器环境。组件三个二进制的职责边界DESIGN.md 用一张表格定义了三个组件的角色二进制角色ax开发者 CLI。应用清单、查看与监听资源、隧道到集群。ax-server8080 端口的直接执行 gRPC API。校验清单、管理分布式锁、直接与 Agent Substrate 协调、把状态持久化到 Redis。ax-task-runner每个任务容器内的入口。引导工作空间、提供元数据服务、运行 Agent 命令。是对runner包的薄封装自定义镜像可以直接内嵌该包。ax开发者 CLIax的全部子命令定义在 cmd/ax/main.go 的 usage 输出中与 DESIGN.md 描述一一对应apply -f file Apply resources (tasks, workspaces, models) from a file or stdin get tasks List tasks get task name Get a specific task get workspaces List workspaces get workspace name Get a specific workspace get models List models get model name Get a specific model describe task name Show detailed information about a task describe workspace name Show detailed information about a workspace describe model name Show detailed information about a model watch task name Stream live status and condition updates for a task ssh task-name [-- cmd] Run a command or shell inside the running task container suspend task name Suspend execution of a task and checkpoint state resume task name Resume execution of a suspended task delete task name Delete a task delete workspace name Delete a workspace delete model name Delete a model ctx, context Show active Kubernetes context and AX connection tunnel list|stop Manage background tunnels to Kubernetes clusters version Print AX version全局 Flags 包括-a, --atespace任务作用域默认default-n, --namespaceAX 安装所在的 Kubernetes 命名空间默认ax-system--contextKubernetes 上下文默认取当前kubectx/current-context--serverAX API 服务器地址默认根据 kube context 或环境变量$AX_SERVER自动探测。值得注意的 CLI 行为细节apply 的幂等语义applyDocument按 kind 分发——Task走CreateTask任务不可变重复创建会报错Workspace/Model走UpdateWorkspace/UpdateModel并仿照kubectl apply输出created/configured/unchanged三种结果applyOutcome 通过比较新旧 spec 的 proto 相等性判定输出格式为kind.ax.io/name outcome例如task.ax.io/simple-task createdapply 输入-f file必填-表示从 stdin 读取单个文件可含多个---分隔的文档逐个提交watch 语义ax watch task name订阅WatchTask流逐行打印时间戳、Phase、Actor、WorkerIP进入Completed或Failed终态即退出delete 的等待窗口删除任务时客户端把超时放宽到 2 分钟其他资源 30 秒因为服务端要先在 Substrate 上完成 actor 与模板的清理ssh 前置条件任务必须处于Running且spec.debug: true详见下文 Task 清单否则 CLI 会明确报错拒绝连接cmd/ax/main.go。ax-server控制面服务ax-server的启动参数定义在 cmd/ax-server/main.go这些参数直接对应架构图中的 Redis 与 Substrate 两侧参数默认值说明-addr:8080HTTP 监听地址同时承载 gRPC 与/healthz可用环境变量ADDR覆盖-redis-addrlocalhost:6379Redis 服务地址REDIS_ADDR-redis-password空Redis 密码REDIS_PASSWORD-substrate-endpointapi.ate-system.svc.cluster.local:443Agent Substrate Control API 端点-substrate-authorityapi.ate-system.svcSubstrate 端点的 Authority / TLS ServerName-substrate-token-file空Substrate 认证的 bearer token 文件路径-substrate-ca-file空Substrate TLS 的 CA PEM 文件路径-substrate-insecure-tlsfalse跳过 Substrate TLS 校验-substrate-plaintextfalse以明文 gRPC 连接 Substrate-templatedefault-template默认 Substrate ActorTemplate 名-template-atespaceax-system默认 ActorTemplate 所在 atespace实现层面有三个关键点单端口双协议Server.Handler检查 HTTP/2 application/grpcContent-Type命中则交给 gRPC server 处理否则响应/healthz返回200 OK与ok\n或 404main 中通过http.Protocols同时开启 HTTP/1.1 与明文 HTTP/2gRPC 需要的 h2c优雅降级Substrate 客户端初始化失败时例如本地开发没有集群服务端打警告并不带 reconciler 运行——此时资源读写、锁、健康检查照常工作只是不做 Substrate 编排优雅关停监听SIGINT/SIGTERM5 秒内完成http.Server.Shutdown。ax-task-runner任务容器入口ax-task-runner是每个任务容器内运行的 entrypoint它从两个环境变量读取规格AX_TASK_YAML任务清单与AX_WORKSPACES_YAML绑定工作空间的多文档流。为方便本地调试cmd/ax-task-runner/main.go 还提供两个覆盖式 Flags-port元数据与 guest 服务的监听端口默认取runner.DefaultPort-task-file/-workspace-file可重复从文件读取规格替代环境变量。它把解析出的Task与Workspace装入runner.Config后交给runner.Run——即 DESIGN.md 所说的对runner包的薄封装自定义镜像可以直接内嵌该包。debug: true时还会开启进程执行与文件访问等 guest 服务为ax ssh提供能力支撑。API 参考ax.v1alpha1.AX gRPC 服务控制面暴露ax.v1alpha1.AXgRPC 服务健康检查是普通 HTTP——同一端口的GET /healthz返回200 OK。服务定义完整写在 pkg/apis/v1alpha1/ax.proto 中生成的 Go 类型位于pkg/apis/v1alpha1对应ax.pb.go与ax_grpc.pb.go。TasksRPC描述GetTask按 atespace 与名称获取任务。ListTasks列出 atespace 中的任务支持分页。CreateTask创建任务任务一经创建即不可变。DeleteTask删除任务。SuspendTask对 Actor 状态做 checkpoint 并暂停任务。ResumeTask恢复被挂起的任务。WatchTask服务端流式 RPC实时推送状态与条件condition变迁。从 proto 定义可以进一步看到请求/响应类型的细节所有 Get/Delete/Suspend/Resume/List 类请求都携带atespace与name或limit/offset服务端对空atespace统一回填defaultListTasksRequest的limit、offset即分页参数服务端默认limit50, offset0WatchTaskResponse由task与action组成action取值INITIAL首次快照或MODIFIED后续变更WatchTask服务端实现internal/server/server.go先推送一次当前任务快照再订阅 Redis Pub/Sub 频道持续推送直到任务进入Failed或Completed终态后自行关闭流。Task消息体的结构为apiVersion kind metadata spec status。TaskSpec关键字段image容器镜像缺省用gcr.io/ax-substrate/ate-images/ax-task-runnercommandAgent 启动命令字符串数组envEnvVar列表注入容器环境resourcesrequests/limits下的cpu、memory字符串类似 Kubernetes 的资源量语法workspaces一个或多个WorkspaceRefname 挂载path 可选goal每个挂载在/workspace下的各自路径上其中第一个条目是任务命令的工作目录debug是否开启容器内 guest 服务进程执行与文件访问它们支撑ax ssh默认关闭。TaskStatus包含phase、id、actor、workerIPYAML/JSON 中拼写为workerIP、pendingApproval、usageprompt/completion token 计数与conditions列表。Condition沿用 Kubernetes 条件模式typestatuslastTransitionTimereasonmessage协调器实际维护Ready与WorkspaceReady两类条件internal/controller/reconciler.go。WorkspacesRPC描述GetWorkspace按 atespace 与名称获取工作空间。ListWorkspaces列出 atespace 中的工作空间。UpdateWorkspace创建或更新工作空间。DeleteWorkspace删除工作空间。WorkspaceSpec由四部分组成gitGit 仓库列表字段含name/repo/branch/dir/depth、filespathcontent的静态文件、mcpMCPConfigregistries按provider/project/query声明注册源servers声明nameendpoint或commandargs的 MCP 服务器、skillsSkillsConfigregistries 本地path。工作空间通过UpdateWorkspace幂等创建/更新写入时同样先取lock:workspace:...锁。ModelsRPC描述GetModel按 atespace 与名称获取模型配置。ListModels列出 atespace 中的模型配置。UpdateModel创建或更新模型配置。DeleteModel删除模型配置。ModelSpec的核心字段是provider、model、secretKeySecretKeyRefnamekey引用 Kubernetes Secret 中的凭证与自由形式的parametersgoogle.protobuf.Struct。设计上有一个值得注意的演进proto 中字段 3-5原先的temperature、max_tokens、system_instruction已被reserved保留provider 专属的生成参数统一放进parameters映射原样透传给模型 API例如 Gemini 的temperature、maxOutputTokens。这保证了模型配置对多 provider 的开放性与向前兼容。请求/响应约定与类型DESIGN.md 明确指出请求与响应类型遵循MethodRequest/MethodResponse命名约定生成的 Go 类型位于pkg/apis/v1alpha1。结合 pkg/apis/v1alpha1/types.go 可以补充三点实现细节版本与 kind 常量apiVersion ax.io/v1alpha1kind 为Task/Workspace/Model严格校验YAML 清单先被通用解码转 JSON 后交给protojson.Unmarshal严格解码——未知字段或拼写错误的字段直接报错不静默丢弃YAML 输出保序CLI 的get task name等命令通过protojson序列化再转yaml.Node输出字段顺序跟随 proto 定义而非字母序字符串标量如True也会被正确加引号防止类型歧义。一次端到端的数据流apply → 协调 → watch把架构图与源码调用链拼起来一次ax apply -f task.yaml的完整旅程是CLI 解析ax用 yaml.v3 解码文件支持多文档按 kind 路由到类型化 RPC服务端收到的永远是强类型的 protobuf 消息服务端加锁落库ax-server对task/atespace/name取分布式锁校验幂等性把 phase 置Suspended写入 Redis直接协调TaskReconciler.Reconcile依次EnsureAtespace→EnsureActor/EnsureActorTemplateWithImage→视 phaseSuspendActor或ResumeActorResumeActor返回的 worker IP 写回TaskStatus.WorkerIp随后以 500ms 间隔、最长 15 秒轮询 worker 的/readyz?checkworkspace直连失败时经ATENET_ROUTER_ADDR走ate-target-actor头路由确认工作空间就绪后才把Ready条件置True状态回写与通知协调结果写回 Redis 并触发 Pub/Sub 事件ax watch task name的流式 RPC 借此把状态变迁实时推到终端直至终态。至此DESIGN.md 所描绘的Redis 存状态、细粒度锁保一致、直连 Substrate 协调的架构在源码层面得到了完整的闭环印证。读者可对照 examples/simple.yaml一个最小的可运行 Task 清单在本地启动ax-server后执行ax apply -f examples/simple.yaml、ax describe task simple-task与ax ssh simple-task -- ls -la /workspace亲自验证。赞分享人工智能AI AgentAgent 框架自主智能体【免费下载链接】axGoogles open agentic orchestration runtime项目地址https://gitcode.com/GitHub_Trending/ax11/ax点击查看免费下载相关推荐Happy Manager Agent 编排指南基于 happy-agent 的多 Agent 委派控制平面设计与实战Happy Manager Agent 编排指南基于 happy agent 的多 Agent 委派控制平面设计与实战 本篇技术指南围绕 Happy 项目中的人工智能AI AgentAI 应用移动开发CLI后端Agent Substrate 威胁模型深度解析面向有状态 AI Agent 编排系统的安全设计全景Agent Substrate 威胁模型深度解析面向有状态 AI Agent 编排系统的安全设计全景 本文基于 docs/threat model.md ht人工智能AI AgentAgent 沙箱云原生容器运行时零信任Paseo 架构解析本地优先的多 Agent 编排系统设计与 WebSocket 协议详解Paseo 架构解析本地优先的多 Agent 编排系统设计与 WebSocket 协议详解 Paseo 是一套客户端 服务器架构的本地 AI 编码 Age创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 AX 系统架构与 API 设计详解：基于 Redis 与 Agent Substrate 的自主 Agent 编排控制面
人工智能AI AgentAgent 框架自主智能体【免费下载链接】axGoogles open agentic orchestration runtime项目地址https://gitcode.com/GitHub_Trending/ax11/ax点击查看免费下载导读本文以 DESIGN.md 为核心深入剖析 AXGoogle 开源的自主 Agent 编排运行时的整体架构设计与 gRPC 控制面 API。文章首先解释 AX 为何选择 Redis 而非 Kubernetes CRD 作为状态存储随后拆解ax、ax-server、ax-task-runner三个二进制组件的职责边界最后完整梳理ax.v1alpha1.AXgRPC 服务的全部 RPC 与健康检查约定。读者在阅读后将掌握 AX 控制面的数据流、分布式锁与直接协调机制以及通过 CLI 调用各 RPC 的实战路径。架构为什么是 Redis而不是 Kubernetes CRDDESIGN.md 开篇点明了 AX 架构决策的出发点将数以百万计的短生命周期任务存储为 Kubernetes CRD会让 etcd 超出其舒适区——个位数 GB 的存储上限、写速率瓶颈、控制面性能劣化三者叠加会拖垮整个集群。因此 AX 把状态存进 Redis并在细粒度分布式锁的保护下直接与 Agent Substrate 进行协调reconcile。ax apply -f task.yaml │ ▼ ax-server (gRPC API /healthz) │ ┌──────────────────────┴──────────────────────┐ ▼ ▼ Redis Agent Substrate (Resource Store, ┌───────────────────────────────┐ Locks, PubSub) │ • Atespace Provisioning │ │ • Actor Creation Activation │ │ • Worker Assignment │ └───────────────────────────────┘这张架构图完整勾勒出 AX 的三大组成客户端axCLIax apply -f task.yaml把清单解析后通过类型化 RPC 提交给服务端服务端永远不直接接触原始 YAMLax-server对外暴露 gRPC API 与/healthzHTTP 健康检查同时作为协调中枢——它持有 Redis 连接也持有 Agent Substrate 客户端数据与运行时两侧左侧 Redis 承担 Resource Store、Locks、PubSub 三个角色右侧 Agent Substrate 负责 Atespace Provisioning、Actor Creation Activation、Worker Assignment 等沙箱生命周期能力。Redis 的三重角色存储、锁与发布订阅从 internal/store/redis/store.go 的源码可以看出Redis Store 用统一前缀ax组织三类资源键任务键ax:task:atespace:name并配全局索引ax:tasks:index与按 atespace 分组的ax:tasks:atespace:atespace工作空间键ax:workspace:atespace:name对应索引ax:workspaces:index/ax:workspaces:atespace:atespace模型键ax:model:atespace:name对应索引ax:models:index/ax:models:atespace:atespace。对象以 protojson 序列化后落盘EmitUnpopulated: false保证零值字段不占空间同时保留 API 线格式的 camelCase 命名。Watch 事件通道同样复用 Redis Pub/Subax:pubsub:task:atespace:name是单任务的状态变更频道WatchTaskRPC 在服务端订阅该频道并把变更流式推给客户端详见下文 API 部分。分布式锁实现在 internal/lock/lock.go 的RedisLocker中锁键形如lock:kind:atespace:name加锁用SET NX PX默认 TTL 30 秒RedisLockerOptions.TTL可调并生成 16 字节随机 token 作持有者凭证。释放锁时通过一段 Lua 脚本原子地校验 token、删除键并向lock:chan:kind:atespace:name频道发布通知if redis.call(get, KEYS[1]) ARGV[1] then local res redis.call(del, KEYS[1]) redis.call(publish, KEYS[2], 1) return res else return 0 end这带来一个对短任务场景至关重要的特性竞争等待者能被锁释放通知立即唤醒而不是靠固定间隔轮询空转。RedisLocker.Lock实现分为快路径直接SetNX尝试与慢路径先订阅 Pub/Sub 频道再以 1 秒FallbackInterval兜底重试防止通知丢失或 TTL 静默过期。服务端无锁场景下例如单元测试或本地模式则由MemoryLocker进程内按kind/atespace/name键控的互斥锁兜底这正对应 internal/server/server.go 中NewServer的逻辑未注入 Locker 时自动使用lock.NewMemoryLocker()。直接协调跳过控制器循环传统 Kubernetes 风格的控制面会在控制器循环里反复观察-比较-收敛。AX 则不同——ax-server在处理 CreateTask、SuspendTask、ResumeTask、DeleteTask 等写操作时直接调用 reconciler 与 Agent Substrate 通信。以CreateTask为例internal/server/server.go 的调用链是v1alpha1.ValidateTask做清单校验非法输入直接返回InvalidArgument以atespace缺省default与任务名获取独占锁加锁失败返回Aborted检查同名任务是否已存在——存在则返回FailedPrecondition因为任务一经创建即不可变补全creationTimestamp把 phase 置为Suspended并SaveTask落库调用reconciler.Reconcile(ctx, task, workspaces...)在 Substrate 上完成 Atespace、Actor、ActorTemplate 的编排随后把协调结果写回状态协调失败则把 phase 置为Failed并持久化。这段源码也印证了架构图右侧 Substrate 的三项职责且每项在 internal/controller/reconciler.go 中都有对应实现Atespace ProvisioningEnsureAtespace失败即标记AtespaceCreationFailed条件Actor Creation ActivationEnsureActorResumeActor挂起用SuspendActoractor 名与任务名保持一致便于路由系统通过ate-target-actor: atespace/actor头寻址Worker AssignmentResumeActor返回 worker IP写入TaskStatus.WorkerIp并作为任务可寻址端点。协调器还会为任务注入运行环境AX_TASK_YAML携带剔除 Status 后的任务清单AX_WORKSPACES_YAML携带绑定工作空间的多文档 YAML 流两者由容器内的ax-task-runner消费见 cmd/ax-task-runner/main.go 的注释说明同时优先从 Kubernetes Secretgemini-api-secret的GEMINI_API_KEY键解析模型凭证注入容器环境。组件三个二进制的职责边界DESIGN.md 用一张表格定义了三个组件的角色二进制角色ax开发者 CLI。应用清单、查看与监听资源、隧道到集群。ax-server8080 端口的直接执行 gRPC API。校验清单、管理分布式锁、直接与 Agent Substrate 协调、把状态持久化到 Redis。ax-task-runner每个任务容器内的入口。引导工作空间、提供元数据服务、运行 Agent 命令。是对runner包的薄封装自定义镜像可以直接内嵌该包。ax开发者 CLIax的全部子命令定义在 cmd/ax/main.go 的 usage 输出中与 DESIGN.md 描述一一对应apply -f file Apply resources (tasks, workspaces, models) from a file or stdin get tasks List tasks get task name Get a specific task get workspaces List workspaces get workspace name Get a specific workspace get models List models get model name Get a specific model describe task name Show detailed information about a task describe workspace name Show detailed information about a workspace describe model name Show detailed information about a model watch task name Stream live status and condition updates for a task ssh task-name [-- cmd] Run a command or shell inside the running task container suspend task name Suspend execution of a task and checkpoint state resume task name Resume execution of a suspended task delete task name Delete a task delete workspace name Delete a workspace delete model name Delete a model ctx, context Show active Kubernetes context and AX connection tunnel list|stop Manage background tunnels to Kubernetes clusters version Print AX version全局 Flags 包括-a, --atespace任务作用域默认default-n, --namespaceAX 安装所在的 Kubernetes 命名空间默认ax-system--contextKubernetes 上下文默认取当前kubectx/current-context--serverAX API 服务器地址默认根据 kube context 或环境变量$AX_SERVER自动探测。值得注意的 CLI 行为细节apply 的幂等语义applyDocument按 kind 分发——Task走CreateTask任务不可变重复创建会报错Workspace/Model走UpdateWorkspace/UpdateModel并仿照kubectl apply输出created/configured/unchanged三种结果applyOutcome 通过比较新旧 spec 的 proto 相等性判定输出格式为kind.ax.io/name outcome例如task.ax.io/simple-task createdapply 输入-f file必填-表示从 stdin 读取单个文件可含多个---分隔的文档逐个提交watch 语义ax watch task name订阅WatchTask流逐行打印时间戳、Phase、Actor、WorkerIP进入Completed或Failed终态即退出delete 的等待窗口删除任务时客户端把超时放宽到 2 分钟其他资源 30 秒因为服务端要先在 Substrate 上完成 actor 与模板的清理ssh 前置条件任务必须处于Running且spec.debug: true详见下文 Task 清单否则 CLI 会明确报错拒绝连接cmd/ax/main.go。ax-server控制面服务ax-server的启动参数定义在 cmd/ax-server/main.go这些参数直接对应架构图中的 Redis 与 Substrate 两侧参数默认值说明-addr:8080HTTP 监听地址同时承载 gRPC 与/healthz可用环境变量ADDR覆盖-redis-addrlocalhost:6379Redis 服务地址REDIS_ADDR-redis-password空Redis 密码REDIS_PASSWORD-substrate-endpointapi.ate-system.svc.cluster.local:443Agent Substrate Control API 端点-substrate-authorityapi.ate-system.svcSubstrate 端点的 Authority / TLS ServerName-substrate-token-file空Substrate 认证的 bearer token 文件路径-substrate-ca-file空Substrate TLS 的 CA PEM 文件路径-substrate-insecure-tlsfalse跳过 Substrate TLS 校验-substrate-plaintextfalse以明文 gRPC 连接 Substrate-templatedefault-template默认 Substrate ActorTemplate 名-template-atespaceax-system默认 ActorTemplate 所在 atespace实现层面有三个关键点单端口双协议Server.Handler检查 HTTP/2 application/grpcContent-Type命中则交给 gRPC server 处理否则响应/healthz返回200 OK与ok\n或 404main 中通过http.Protocols同时开启 HTTP/1.1 与明文 HTTP/2gRPC 需要的 h2c优雅降级Substrate 客户端初始化失败时例如本地开发没有集群服务端打警告并不带 reconciler 运行——此时资源读写、锁、健康检查照常工作只是不做 Substrate 编排优雅关停监听SIGINT/SIGTERM5 秒内完成http.Server.Shutdown。ax-task-runner任务容器入口ax-task-runner是每个任务容器内运行的 entrypoint它从两个环境变量读取规格AX_TASK_YAML任务清单与AX_WORKSPACES_YAML绑定工作空间的多文档流。为方便本地调试cmd/ax-task-runner/main.go 还提供两个覆盖式 Flags-port元数据与 guest 服务的监听端口默认取runner.DefaultPort-task-file/-workspace-file可重复从文件读取规格替代环境变量。它把解析出的Task与Workspace装入runner.Config后交给runner.Run——即 DESIGN.md 所说的对runner包的薄封装自定义镜像可以直接内嵌该包。debug: true时还会开启进程执行与文件访问等 guest 服务为ax ssh提供能力支撑。API 参考ax.v1alpha1.AX gRPC 服务控制面暴露ax.v1alpha1.AXgRPC 服务健康检查是普通 HTTP——同一端口的GET /healthz返回200 OK。服务定义完整写在 pkg/apis/v1alpha1/ax.proto 中生成的 Go 类型位于pkg/apis/v1alpha1对应ax.pb.go与ax_grpc.pb.go。TasksRPC描述GetTask按 atespace 与名称获取任务。ListTasks列出 atespace 中的任务支持分页。CreateTask创建任务任务一经创建即不可变。DeleteTask删除任务。SuspendTask对 Actor 状态做 checkpoint 并暂停任务。ResumeTask恢复被挂起的任务。WatchTask服务端流式 RPC实时推送状态与条件condition变迁。从 proto 定义可以进一步看到请求/响应类型的细节所有 Get/Delete/Suspend/Resume/List 类请求都携带atespace与name或limit/offset服务端对空atespace统一回填defaultListTasksRequest的limit、offset即分页参数服务端默认limit50, offset0WatchTaskResponse由task与action组成action取值INITIAL首次快照或MODIFIED后续变更WatchTask服务端实现internal/server/server.go先推送一次当前任务快照再订阅 Redis Pub/Sub 频道持续推送直到任务进入Failed或Completed终态后自行关闭流。Task消息体的结构为apiVersion kind metadata spec status。TaskSpec关键字段image容器镜像缺省用gcr.io/ax-substrate/ate-images/ax-task-runnercommandAgent 启动命令字符串数组envEnvVar列表注入容器环境resourcesrequests/limits下的cpu、memory字符串类似 Kubernetes 的资源量语法workspaces一个或多个WorkspaceRefname 挂载path 可选goal每个挂载在/workspace下的各自路径上其中第一个条目是任务命令的工作目录debug是否开启容器内 guest 服务进程执行与文件访问它们支撑ax ssh默认关闭。TaskStatus包含phase、id、actor、workerIPYAML/JSON 中拼写为workerIP、pendingApproval、usageprompt/completion token 计数与conditions列表。Condition沿用 Kubernetes 条件模式typestatuslastTransitionTimereasonmessage协调器实际维护Ready与WorkspaceReady两类条件internal/controller/reconciler.go。WorkspacesRPC描述GetWorkspace按 atespace 与名称获取工作空间。ListWorkspaces列出 atespace 中的工作空间。UpdateWorkspace创建或更新工作空间。DeleteWorkspace删除工作空间。WorkspaceSpec由四部分组成gitGit 仓库列表字段含name/repo/branch/dir/depth、filespathcontent的静态文件、mcpMCPConfigregistries按provider/project/query声明注册源servers声明nameendpoint或commandargs的 MCP 服务器、skillsSkillsConfigregistries 本地path。工作空间通过UpdateWorkspace幂等创建/更新写入时同样先取lock:workspace:...锁。ModelsRPC描述GetModel按 atespace 与名称获取模型配置。ListModels列出 atespace 中的模型配置。UpdateModel创建或更新模型配置。DeleteModel删除模型配置。ModelSpec的核心字段是provider、model、secretKeySecretKeyRefnamekey引用 Kubernetes Secret 中的凭证与自由形式的parametersgoogle.protobuf.Struct。设计上有一个值得注意的演进proto 中字段 3-5原先的temperature、max_tokens、system_instruction已被reserved保留provider 专属的生成参数统一放进parameters映射原样透传给模型 API例如 Gemini 的temperature、maxOutputTokens。这保证了模型配置对多 provider 的开放性与向前兼容。请求/响应约定与类型DESIGN.md 明确指出请求与响应类型遵循MethodRequest/MethodResponse命名约定生成的 Go 类型位于pkg/apis/v1alpha1。结合 pkg/apis/v1alpha1/types.go 可以补充三点实现细节版本与 kind 常量apiVersion ax.io/v1alpha1kind 为Task/Workspace/Model严格校验YAML 清单先被通用解码转 JSON 后交给protojson.Unmarshal严格解码——未知字段或拼写错误的字段直接报错不静默丢弃YAML 输出保序CLI 的get task name等命令通过protojson序列化再转yaml.Node输出字段顺序跟随 proto 定义而非字母序字符串标量如True也会被正确加引号防止类型歧义。一次端到端的数据流apply → 协调 → watch把架构图与源码调用链拼起来一次ax apply -f task.yaml的完整旅程是CLI 解析ax用 yaml.v3 解码文件支持多文档按 kind 路由到类型化 RPC服务端收到的永远是强类型的 protobuf 消息服务端加锁落库ax-server对task/atespace/name取分布式锁校验幂等性把 phase 置Suspended写入 Redis直接协调TaskReconciler.Reconcile依次EnsureAtespace→EnsureActor/EnsureActorTemplateWithImage→视 phaseSuspendActor或ResumeActorResumeActor返回的 worker IP 写回TaskStatus.WorkerIp随后以 500ms 间隔、最长 15 秒轮询 worker 的/readyz?checkworkspace直连失败时经ATENET_ROUTER_ADDR走ate-target-actor头路由确认工作空间就绪后才把Ready条件置True状态回写与通知协调结果写回 Redis 并触发 Pub/Sub 事件ax watch task name的流式 RPC 借此把状态变迁实时推到终端直至终态。至此DESIGN.md 所描绘的Redis 存状态、细粒度锁保一致、直连 Substrate 协调的架构在源码层面得到了完整的闭环印证。读者可对照 examples/simple.yaml一个最小的可运行 Task 清单在本地启动ax-server后执行ax apply -f examples/simple.yaml、ax describe task simple-task与ax ssh simple-task -- ls -la /workspace亲自验证。赞分享人工智能AI AgentAgent 框架自主智能体【免费下载链接】axGoogles open agentic orchestration runtime项目地址https://gitcode.com/GitHub_Trending/ax11/ax点击查看免费下载相关推荐Happy Manager Agent 编排指南基于 happy-agent 的多 Agent 委派控制平面设计与实战Happy Manager Agent 编排指南基于 happy agent 的多 Agent 委派控制平面设计与实战 本篇技术指南围绕 Happy 项目中的人工智能AI AgentAI 应用移动开发CLI后端Agent Substrate 威胁模型深度解析面向有状态 AI Agent 编排系统的安全设计全景Agent Substrate 威胁模型深度解析面向有状态 AI Agent 编排系统的安全设计全景 本文基于 docs/threat model.md ht人工智能AI AgentAgent 沙箱云原生容器运行时零信任Paseo 架构解析本地优先的多 Agent 编排系统设计与 WebSocket 协议详解Paseo 架构解析本地优先的多 Agent 编排系统设计与 WebSocket 协议详解 Paseo 是一套客户端 服务器架构的本地 AI 编码 Age创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考