Agents

Overview

An ArchAgents agent is a long-lived AI worker with a clear job, useful tools, and knowledge it can use.

It is not just a prompt or a one-off workflow run. An agent can:

• talk with people in threads
• react to events over time
• use tools to do work
• draw from knowledge
• keep behaving like the same named, managed system over time

The same model works whether you are building agents for your team, embedding them inside a product, or running them across a multi-company deployment. What changes is packaging and access, not the basic building blocks.

---

The core message flow is simple:

1. A person or system sends a message in a thread.
2. The platform checks whether any agent routines should react.
3. The agent uses its instructions, tools, and knowledge to decide what to do.
4. The agent replies, takes an action, or starts additional work.

This is the flow you are building on top of.

---

Agent

The agent is the main object in the system. It is the managed AI worker you create and operate.

An agent has:

• a name people can recognize
• a stable key your team can reference in code and automation
• instructions that define its role and boundaries
• optional metadata for ownership, company, and current state

You can create one quickly from the CLI:

archagent create agent -n "Support Agent" -k support-agent \
  -i "You help users resolve billing and support issues with short, concrete answers."

The result is a durable agent identity, not a one-off prompt.

---

Profile and instructions

Every agent has profile details and instructions that shape how it shows up to other people.

It defines things like:

• display name
• tone and voice
• avatar or profile presentation
• instructions that shape how the agent sounds in conversations

You can think of this as the outward face of the agent. The agent is the same worker underneath; these settings shape how it appears and communicates.

Update instructions, name, and profile details from the CLI or an agent template. In ArchAgents Portal, open Agents and click into an agent for a visual view you can review and edit.

---

Routines

Routines give the agent ongoing behavior.

They answer two practical questions:

1. When should this agent act?
2. What should it do when that happens?

For example, you can create a routine that runs when a new message appears:

archagent create agentroutine --agent <agent_id> \
  -n "billing-triage" \
  -e thread.message_added \
  -t script \
  --script "{ route: \"billing\", priority: \"high\" }"
archagent activate agentroutine <routine_id>

New routines start in draft, so save the routine ID from the create command and activate it when you want the handler to run.

Common routine patterns

• reply when a new message arrives
• run on a schedule
• react when a person joins a thread
• respond when new knowledge or integration data becomes available

Handler types

Handler type	When to use	What runs
preset: participate	Agent should join and respond in a thread conversation	Built-in conversation handler that posts the agent's response into the thread
preset: auto_memory_capture	Extract and store key facts when a conversation ends (opt-in)	Built-in memory extraction
preset: do_task	Scheduled work or offline computation whose result does not belong in a thread	Full LLM session with all agent tools; result is stored in the routine run record, not posted to a thread
script	Deterministic logic (routing, filtering, transformations)	ArchAgents script expression
workflow_graph	Multi-step process with branching or approvals	Workflow config

participate vs. do_task — pick based on where the result should go:

• Use participate when the agent should reply inside a thread. The preset handles the thread-side mechanics and the user sees the agent's response as a thread message.
• Use do_task for offline computation — scheduled summaries, batch analysis, periodic audits — where the result is inspected via archagent list agentroutineruns or the activity feed. A do_task run stores its output in the run record rather than posting to a thread, so use it when the result is meant to be read from the run history, not from the conversation.

do_task is more powerful (full LLM reasoning with every tool attached), and participate is the right choice whenever you want the agent's reply to show up directly in the thread it was triggered from.

For a first agent, start with participate (so it responds in conversations) and auto_memory_capture (opt-in memory extraction — the agent creator adds this routine to enable it; it is not on by default).

State

Routines move through a few simple states:

• Draft when you are still setting them up
• Active when they should run
• Paused when they should stop temporarily

---

Tools

Tools are how an agent does work instead of only talking about work.

Some tools come from the platform, such as messaging, search, or computer-use capabilities. Others are custom tools you define for your own services.

Built-in tools

Use built-in tools when you want standard platform capabilities without having to build them yourself.

Custom tools

Use custom tools when the agent needs to call your own product logic, service endpoints, or company-specific actions.

Read Tools for the real operator workflow: attach, inspect, activate, and run tools through an embed session.

---

Knowledge

Knowledge is the information the agent is allowed to use.

That can include:

• connected repositories and inboxes
• uploaded files and documents
• website content
• thread history
• long-term memory

Access should be intentional. Give an agent only the knowledge it actually needs.

Sources and installations

There are two objects to understand here:

• Installation: a connected external service, account, or integration
• Source: a specific knowledge feed the agent can use from that installation

That means:

1. connect a system or source
2. activate it for the agent
3. let the platform make that knowledge available when the agent needs it

Read Knowledge for the operational model: integrations, sources, ingestions, items, and the debugging loop around them.

---

Structured output

By default, an agent responds with free-form text. When you need the response to fit a known shape — for downstream automation, for inter-agent handoffs, or for content policy enforcement — attach an AgentMessageSchema to the routine.

The schema is a JSON Schema that constrains the agent's output. Required fields, enums, nested objects, and array shapes are all enforced before the response is accepted. You can also attach field guards to a schema to run content policies (regex, substring, or LLM-based) on each resolved field value.

routines:
  - name: customer-triage
    handler_type: preset
    preset_name: do_task
    structured_message_template_refs:
      - "#/schemas/customer-summary"
    status: active

See Structured Output for the schema model and Field Guards for the content policy layer.

---

Threads and messages

Threads are where people and agents talk to each other.

Messages are the individual events inside those threads. A person can send a message, an agent can respond, and routines can use those events to drive behavior.

You can test that flow quickly from the CLI:

archagent create thread -t "Billing support" --owner-type agent --owner-id <agent_id>
archagent create user --system-user -n "Demo User"
archagent create threadmember --thread <thread_id> --user-id <user_id>
archagent create threadmessage --thread <thread_id> --user-id <user_id> \
  -c "I need help with invoice INV-2041"

This creates the flow most developers care about:

1. a message arrives
2. the platform gathers the right context
3. the agent decides what to do
4. the agent replies, uses tools, or pulls in more knowledge

Best practices

1. Give each agent a narrow, understandable job.
2. Add only the routines the agent really needs.
3. Give the agent only the tools and knowledge it should have.
4. Test new behavior in a sandbox before wider rollout.
5. Review agent behavior regularly and refine instructions, routines, and access as you learn what works.

---

Deploy from a template

The recommended workflow is to write an agent.yaml file (an AgentTemplate) and deploy it in one command:

archagent deploy agent agent.yaml --name "Support Agent"

This creates the agent AND provisions all tools, routines, and installations in one command.

Minimal AgentTemplate example

kind: AgentTemplate
agent_key: support-agent
name: Support Agent
identity: |
  You help users resolve billing and support problems with short, concrete answers.
  Always ask one clarifying question before taking action.

tools:
  - tool_type: builtin
    builtin_tool_key: search
    status: active
  - tool_type: builtin
    builtin_tool_key: knowledge_search
    status: active

routines:
  - name: Reply to messages
    description: Respond when a new message arrives
    handler_type: preset
    preset_name: participate
    event_type: thread.session.join
    event_config:
      thread.session.join:
        filters: {}
    status: active

installations:
  - install_type: memory/long-term
    config: {}

Key fields

• identity -- system prompt and instructions that define the agent's behavior and boundaries.
• tools -- builtin or custom tools the agent can use. Builtin tools reference a builtin_tool_key; custom tools reference a handler and config.
• routines -- event handlers that give the agent ongoing behavior. Each routine specifies a handler_type and an event_type.
  • handler_type values: preset (built-in behavior), script (custom logic), workflow_graph (multi-step workflows), chain (a linear sequence of preset / script / workflow_graph steps — see Scripts → Chain-step input shape for how scripts inside chain steps read their input).
  • preset_name values: participate (join conversations), auto_memory_capture (opt-in: extracts and stores key facts after sessions when enabled by the agent creator), do_task (execute instructions on schedule).
  • event_type values: thread.session.join, thread.session.leave, thread.message_added, schedule.cron.
  • For cron routines, add schedule: "0 9 * * 1" (a cron expression in UTC) alongside event_type: schedule.cron.
• installations -- connected capabilities such as memory, integrations, and knowledge sources. See Installations for the full list of kinds.

Validate before deploying

archagent validate configs --kind AgentTemplate --file agent.yaml

Run this before deploy to catch schema errors early.