English | 中文

Agent CLI Framework is a revolutionary, CLI-First orchestration and packaging tool for modern AI Agents. It transforms Python scripts (like LangChain or CrewAI agents) into production-ready, standardized, and orchestratable Command Line Interfaces (CLIs).

1. CLI-First Architecture: Run agents synchronously (run) or as background daemon processes (start). Perfect for long-running multi-agent tasks.
2. Native Observability: Poll status (status) and tail thought logs (logs) of background agents without blocking your main process.
3. Standalone Package Compiler: Use agent-cli package to dynamically generate a fully independent Python package (your-agent-cli) out of a simple YAML config.
4. Single-File Binary Compilation: Use --binary to bundle the entire agent and its dependencies (like LangChain) into a standalone executable using PyInstaller. Zero Python environment required for end users!
5. LLM-Oriented Design: Automatically generates SKILL.md for Claude Code. Throws structured JSON errors with actionable resolutions when run non-interactively (perfect for AI self-healing).
6. Interactive Secret Management: Securely prompt and save API keys (e.g., GEMINI_API_KEY) to a local .env vault (~/.agent-cli/<cli-name>/.env).

git clone https://github.com/Raygooo/agent_cli.git
cd agent_cli
pip install -e .

1. Create a config file (agent.yaml)

name: "cooking-agent"
framework: "custom" # or "langchain", "crewai"
entrypoint: "agent:run_agent"

arguments:
  cook:
    type: string
    required: true
  spicy:
    type: boolean
    default: false

required_envs:
  - OPENAI_API_KEY

2. Run locally with Agent CLI

# Foreground synchronous run
agent-cli run -c agent.yaml --cook "Pizza" --spicy

# Background asynchronous run (Daemon)
JOB_ID=$(agent-cli start -c agent.yaml --cook "Pizza")
agent-cli logs $JOB_ID --follow

3. Compile into a standalone CLI and Binary

# Generates a standalone Python package in dist/cooking-agent-cli
agent-cli package -c agent.yaml

# Or compile into a zero-dependency binary executable!
agent-cli package -c agent.yaml --binary

# --binary now builds inside an isolated uv-managed virtual environment
# before invoking PyInstaller.

# Now you can distribute it and users can just run:
./dist/bin/cooking-agent-cli run "Pizza"

Agent CLI Framework 是一个革命性的、以 CLI 为核心的 AI Agent 编排与打包框架。它可以将你编写的 Python 脚本（如 LangChain 或 CrewAI Agent）一键转化为生产可用、标准化且高度可被大模型（如 Claude Code）编排的命令行工具。

1. CLI-First 架构：支持前台同步执行（run）和后台守护进程异步执行（start）。完美解决复杂多 Agent 任务耗时长、易断连的痛点。
2. 原生可观测性：随时随地轮询后台任务状态（status），或者像 tail -f 一样实时追踪底层 Agent 的思考日志（logs）。
3. 独立包编译器：使用 agent-cli package，只需提供一份极简的 YAML 配置，即可动态生成一个完全独立的 Python CLI 安装包（带有专属的业务指令如 --cook）。
4. 单文件二进制编译：通过附加 --binary 参数，底层会自动调用 PyInstaller 将你的 Agent（连同庞大的 LangChain 等依赖）打包成一个绿色的单文件可执行程序。最终用户即使不安装 Python 也能双击运行！
5. 面向 LLM 设计 (LLM-Oriented)：一键为 Claude Code 等主编排器生成 SKILL.md 操作指南。在被脚本或 AI 非交互式调用时，遇到错误（如缺少 API Key）会抛出带有自我修复建议的结构化 JSON，便于 AI 自动纠错。
6. 交互式安全凭证管理：内置 env 指令。首次运行缺少 API Key 时，会通过密码框安全提示用户输入，并持久化保存在本地私有目录（~/.agent-cli/<cli-name>/.env）中。

git clone https://github.com/Raygooo/agent_cli.git
cd agent_cli
pip install -e .

1. 编写配置文件 (agent.yaml)

name: "cooking-agent"
framework: "custom" # 支持 "langchain" 或 "crewai"
entrypoint: "agent:run_agent"

arguments:
  cook: # 自动映射为 CLI 参数
    type: string
    required: true
  spicy:
    type: boolean
    default: false

required_envs:
  - OPENAI_API_KEY

2. 使用 Agent CLI 运行测试

# 前台同步运行
agent-cli run -c agent.yaml --cook "番茄炒蛋" --spicy

# 后台异步运行（守护进程模式）
JOB_ID=$(agent-cli start -c agent.yaml --cook "番茄炒蛋")
agent-cli logs $JOB_ID --follow

3. 编译发布为独立的 CLI 工具与二进制文件

# 在 dist/cooking-agent-cli 生成标准的 Python Package 项目
agent-cli package -c agent.yaml

# 或者直接编译成零环境依赖的可执行二进制程序！
agent-cli package -c agent.yaml --binary

# --binary 现在会先使用 uv 创建隔离虚拟环境，再调用 PyInstaller。

# 现在，你可以将程序分发给任何人，他们只需要执行：
./dist/bin/cooking-agent-cli run "番茄炒蛋"

Built for the next generation of AI orchestration. See ROADMAP.md for future explorations.