agent.acl

agent.acl 是文件系统优先形态里的运行配置入口。它负责把模型、provider、并行度、队列、存储、skill 目录和 worker agent 目录固化为可版本化配置。

SDK 宿主可以用 Agent.create("agent.acl") 显式传入任意 .acl 文件。 a3s code TUI 会从 workspace 向上发现 .a3s/config.acl，然后读取 ~/.a3s/config.acl；它并不要求仓库根部存在 agent.acl。AgentDir 内的 agent.acl 服务于该目录的长期 Agent。三者格式一致，但发现方式和作用范围不同。

基础配置

Text

default_model = "provider/model-id"
max_parallel_tasks = 4
auto_parallel = false

providers "provider" {
  apiKey = env("PROVIDER_API_KEY")
  baseUrl = env("PROVIDER_BASE_URL")

  models "model-id" {
    tool_call = true
    limit = {
      context = 128000
      output = 4096
    }
  }
}

apiKey / api_key 和 baseUrl / base_url 都是可接受别名。运行时不硬编码模型名；default_model 和 session 级 model 覆盖必须匹配这里声明的 provider/model-id。

把 token 通过环境变量注入，不要写进 agent.acl。配置文件进入仓库后，它就是产品行为的一部分，应该像代码一样审查。

目录发现

Text

skill_dirs = ["./.a3s/skills"]
agent_dirs = ["./.a3s/agents"]

auto_delegation {
  enabled        = true
  min_confidence = 0.72
  max_tasks      = 4
  auto_parallel  = false
}

skill_dirs 指向可复用技能目录；agent_dirs 指向 worker/subagent 定义目录。自动委派只决定是否让模型选择 worker，不会取消父 session 的权限策略、工具可见性或验证要求。

Session 存储

Text

storage_backend = "file"
sessions_dir = ".a3s/sessions"

当 session 没有显式收到 SDK sessionStore 时，sessions_dir 是本地文件型 session persistence 路径。storage_backend = "memory" 表示 session 是临时的。 storage_url 会被解析为自定义存储元数据，但它本身不会创建本地 FileSessionStore。

AgentDir 中的配置

AgentDir 的 agent.acl 可以省略；省略时使用默认配置。存在时，AgentDir::load 会把它解析成 CodeConfig，并与 instructions.md、skills/、tools/、schedules/ 一起合成长期 Agent。

Text

release-agent/
├── instructions.md
├── agent.acl
├── skills/
├── tools/
└── schedules/

适合放在 AgentDir agent.acl 的内容包括该 Agent 默认模型、provider、运行限制、队列策略和私有 skill 目录。不要在这里硬编码部署环境差异；用环境变量或宿主注入区分开发、测试和生产。

配置边界

配置决定“可以连接什么”和“默认如何运行”，不决定“模型能越过权限门”。
目录路径应相对 workspace 或 AgentDir，避免依赖个人机器绝对路径。
自动委派需要和 agents/ 的描述质量一起调优；低质量 description 会让运行时错误分派。
高风险工具即使被目录发现，也应继续走 HITL 或 allow-list。

#agent.acl

#基础配置

#目录发现

#Session 存储

#AgentDir 中的配置

#配置边界

agent.acl

基础配置

目录发现

Session 存储

AgentDir 中的配置

配置边界