AgentSPEX: An Agent SPecification and EXecution Language
| Authors | Pengcheng Wang et al. |
| Year | 2026 |
| HF Upvotes | 156 |
| arXiv | 2604.13346 |
| Download | |
| HF Page | View on Hugging Face |
Abstract
Language-model agent systems commonly rely on reactive prompting, in which a single instruction guides the model through an open-ended sequence of reasoning and tool-use steps, leaving control flow and intermediate state implicit and making agent behavior potentially difficult to control. Orchestration frameworks such as LangGraph, DSPy, and CrewAI impose greater structure through explicit workflow definitions, but tightly couple workflow logic with Python, making agents difficult to maintain and modify. In this paper, we introduce AgentSPEX, an Agent SPecification and EXecution Language for specifying LLM-agent workflows with explicit control flow and modular structure, along with a customizable agent harness. AgentSPEX supports typed steps, branching and loops, parallel execution, reusable submodules, and explicit state management, and these workflows execute within an agent harness that provides tool access, a sandboxed virtual environment, and support for checkpointing, verification, and logging. Furthermore, we provide a visual editor with synchronized graph and workflow views for authoring and inspection. We include ready-to-use agents for deep research and scientific research, and we evaluate AgentSPEX on 7 benchmarks. Finally, we show through a user study that AgentSPEX provides a more interpretable and accessible workflow-authoring paradigm than a popular existing agent framework.
Engineering Breakdown
Plain English
AgentSPEX is a domain-specific language designed to address the control-flow problem in LLM-based agent systems. Current frameworks like LangGraph and CrewAI couple workflow logic tightly with Python code, making agents brittle and hard to modify when requirements change. The paper introduces a declarative specification language that separates agent workflow definitions from execution, supporting typed steps, branching, loops, and parallel execution with an explicit control flow model. This approach makes agent behavior more predictable and maintainable while reducing the coupling between business logic and implementation code.
Core Technical Contribution
The core novelty is a domain-specific language (DSL) that treats agent workflows as first-class declarative specifications rather than imperative Python code. AgentSPEX introduces explicit control flow primitives (branching, loops, parallel execution) and typed steps that can be formally reasoned about and validated before execution. The innovation bridges the gap between fully reactive prompting (where control flow is implicit and hidden) and tightly-coupled orchestration frameworks (where workflow logic is scattered across Python). This enables decoupling of workflow specification from execution harness, allowing the same agent specification to run on different execution engines without code changes.
How It Works
AgentSPEX defines agents through a declarative specification that includes typed step definitions, control flow edges, and execution constraints. When a workflow is specified, the language parser validates type compatibility between steps and checks for reachability and termination properties. During execution, the customizable agent harness interprets the specification, maintains execution state (current step, variable bindings, branch conditions), and routes control based on explicit branching and loop rules rather than implicit prompt interpretation. Steps are executed sequentially or in parallel depending on specification directives, with intermediate results propagated through a typed context that ensures data compatibility. The harness can swap underlying LLM components or modify execution strategies without requiring workflow redefinition—the specification remains decoupled from these implementation details.
Production Impact
For teams building agent systems, AgentSPEX eliminates the common pattern of rewriting entire Python orchestration code when agent workflows change. Instead of modifying Python and redeploying, teams can update the SPEX specification file and redeploy the agent harness (which remains stable). This dramatically reduces deployment friction and testing overhead—specification changes don't require Python code review or full integration testing of orchestration logic. However, adoption requires investment in learning the DSL syntax and building parsers/validators for your specific execution environment. The typed step model also prevents entire classes of runtime errors (type mismatches between step outputs and inputs) that would otherwise only surface in production, improving reliability for multi-step reasoning workflows.
Limitations and When Not to Use This
AgentSPEX assumes workflows can be specified declaratively upfront, which breaks down for truly emergent behaviors where the agent must dynamically discover new steps or modify its own workflow at runtime. The paper does not address how to handle long-running workflows that fail midway (checkpoint/resumption semantics are not discussed), which is critical for production systems processing expensive multi-step tasks. Validation and type-checking of the specification is straightforward, but reasoning about the correctness of the workflow logic itself (does this sequence of steps actually solve the user's problem?) still requires human validation. The abstraction also assumes step outputs are deterministic or at least consistent in structure—LLM outputs that vary in schema across runs could break the type system unless the harness includes schema repair mechanisms not mentioned in the abstract.
Research Context
This work builds on prior research in orchestration frameworks (LangGraph, DSPy, CrewAI) and domain-specific languages for workflow management (Airflow, Temporal), adapting proven concepts from workflow orchestration to the specific constraints of LLM agents. It addresses pain points identified in practice—that Python-based orchestration of agent steps is fragile and difficult to maintain at scale. The work opens a research direction around verification and optimization of agent specifications: can you statically analyze an AgentSPEX specification to prove properties like 'this workflow will eventually reach a terminal state' or 'this workflow minimizes token usage'? It also complements recent work on agent benchmarks (AgentBench, GAIA) by providing a standard format for specifying agent behaviors that could improve reproducibility and comparison across agent systems.
:::tip Subscribe Get weekly breakdowns of papers like this in AI Letters - the newsletter for engineers building production AI systems. :::