agent-exec: A Structured Task Runner Designed for AI Agent Workflows

agent-exec is a non-interactive task runner written in Rust, designed specifically for AI agent workflows. It runs commands as background jobs and returns results in a structured JSON format, solving common challenges AI agents face when executing external commands, such as output parsing, timeout control, and error handling. Key features include a default 10-second timeout mechanism, separation of stdout/stderr, persistent log storage, complete command lifecycle management (immediate/deferred execution, status query, termination control), etc., adhering to an agent-first design philosophy.

When AI agents execute external commands, traditional methods have many issues: inconsistent shell output formats requiring complex parsing, long tasks blocking sessions, error messages mixed in stderr, and manual implementation of timeout and signal handling. These problems consume a lot of context window resources and affect the operation of the agent's core logic—agent-exec was created precisely to address these pain points.

The core design of agent-exec revolves around reasonable default settings: a default 10-second timeout (to avoid session hijacking and quickly expose startup failures), stdout only outputs structured JSON (stderr is used for diagnostic logs), and persistent logs stored to files (responses include paths and summaries). The command lifecycle supports two modes: 1. Immediate execution (run): one-step process, returns JSON containing job_id, status, and output scope; 2. Deferred execution (create+start): define the task first then start it, suitable for batch scenarios. Additionally, it provides functions like status (query status), tail (stream output), wait (blocking wait), kill (terminate task), etc.

agent-exec provides fine-grained timeout and signal handling: supports hierarchical termination (e.g., --timeout 5 sends SIGTERM, --kill-after 2 sends SIGKILL). Environment management prioritizes security: --env sets variables, --env-file reads from files (to avoid sensitive information entering version control), and --mask hides sensitive parameters. When collaborating with shells, simple commands are executed directly; when shell features (pipes/redirection) are needed, explicitly wrap with a shell (e.g., sh -lc ...) to avoid injection risks.

agent-exec is suitable for automated workflows (CI/CD, scheduled tasks), AI agent integration (tool calling, code execution), long-running tasks (model training, data migration), and multi-step orchestration (deployment processes, test matrices). Technically, the Rust implementation ensures memory and concurrency safety, uses Result patterns for error handling, and the schema_version design ensures forward compatibility.

Compared with traditional tools, agent-exec is lightweight and focuses on single-task execution (different from systemd/supervisord's long-term service management), providing complete lifecycle management and structured output (superior to timeout/nohup). It fills the gap of a reliable task execution layer in the AI agent ecosystem and is a practical component for AI agent developers—Rust ensures performance and reliability, the concise JSON interface reduces integration complexity, and the agent-first design ensures practicality.