For Coding Agents | ArchAgents Docs

Human? This page is written for AI coding assistants. For the human getting-started guide, see Getting Started.

Overview

This page is for coding agents and the developers using them.

Use it when the goal is to get ArchAstro working quickly and correctly inside a real codebase.

The default assumptions are:

get to an agent that can answer a test prompt quickly
use the CLI as the default setup path
use the same core agent model whether the user is deploying for a team or embedding inside a product
avoid inventing extra wrappers or scaffolding unless the user asks for them

Quick setup prompt

Paste this into the repo you are working in:

Set up ArchAstro in this repo so we can deploy an agent and test it.

1) Read:
   https://docs.archastro.ai/llms-full.txt

2) Ask me for any missing ArchAstro credentials or environment variables.

3) Install the ArchAstro CLI and run: archastro auth login && archastro init

4) Write an agent.yaml template (kind: AgentTemplate) with:
   - a clear identity/instructions
   - the participate preset routine (so it responds in conversations)
   - search and knowledge_search builtin tools
   - memory/long-term installation

5) Deploy it: archastro deploy agent agent.yaml --name "Support Agent"

6) Test it:
   - create a thread, user, and send a test message
   - OR create an agent session and exec a test prompt

7) When complete, summarize what was created and how to test it again.

Required environment variables

Before running ArchAstro operations, check for these values:

Variable	Required	Purpose
`ARCHASTRO_SECRET_KEY`	CI or non-interactive use	Server-side or automated authentication when browser login is not available
`ARCHASTRO_APP_ID`	Existing project linkage only	Needed when the repo should link to a specific existing ArchAstro project

Ask the user for missing values instead of guessing them.

Canonical URLs

Resource	URL
Documentation	`https://docs.archastro.ai`
Developer portal	`https://developers.archastro.ai`
LLM index	`https://docs.archastro.ai/llms.txt`
Extended LLM index	`https://docs.archastro.ai/llms-full.txt`

Treat these as canonical. Do not invent alternate hosts or endpoint roots.

Install the CLI

The CLI is the default starting point.

macOS

brew install ArchAstro/tools/archastro

Linux

curl -fsSL https://raw.githubusercontent.com/ArchAstro/archastro-cli/main/install.sh | bash

Windows

irm https://raw.githubusercontent.com/ArchAstro/archastro-cli/main/install.ps1 | iex

Verify the install:

archastro --help

Minimal setup pattern

1. Authenticate

archastro auth login
archastro auth status

2. Connect the project

archastro init

3. Write an agent template

Create agent.yaml in your project:

kind: AgentTemplate
key: support-agent
name: Support Agent
identity: |
  You help users resolve support and billing
  problems with short, concrete answers.

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

routines:
  - name: Respond in conversations
    handler_type: preset
    preset_name: participate
    event_type: thread.session.join
    event_config:
      thread.session.join: {}
    status: active

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

4. Deploy it

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

5. Prove the agent can answer

archastro create agentsession --agent <agent_id> \
  --instructions "Help a user resolve support questions. Ask one clarifying question if needed."
archastro exec agentsession <session_id> \
  -m "Can you help with invoice failures?"

6. Test with a thread and message

archastro create thread -t "Support test" --owner-type agent --owner-id <agent_id>
archastro create user --system-user -n "Demo User"
archastro create threadmember --thread <thread_id> --user-id <user_id>
archastro create threadmessage --thread <thread_id> --user-id <user_id> \
  -c "Can you help with invoice failures?"

Save the printed IDs as you go. The next command will need them.

For manual step-by-step creation without a YAML file, use archastro create agent, archastro create agentroutine, etc. See CLI for all commands.

Platform building blocks

Use these plain meanings when explaining ArchAstro inside a repo:

Term	Meaning
Agent	The long-lived AI identity you create and manage
Routine	An event handler for the agent: when X happens, do Y
Tool	An action the agent can take
Knowledge	The information the agent can use
Thread	The conversation where people and agents exchange messages

If the user needs a conceptual explanation, point them to Agents.

Auth and safety guidance

Area	Guidance
Auth	Use the published auth flows and key types only
OAuth	Use the published device flow for CLI and non-browser flows
Setup	Prefer CLI setup and CLI verification before reaching for APIs

If a coding agent needs exact request or response shapes after the CLI flow is already working, use /openapi.json as the advanced reference for currently published operations.

Optional helpers

/llms.txt - lightweight page index for small context windows
/llms-full.txt - extended index with more content

Rules for coding agents

Check required environment variables before trying write actions.
Prefer the fastest path to an agent you can test over broad upfront scaffolding.
Use the CLI first for setup, verification, and repeatable workflows.
Use llms-full.txt before scraping rendered docs pages.
Reach for openapi.json only when exact request or response shapes are necessary.
Do not add extra setup the user did not ask for.
Do not expose secret keys or put them in client-side code.
Explain what was created in plain language after setup completes.

Tell us where this page still falls short.