agents-exe
A handy LLM-agent tool, with a variety of calling and configuration modes so that the LLM adapts to your workflow rather than the opposite. An agent is a JSON file: an LLM endpoint and model, a system prompt, a directory of command-line tools, MCP servers, and helper agents it can prompt in turn. The same agent runs as a one-shot command, in a terminal UI, as an MCP server, or behind an HTTP server that keeps sessions across restarts.
agents-exe init # write an agent.json and its tools directory
agents-exe run --agent-file agent.json --prompt "Hello!" # one shot
agents-exe tui --agent-file agent.json # interactive terminal UI
agents-exe serve --agent-file agent.json # sessions over HTTP, durable, with a chat page
agents-exe mcp-server --agent-file agent.json # every agent as an MCP tool
Tools are plain executables that describe themselves, MCP servers, or OpenAPI operations; helper agents are exposed to the model as functions the same way, so a root agent delegates to specialised ones and their results come back as tool results. Sessions are durable: a run can stop on a tool call that needs an external answer, a background call, or a message from another agent, and be resumed later, in the same process or another one.
The code is on GitHub at
lucasdicioccio/agents-exe.
It is a Haskell cabal project: the agents library, the agents-exe and
agents-server executables, and agq, a small query tool over stored
sessions.
See it work
One prompt, four agents: a front desk asks three helpers in the same turn,
each runs a tool of its own, and agents-exe spectate shows the sessions
while they work. An unedited capture, from a run on a laptop against a
local model:
┌────────────────── agents ─────────────────┐┌──────────── text: librarian (following) ────────────┐
│* repo-tour-desk 90669359 running 1m46s ││ │
│ - historian 326ce547 returned 18s ││ │
│ * code-counter 401bf8a5 running 1m07s ││ │
│ * librarian fae942c5 running 1m07s ││ │
│ ││ │
│ ││ │
│ ││ │
│ ││ │
│ ││ │
│ ││ │
│ ││ │
│ ││ │
└───────────────────────────────────────────┘│ │
┌──────────────── tool calls ───────────────┐│ │
│* io_prompt_agent_code-counter repo-tour-d││ │
│* io_prompt_agent_librarian repo-tour-desk││ │
│- io_prompt_agent_historian repo-tour-desk││ │
│ ││ │
│ ││ │
│ ││ │
│ ││ │
└───────────────────────────────────────────┘└─────────────────────────────────────────────────────┘
http://localhost:8765 | 3/4 sessions running | 2 tool calls | 27 events | up/down select, f follow,
The demo has the rest of the run and the commands to reproduce it. How agents-exe compares places it next to LangGraph, AutoGen, the OpenAI Agents SDK, the Claude Agent SDK and CrewAI.
The terminal UI
agents-exe tui is the interactive mode: pick an agent, hold several
conversations at once, read each session turn by turn, and answer the tool
calls a run is waiting on. The screenshot is produced by the end-to-end
tests, which drive the real binary in a pseudo-terminal against a scripted
model. The TUI guide has the keys and the other views.
How it fits together
The interfaces are thin: the terminal UI and the HTTP server are both clients of one session runner, while the one-shot, MCP and inspection commands go straight to the agent tree. Everything below the tree (sessions, tools, LLM endpoints) is shared, so an agent behaves the same in each mode.
Explore
- The demo: a root agent and three helpers at work, recorded, with the commands to run it.
- How agents-exe compares: what it is and is not, next to five other agent frameworks.
- Getting started: build it, write a first agent, store an API key, and run it in each mode.
- Architecture: the layers, the OS model underneath (entities, resources, conversations), and where a session lives.
- Command reference: the global options and every
agents-execommand, one entry each. - Tools and executable tools: how a program describes itself to the agent, and how MCP servers and OpenAPI documents become tools.
- Parameters, bindings and narrowing: pre-bind tool arguments, declare parameters an operator or a client supplies, and hand a narrowed helper to a sub-agent.
- agents-server: agents over HTTP, durable sessions, event streams, the chat page, MCP over HTTP.
- Sessions and asynchronous tool calls: turns, deferred and background calls, resuming.
- The TUI: the terminal UI, its keys and its views.
- Docs and Specs: every guide and reference, and the design documents with what of each has shipped.