gptel agentic framework based around state machines

Posted on August 22, 2026 by Ivan Dimitrov

### I want to make a framework that uses gptel presets as one-to-many agents in an LLM map tasked with solving a subproblem of the main goal. How should one go about implementing a framework that has different buffers one for each agent that coordinate between each other and follow a state machine until a goal is reached

Don’t start with code. First, clarify concepts and requirements:

  • Agent Model: Decide how you define agents (GPTel presets = prompt + context). What counts as a “subproblem”? What state do agents hold?
  • Coordination: How will agents communicate—via buffers, messages, shared state?
  • State Machine: What states must agents move through? Who coordinates transitions—the framework or the agents?
  • Termination: How is “goal reached” formally determined?

Recommended approach:

  1. Design the State Machine:
    • Enumerate all possible agent states (Idle, Waiting, Running, Completed, etc.).
    • Define messages/steps for coordination and completion.
  2. Agent/Buffer Model:
    • Each buffer is an interaction store for one agent.
    • Buffers can be indirect—use hash tables keyed by agent name if you want quick lookup.
  3. Coordination Mechanism:
    • Implement a main controller (“orchestrator”) Emacs Lisp object (or a buffer-mode) to:
      • Track all agents/states.
      • Route messages/results to and from each agent buffer.
      • Progress state machine per agent, and globally.
    • Use hooks or custom events on message arrival/progress.
  4. Agent Execution:
    • When an agent is ready, send its buffer contents + prompt to GPTel.
    • When result arrives, parse result, update state, trigger next action.
  5. Synchronization:
    • On agent completion, notify orchestrator.
    • Orchestrator checks dependencies. If all subproblem agents finish, continue/main goal agent runs.
  6. Buffer Management:
    • Create one major-mode buffer per agent, named predictably (“llm-agent-foo”).
    • Optionally, keep all state in a single orchestrator structure with buffer references.

Implementation sketch:

  • Use an orchestrator object (list or struct). Each agent entry holds:
    • Preset (prompt)
    • Buffer
    • Current state
    • Upstream/downstream dependencies (if any)
  • Functions:
    • `llm-framework-start`: spawns all agent buffers, initializes state machine.
    • `llm-framework-handle-response`: called when an agent’s response is ready.
    • `llm-framework-advance`: orchestrator checks and moves agents to their next state, routes info, triggers requests.
  • Keep all agent (buffer <-> state) mappings in one orchestrator variable or buffer-local structure.
  • Try not to use complex concurrency—use simple Emacs hooks/callbacks per agent.

Alternatives:

  • If pure buffer-per-agent is too heavy, use indirect buffers or overlays, but separating by buffer is idiomatic and simple.
  • Consider starting with a proof of concept using just two agents with a simple dependency and extend.

TL;DR: Design agent models, state machine, orchestrator. Each agent gets a buffer. The orchestrator tracks state, routes messages, and advances the state machine based on agent outputs. Don’t overcomplicate—test basic coordination and single-step transitions first.

### ok please consider the current working directory and make an org file inside that breaks down the design of this framework in tasks with documentation. Name the file index.org

``` tool (Write :content “* LLM Agent Framework Design and Task Breakdown ** Overview A framework to coordinate multiple …) (:name”Write" :args (:content “* LLM Agent Framework Design and Task Breakdown

Overview

A framework to coordinate multiple GPTel preset-based agents, each assigned a subproblem of a main goal. Each agent runs in its own buffer and agents coordinate by following a defined state machine until the main goal is achieved.

Goals

  • Modularity: Easy to define, add, and remove agents.
  • Coordination: Agents communicate results and triggers.
  • Transparency: Each agent’s state and buffer visible.
  • Deterministic Completion: The orchestrator knows when the main goal is achieved.

Components

  • Orchestrator: Controls agents, state, and messaging.
  • Agents: Encapsulated GPTel presets + buffers.
  • State Machine: Defines agent states and transitions.
  • Buffers: One per agent, storing context and logs.

Implementation Tasks

Define Agent Data Model

  • Document required fields (preset, buffer, state, dependencies, etc).
  • Decide on struct/list/object for in-memory representation.

Design Global Orchestrator

  • Orchestrator holds agent list and state.
  • Functions for initializing, updating, and finishing workflows.
  • Plan hooks/callbacks for response arrival and step advancement.

Specify State Machine

  • Enumerate agent states (Idle, Submitted, Waiting, Running, Completed, Error).
  • Draft allowed transitions and state diagrams.
  • Define transition triggers (incoming data, dependencies, timers).

Agent Buffer Integration

  • Create buffers named after agent roles (e.g., llm-agent-research).
  • Write functions to initialize and update buffers.
  • Connect buffers to orchestrator state.

Agent Lifecycle and Execution

  • Implement agent task initiation: send context/prompt to GPTel.
  • Handle output: parse, store in buffer, notify orchestrator.
  • Document interface between orchestrator and agent buffers.

Agent Coordination

  • Implement message passing or result handoff between agents (via orchestrator).
  • Document how dependencies are tracked and checked.

Goal/Termination Conditions

  • Formalize how orchestrator knows when main goal is achieved.
  • Plan for error handling and recovery.

User Interaction and Monitoring

  • Optional: Provide ways to inspect or steer agent buffers and state.

Example Use Case (Documented)

  1. User defines a main problem and subproblems mapped to agents.
  2. Each agent buffer is created and initialized with its GPTel preset.
  3. Orchestrator triggers agents based on dependencies.
  4. Agent finishes a task, writes output to its buffer.
  5. Orchestrator advances state, possibly triggering downstream agents.
  6. When all requirements met, orchestrator marks goal as completed.

Future Enhancements

  • Parallel agent execution (async triggers)
  • Visualizations of agent progress and states
  • Dynamic agent creation/removal during workflow

" :filename “index.org” :path “.”))

Created file index.org in . ``` index.org has been created in your current directory. It documents the framework design and breaks it into tasks as requested.

###

<!– Local Variables: –> <!– gptel–preset: gptel-agent –> <!– gptel-model: gpt-4.1 –> <!– gptel–backend-name: “Copilot” –> <!– gptel–bounds: ((tool (3724 6612 “callK0X3eSLpAYrEGGiO7a6sk6ox”)) (ignore (3598 3724) (6612 6617)) (response (494 3414) (6617 6743))) –> <!– End: –>