atac 0.4.7

Recording and Replay AI Agent Trajectory.

English | 中文

中文

ATaC (Agentic Trajectory as Code) 提供了一套专为 AI Agent 设计的声明式轨迹录制与回放接口。通过 ATaC，开发者能将智能体运行时的动态调用流，固化为可流转、可复用、可精确重构的静态代码资产。

🛠 核心能力

• 轨迹录制: 将智能体非结构化的工具调用历史，持久化为标准化的静态 .yaml 资产。
• 精确回放: 搭载轻量化执行引擎，按序、精确还原复杂环境下的工具执行序列。
• 声明式控制流: 在 YAML 轨迹中原生支持循环 (for) 和条件 (if-else) 逻辑编排。
• 多协议总线: 统一调度 mcp:// (Model Context Protocol)、bash:// 等多源执行环境。
• Agent Memory: 将 AI 解决过的任务模式以目录 bundle 形式持久化，入口为 index.yaml，并支持附带脚本与按关键词检索，用于引导后续任务。

📋 执行器兼容性

执行器	协议	状态	说明
MCP	mcp://	✅ 已支持	原生支持所有标准 MCP 服务
Bash	bash://	✅ 已支持	支持本地终端命令及脚本执行
Claude Code	claude://	🚧 规划中	待集成内置工具集

🤖 自主构建与流转示例

1. 自动化构建 (CLI)

Agent 可以通过以下指令序列自主生成 GeoSearch 工作区轨迹：

# 1. 初始化并定义输入变量 (自动创建 .atac/GeoSearch 目录结构)
atac init GeoSearch --description "GeoSearch workflow"
atac add-input GeoSearch --name provinces --type list

# 2. 注入逻辑结构 (For 循环)
atac add-for GeoSearch --in '${inputs.provinces}' --item province

# 3. 在指定位置插入动作 (支持路径寻址)
atac add-action GeoSearch --at 0 --id geo --action "mcp://amap/maps_geo" --args '{"address": "${variables.province}"}'

# 4. 预览生成的结构
atac show GeoSearch

2. 嵌套轨迹调用 (Sub-Workflows)

ATaC 原生支持通过 bash://run 调用其它 ATaC 文件，从而实现模块化与依赖复用：

# 在 parent 轨迹的 index.yaml 中
steps:
  - id: call_sub
    type: action
    action: bash://run
    args:
      command: atac run child_workspace --input city="Beijing"

🚀 快速开始

1. 安装与环境配置

uv tool install atac  # 极简模式（推荐）

# 挂载您的任意外部 MCP 服务器环境配置：
# 方式一：使用 atac config (推荐，项目级配置最高优先级)
atac config mcp_config=path/to/mcp_config_1.json mcp_config=path/to/mcp_config_2.json

# 方式二：使用环境变量 (全局生效)
export ATAC_MCP_SERVER_CONFIGS="path/to/mcp_config_1.json,path/to/mcp_config_2.json"

[!NOTE] atac config 命令生成的 .atac/atac.json 具有最高优先级，加载时会覆盖同名的环境变量。

2. 以 Skills 形式引入

将项目中的 skills/atac 目录复制到您 Agent 工作区的 skills/ 目录下即可激活：

cp -r path/to/ATaC/skills/atac ./skills/

3. 以 MCP Server 形式引入

在支持 MCP 协议的应用程序配置中添加 ATaC：

{
  "mcpServers": {
    "atac": {
      "command": "uvx",
      "args": ["atac", "mcp"],
      "env": {
        "ATAC_MCP_SERVER_CONFIGS": "path/to/mcp_config_1.json,path/to/mcp_config_2.json"
      }
    },
    "atac-memory": {
      "command": "uvx",
      "args": ["atac", "memory-mcp", "--memory-dir", "/path/to/memory"]
    }
  }
}

memory-mcp also exposes memory_run_command(memory_name, command, args) for running a relative executable path inside a memory bundle directory.

4. ATaC Memory — Agent 记忆模块

ATaC Memory 将 AI 执行过的任务模式保存为目录 bundle，入口文件固定为 .atac/.memory/<name>/index.yaml，目录内可附带脚本与其他资产，供后续任务检索复用：

.atac/.memory/analyze_regional_sales/
├── index.yaml
└── scripts/
    └── helper.py

# 搜索相关历史经验
atac memory search 节假日 销售 分析

# 任务完成后从 YAML/JSON 定义生成 bundle
atac memory save ./my_solution.yaml

# 或直接导入一个现成的 memory bundle 目录
atac memory save ./my_memory_bundle

# 下次任务前读取参考
atac memory read analyze_regional_sales

# 启动独立 memory MCP，并显式指定记忆目录
atac memory-mcp --memory-dir /path/to/memory

将 skills/atac-memory 复制到 Agent 工作区的 skills/ 目录以激活：

cp -r path/to/ATaC/skills/atac-memory ./skills/

---

English

ATaC (Agentic Trajectory as Code) provides a set of declarative trajectory recording and replay interfaces tailored specifically for AI Agents. Through ATaC, developers can persist an agent's dynamic execution flow into modular, reusable, and deterministic static code assets.

🛠 Key Features

• Trajectory Recording: Persists unstructured agent tool invocations into standardized, static .yaml assets.
• Precise Replay: Powered by a lightweight runtime engine to predictably execute complex tool sequences.
• Declarative Control Flow: Native for loop and if-else condition routing directly within the YAML schema.
• Multi-protocol Bus: Unified execution pipeline bridging mcp://, bash://, and various platform APIs.
• Agent Memory: Persist solved task patterns as searchable directory bundles with an index.yaml entry and optional helper scripts, giving agents reusable guidance for future tasks.

📋 Executor Support

Executor	Scheme	Status	Note
MCP	mcp://	✅ Supported	Native support for all MCP servers
Bash	bash://	✅ Supported	Local shell commands and scripts
Claude Code	claude://	🚧 Roadmap	Built-in tool integration pending

🤖 Authoring & Workflow Examples

1. Authoring Flow (CLI)

Agents can generate a GeoSearch trajectory workspace via direct CLI commands:

# Create a new workspace at .atac/GeoSearch
atac init GeoSearch --description "GeoSearch workflow"
atac add-input GeoSearch --name provinces --type list
atac add-for GeoSearch --in '${inputs.provinces}' --item province
atac add-action GeoSearch --at 0 --id geo --action "mcp://amap/maps_geo" --args '{"address": "${variables.province}"}'

2. Nested Trajectories (Sub-Workflows)

ATaC supports executing other ATaC files natively via the bash://run executor, allowing you to build modular, reusable sub-workflows:

# Inside parent workspace's index.yaml
steps:
  - id: call_sub
    type: action
    action: bash://run
    args:
      command: atac run child_workspace --input city="Beijing"

🚀 Quick Start

1. Installation & Environment Setup

uv tool install atac  # Minimalist mode (Recommended)

# Mount your external MCP server environment configurations:
# Method 1: Using atac config (Recommended, highest priority for project level)
atac config mcp_config=path/to/mcp_config_1.json mcp_config=path/to/mcp_config_2.json

# Method 2: Using Environment Variables (Global level)
export ATAC_MCP_SERVER_CONFIGS="path/to/mcp_config_1.json,path/to/mcp_config_2.json"

[!NOTE] The .atac/atac.json file generated by atac config has the highest priority and will override the environment variable during context loading.

2. Introduce as Skills

Copy the skills/atac directory from this repository into your Agent workspace's skills/ directory:

cp -r path/to/ATaC/skills/atac ./skills/

3. Introduce as an MCP Server

Add ATaC to the configuration of any MCP-compatible application:

{
  "mcpServers": {
    "atac": {
      "command": "uvx",
      "args": ["atac", "mcp"],
      "env": {
        "ATAC_MCP_SERVER_CONFIGS": "path/to/mcp_config_1.json,path/to/mcp_config_2.json"
      }
    },
    "atac-memory": {
      "command": "uvx",
      "args": ["atac", "memory-mcp", "--memory-dir", "/path/to/memory"]
    }
  }
}

memory-mcp also exposes memory_run_command(memory_name, command, args) for running a relative executable path inside a memory bundle directory.

4. ATaC Memory — Agent Memory Module

ATaC Memory stores solved task patterns as directory bundles. Each bundle lives at .atac/.memory/<name>/index.yaml and can include helper scripts or other local assets:

.atac/.memory/analyze_regional_sales/
├── index.yaml
└── scripts/
    └── helper.py

# Search for relevant past experience
atac memory search ranking analytics

# Generate a bundle from a YAML/JSON definition file
atac memory save ./my_solution.yaml

# Or import an existing memory bundle directory
atac memory save ./my_memory_bundle

# Read the pattern before starting a similar task
atac memory read analyze_regional_sales

# Start the standalone memory MCP with an explicit memory directory
atac memory-mcp --memory-dir /path/to/memory

Copy skills/atac-memory to your Agent workspace's skills/ directory to activate:

cp -r path/to/ATaC/skills/atac-memory ./skills/

License

MIT