Concepts

Overview

Every agent platform eventually has to answer the same two questions: when something happens, who reacts? And how does the reaction run? ArchAgents answers them with a small, sturdy model you'll see in every page from here on.

1. When something happens, who reacts? An agent, or the project as a whole?
2. How does the reaction run? Built-in behavior, a script, or a multi-step workflow?

Everything else builds on those two answers. The same model works whether your agent stays inside one company or sits on a thread shared with a customer. The thread changes; the agent doesn't.

---

The reaction model

Events are the start

Something happens: a cron schedule fires, a message is added to a thread, a connector finishes indexing, an email arrives. These are events, and every reactive behavior on the platform begins with one. You can list the full event catalogue with:

archagent list events
archagent describe events <event-name>

Routines and automations are both event handlers

When an event fires, the platform dispatches to any registered handlers. Handlers come in two shapes:

• A routine lives on an agent. It says "when X happens, this agent reacts." Routines are how agents get ongoing behavior, replying in threads, running scheduled tasks, reacting to connector events.
• An automation lives on the project. It says "when X happens, the project reacts." Automations are how shared, project-wide jobs run, the daily digest, the ingestion retry, the cross-agent monitoring job.

Routines and automations are structurally similar, both match an event and dispatch a handler, but they differ in scope and identity. A routine is attributed to a specific agent and has access to that agent's tools, knowledge, memory, and skills. An automation is attributed to the project and does not belong to any one agent.

Which should you use? If the work is "this named agent reacts", use a routine. If the work is "the project as a whole reacts", use an automation. If it's neither, if it's a one-off manual task, use an agent session, not a handler.

Handlers dispatch to one of three types

Routines and automations both have a handler_type field that tells the platform how the reaction runs:

handler_type	What runs	When to pick this
preset	A built-in behavior the platform implements	You want standard agent behavior, participate (reply in a thread) or do_task (run an LLM session)
script	A single ArchAgents script expression	You need small, deterministic logic, routing, filtering, a short transformation
workflow_graph	A full workflow config with multiple nodes	You need multi-step work with branching, approvals, external calls, or retries

A script is the smallest unit of custom logic. A workflow is a graph of nodes, and one of the node types is a ScriptNode that runs a script. So a workflow can contain scripts, but a script on its own is just an expression, not a workflow. When a handler is workflow_graph, it runs the full graph; when it's script, it runs one expression.

Results go somewhere specific

Every handler run produces something. Where that something lives depends on the handler:

• Thread message: a participate preset routine posts the agent's reply directly into the thread the event came from. This is the only handler type that posts conversational responses.
• Run record: every handler run produces a durable record with status, inputs, outputs, and errors. Inspect with archagent list agentroutineruns --routine <id> or archagent list automationruns --automation <id>. The activity feed shows these in real time.
• Side effect: handlers can also trigger external actions: send Slack messages, post to webhooks, write files, open GitHub PRs, call MCP server tools. These happen inside the handler but leave records of what was attempted.

A common confusion: do_task is a preset that runs a full LLM session with all the agent's tools, but its output does not post to a thread, the result lives in the run record. If you want the agent to reply in a thread, use participate, not do_task. See Agents → Handler types for the full distinction.

---

The capability model

The reaction model above explains when an agent does work. This section explains what it can do.

An agent has three kinds of capabilities, and all three flow from the same upstream primitive: installations.

Capability	What it is	How it's attached
Tools	Actions the agent can call during an LLM session, search, knowledge_search, open_pr, MCP server tools, custom tools	Declared on the agent directly (builtin or custom) or provided by an installation (e.g. GitHub App tools)
Knowledge	Information the agent can retrieve at query time, indexed files, repositories, websites, threads	Connected via an installation, then exposed as a knowledge source the agent can search
Memory	Facts the agent retains across sessions	Enabled via an installation (memory/long-term)

An installation is the attachment point. One installation can enable several capabilities at once. Installing a GitHub App, for example, gives the agent:

• the GitHub builtin tools (open PR, comment on issue, read file)
• GitHub repositories as knowledge sources
• a scoped token the platform manages for the agent

The reason this matters: when something isn't working, the first place to look is the installation's status, not the individual tool or knowledge source downstream of it. archagent list agentinstallations --agent <id> shows the health of the whole capability chain at once.

See Installations, Tools, and Knowledge for each layer in detail.

---

The five words you will see most

If you only read one section of this page, read this one. Here are the five words that appear throughout the rest of the docs and what they mean in one line each:

• Agent: a persistent AI worker with a name, instructions, tools, knowledge, and memory. See Agents.
• Routine: an event handler that lives on one agent. See Agents → Routines.
• Automation: an event handler that lives on the project. See Automations.
• Workflow: a reusable multi-step config referenced by a routine or automation as a workflow_graph handler. See Workflows.
• Config: the file-backed, version-controllable representation of any of the above. See Configs.

Every other concept (skills, scripts, tools, knowledge sources, installations, structured output, field guards) either composes into one of those five or is a building block one of them uses.

---

Where to go next

1. Agents: the full agent model and routine lifecycle.
2. Automations: project-wide reactions and scheduled work.
3. Workflows: multi-step process graphs.
4. Scripts: the smallest unit of custom logic.
5. Tools and Knowledge, what an agent can do and what it can know.
6. Installations: the attachment point that enables tools and knowledge.