archagent-concepts

name	archagent-concepts
description	Canonical one-line reference for every ArchAgents concept — AgentTemplate, Agent, Thread, Routine, Automation, Script, Workflow, Skill, Installation, Tool, Config. Use when the customer asks "what is an X", "what's the difference between X and Y", "do I need an automation or a routine", or when you need to ground a design discussion in the platform's vocabulary.

ArchAgents Concept Map

Every ArchAstro support conversation eventually hits a concept question. Answer it with the platform's real vocabulary, not your own paraphrase. When you are unsure, link the customer to the canonical doc (see the archagent-docs-map skill) rather than inventing a definition.

Primary nouns

AgentTemplate

A YAML file with kind: AgentTemplate that declaratively defines an agent's identity, tools, routines, and installations. Version-controlled in git. Deployed with archagent deploy agent <file>.yaml. The source of truth for what an agent is.

Agent

A deployed, persistent AI worker created from an AgentTemplate. Has a name, identity prompt, tools, knowledge, memory, and routines. Lives on the ArchAgents platform and is addressable across threads, webhooks, schedules, and API calls.

Thread

A persistent conversation where human users, system users, and agents exchange messages over time. Supports multiple participants and cross-company collaboration. Agents join threads via thread.session.join routines and leave via thread.session.leave.

Routine

An agent-scoped event handler. Attached to a specific agent; fires when a matching event (schedule.cron, webhook.*, thread.session.join, etc.) occurs. Routines are the primary way an agent reacts to the world.

Automation

A project-scoped event handler. Same event-and-handler shape as a routine, but not tied to a single agent. Use for project-wide jobs (e.g., a webhook that fans out to multiple agents).

Script

The smallest unit of custom logic. A functional, expression-oriented language (no loops, no return statement) authored in .aascript files. Used as a tool handler, a workflow node handler, or a routine handler. Authoritative syntax: archagent describe scriptdocs.

Workflow

A directed JSON graph of nodes (WorkflowGraph kind) referenced by a routine when a handler needs branching, approvals, retries, or multi-step state. Prefer a routine + single script for simple handlers; reach for a workflow only when you need structure.

Skill

A file-backed instruction bundle anchored by a SKILL.md file with optional supporting files. Agents invoke skills at runtime via the get_skill tool (listed as skills in the tool catalog). Use skills to keep identity prompts small and load detailed playbooks on demand.

Installation

The attachment point that enables tools, knowledge sources, and memory on an agent in one step. Installing the GitHub App installation, for example, grants GitHub-flavored tools and a scoped token. Common installations:

• memory/long-term — persistent facts across sessions
• archastro/thread — live in threads
• archastro/files — ingest files as searchable knowledge
• integration/github — GitHub App tools and webhooks

Tool

An action the agent can call during an LLM session. Three kinds:

• Builtin — search, knowledge_search, long_term_memory, open_pr, skills, etc. Declared as kind: builtin.
• Custom (script) — kind: custom, handler_type: script, config_ref: <script-slug>. Backed by a Script config.
• MCP — tools exposed by an attached MCP server.

Config

The file-backed, version-controllable representation of any platform resource: AgentTemplate, Script, WorkflowGraph, Skill, File, etc. Managed via a local configs/ directory and deployed with archagent deploy configs.

Easy confusions

• Routine vs Automation. Agent-scoped vs project-scoped. Start with routine. Reach for automation when two+ agents need the same handler.
• Tool vs Skill. A tool is an action the agent can call. A skill is a bundle of instructions the agent reads. Tools do things; skills tell the agent how to do things.
• Script vs Workflow. One expression vs a graph. Ship a script until branching or approvals force you to a workflow.
• AgentTemplate vs Agent. The YAML config vs the deployed instance. Templates are declarative and reproducible; agents are live and have IDs.
• Installation vs Tool. An installation is the wiring (credentials + capability attach). The tools it exposes are what the agent actually calls.

When a customer asks "which do I want?"

1. "I want the agent to react to something." → Routine.
2. "I want the agent to do something on a schedule." → Routine with event_type: schedule.cron.
3. "I want the agent to live in a Slack / thread conversation." → archastro/thread installation + participate preset routine.
4. "I want the agent to call my API." → Custom tool backed by a Script in the requests namespace.
5. "I want the agent to remember things about a user." → memory/long-term installation + auto_memory_capture routine.
6. "I want multi-step logic with approvals / branches." → Workflow.
7. "I want reusable playbooks the agent loads on demand." → Skill.
8. "I want it across customers / companies." → Agent Network (cross-company threads + shared teams).