Core concepts
The handful of ideas that everything else builds on.
Agents
An agent is a configured persona: a soul (who it is), instructions(how it works), a default model, and an allow/deny list of skills it may use. Agents live under ~/parley/agents/<name> and are edited in the console — the built-in Parley assistant can even co-author a soul or instructions with you.
Sessions
A session is one running conversation/task for an agent. Sessions are durable and restart-safe: work that's waiting on something parks and wakes when the answer arrives, rather than blocking. Each session moves through a small state machine:
| State | Meaning |
|---|---|
Running | Actively executing a turn. |
Idle | Yielded with open todos still to do. |
Dormant | Yielded with nothing pending. |
AwaitingHuman | Parked on an ask_user question. |
AwaitingPeer | Parked on a reply from another agent. |
AwaitingApproval | Parked on a human approval (e.g. a shell command). |
Done | The task is complete. |
Todos
Each session has a built-in todo list. Open todos drive a wake loop that re-enters the session on its own until the work is done, so one request can become a multi-step job the agent completes without prodding. See Todos & the wake loop.
Crews & inter-agent communication
The differentiator. Agents don't just run in isolation — they form crews and communicate over a first-class messaging layer:
- Subagents. An agent can spawn a child session to take on part of a task, concurrently, and get the result back.
- Named delegation. Delegate to another configured expert agent by name.
- Peer consults. Ask another agent a question mid-task and get an answer — modeled as a park-and-resume so it never blocks the worker or holds a lock.
- Messaging. Agents send messages and replies to peers and humans across channels, with routing and provenance recorded.
Channels
A channel connects an agent to the outside world — Telegram out of the box, more via plugins. Inbound messages are matched to a session by a sticky (instance, conversation)binding, so a human stays in one continuous thread. Channel access is default-deny: a sender must be on the agent's allowlist. How a conversation stays bound to one session — and how background tasks reach a human in the right thread — is covered in Channel ownership.
Missions (cron)
Standing, long-running work runs on a schedule. A cron entry fires a prompt into a fresh or reused session on a cadence — "every 15 minutes, check the queues and parley the crew if depth is over 10k." Schedules are drift-free and survive restarts.
Memory & the wiki
Agents recall relevant memories via embedding search, and a crew shares a human-readable wiki (git-backed markdown by default) so knowledge compounds instead of resetting each run.
Compaction
When a session's context approaches the model's window, AgentParley compacts: it keeps recent turns verbatim and summarizes the older prefix into a structured brief (goal, progress, decisions, next steps) plus a read/modified-file manifest. The raw log is never destroyed — only the working context is rewritten. The summarizer itself is a selectable provider.