Concepts | ArchAgents Docs

Overview

You already have a Forward Deployed Agent in your workspace. To customize it (or to build new agents) you'll see five words a lot: agent, routine, automation, workflow, config. This page explains each one and how they connect.

If you haven't met the FDA model yet, read Forward Deployed Agent first. The rest of this page assumes you have.

The five words

Word	One-line definition
Agent	A named AI worker with instructions, attached tools, and knowledge. Your FDA is one.
Routine	A rule on an agent: "when X happens in a thread, this agent reacts."
Automation	A rule on the workspace: "when X happens, run this job." Not tied to any one agent.
Workflow	A multi-step graph (branches, approvals, retries) that a routine or automation can call.
Config	The text file representing any of the above. Version-controllable, deployable.

Everything else (skills, scripts, tools, knowledge, installations, field guards, structured output) plugs into one of these five.

When something happens, who reacts?

Two answers, and they decide everything else:

An agent reacts. Attach a routine to that agent. The agent's tools, knowledge, and memory are available to the handler. The reaction is attributed to the agent.
The workspace reacts. Create an automation. No single agent owns it. Use this for scheduled work, ingestion retries, cross-agent monitoring, anything that doesn't belong to one named agent.

If the work isn't "react to an event" at all (it's a one-off thing you want to run by hand), don't use either. Use an agent session instead.

Events are the triggers

A routine or automation reacts to an event. Examples:

A message lands in a thread (thread.message_added).
A scheduled automation fires (workflow.scheduled).
A knowledge ingestion finishes (context.ingestion.succeeded).
An inbound email arrives (email.received).
A teammate joins a team (team.member_joined).

List every event the platform exposes:

archagent list events
archagent describe events <event-name>

How does the reaction run?

Every routine and automation has a handler_type field. Four choices:

`handler_type`	What runs	Pick when
`preset`	One of the four built-in handlers: `participate`, `send_message`, `do_task`, `auto_memory_capture` (covered below).	You want standard agent behavior.
`script`	One ArchAgents script expression.	Small, deterministic logic: routing, filtering, a transformation.
`workflow_graph`	A full workflow: multiple nodes, branching, approvals, external calls.	The work has several steps or needs human approval.
`chain`	A linear sequence of steps. Each step is itself a `preset`, `script`, or `workflow_graph`.	You want two or three handlers to run in order, output of one feeding the next, without authoring a full workflow graph.

The four presets

Preset	What it does	Trigger events
`participate`	Joins a chat-room session and replies turn-by-turn as the agent.	`thread.session.join`
`send_message`	Sends one message in response to an event.	`thread.created`, `thread.member_joined`, `schedule.cron` (via the routine's own schedule), `agentroutine.invoked`
`do_task`	Runs a focused LLM task with the agent's full tool set. Output goes into the run record, not the thread.	Any event (`"*"`)
`auto_memory_capture`	Extracts and stores key facts from sessions for long-term memory.	`thread.session.leave`, `agent_session.completed`

do_task runs the agent but does not post a message to the thread. Its output goes into the run record. To reply in the thread, pick participate for a live turn-by-turn session or send_message for a one-shot reply on a specific event.

A script can live inside a workflow (one of the node types is a script node), and a chain can mix presets, scripts, and workflows step by step. A script on its own is one expression, not a workflow or chain.

Where the result goes

Every handler run produces one or more of:

A thread message: only participate posts back to the thread the event came from.
A run record: every handler creates one, with status, inputs, outputs, and any errors. Inspect with archagent list agentroutineruns --routine <id> or archagent list automationruns --automation <id>. The Activity Feed shows these in real time.
A side effect: handlers can call external systems: Slack, GitHub, webhooks, MCP server tools. The call is recorded on the run.

When a handler "doesn't work," the run record is the first place to look.

What an agent can actually do

A routine handler runs in the context of an agent. The agent gets three kinds of capability:

Capability	What it is
Tools	Things the agent can call during an LLM session. Web search, knowledge search, "open a PR," "post in Slack," your custom tools, any MCP server tool.
Knowledge	What the agent can look up. Indexed files, repositories, websites, prior threads.
Memory	What the agent remembers between sessions. Working memory inside a session, long-term memory across them.

All three flow through installations. An installation is the attachment between an agent and an outside system (a GitHub App, a Slack workspace, a custom integration, a memory provider). One installation can enable several capabilities at once. The GitHub App installation, for example, gives the agent its GitHub tools AND repository knowledge AND a managed token.

When a tool or knowledge source isn't behaving, look at the installation first:

archagent list agentinstallations --agent <id>

The whole capability chain's status shows there in one view.

See Tools, Knowledge, Installations for the full layers.

Configs: the source-of-truth file

Every agent, routine, automation, and workflow has a config representation. A config is a YAML file with a kind: and a body. You can:

Author it in your coding tool (the FDA's own Onboarding skill knows how).
Edit it in Designer.
Edit it directly in your repo and archagent deploy it.

Configs are how you version-control your ArchAgents setup. See Configs for the file format and lifecycle.

Where to go next

Agents: the full agent model, routine lifecycle, and participate vs do_task.
Automations: the workspace-level reactor.
Workflows: multi-step graphs.
Scripts: the smallest unit of custom logic.
Tools, Knowledge, Installations: what an agent can do, what it can know, and how that gets attached.

Help us make this page even more useful.