ArchAstro Docs

Overview

In many agent frameworks, an "agent" exists only while a prompt or workflow is running. In ArchAstro, agents are persistent platform resources with identity, lifecycle, scoped data access, and execution history.

This means your agents survive across sessions, operate within clear access boundaries, and can be managed through the portal, API, or CLI like other application resources.

Agent identity

Every agent has a unique identity scoped to your app.

const agent = await client.rest.createAgent({
  name: "Support Agent",
  lookup_key: "support-bot",
  email: "support@yourapp.com",
  identity: "You are a customer support specialist for Acme Corp.",
  metadata: {
    department: "customer-success",
    tier: "enterprise",
  },
});

Key properties:

Field	Purpose
`name`	Display name shown in conversations
`lookup_key`	App-unique identifier for programmatic access
`identity`	Behavioral description for the agent
`email`, `phone_number`	Contact fields for agent-facing scenarios
`metadata`	Arbitrary extensible data
`secret_group_id`	Encrypted credential store for this agent

When you create an agent, the platform automatically provisions an encrypted credential store scoped to that agent. This is where installation tokens and agent-specific secrets live.

Agent operations:

const agents = await client.rest.listAgents();
const agent = await client.rest.getAgent("agi_abc123");

await client.rest.updateAgent("agi_abc123", {
  name: "Senior Support Agent",
  identity: "You are a senior support specialist...",
});

await client.rest.deleteAgent("agi_abc123");

Routines

Routines are the core execution primitive. Each routine binds an agent to an event type and a handler so the agent can respond automatically when matching events occur.

Creating a routine

const routine = await client.rest.createAgentRoutine({
  agent_id: agent.id,
  name: "billing_triage",
  event_type: "thread.message_added",
  handler_type: "script",
  script: `
    const msg = event.payload.message;
    if (msg.text.includes("invoice")) {
      return { route: "billing", priority: "high" };
    }
    return { route: "general" };
  `,
});

Event types

Event	Fires when
`thread.message_added`	A new message is posted in a thread
`thread.created`	A new thread is created
`thread.member_joined`	A member joins a thread
`schedule.cron`	On a cron schedule
`connector.connected`	A user completes an OAuth connection
`context.ingestion_succeeded`	Data ingestion completes

Event filtering

Routines can filter which events actually trigger execution using event_config:

await client.rest.createAgentRoutine({
  agent_id: agent.id,
  name: "filtered_handler",
  event_type: "thread.message_added",
  event_config: {
    "thread.message_added": {
      subject_is_agent: true,
      thread_id: ["thr_123"],
    },
  },
  handler_type: "workflow_graph",
  config_id: "cfg_workflow_abc",
});

Handler types

Workflow graph — executes a saved workflow.

{
  handler_type: "workflow_graph",
  config_id: "cfg_abc123"
}

Script — runs inline code or references a saved Script config.

{
  handler_type: "script",
  script: "return { handled: true, result: event.payload.message.text };"
}

{
  handler_type: "script",
  config_id: "cfg_script_xyz"
}

Preset — delegates to a built-in handler.

{
  handler_type: "preset",
  preset_name: "participate"
}

Routine lifecycle

Routines follow a clear lifecycle: draft → active → paused.

Draft — created but not processing events
Active — listening for matching events and executing
Paused — temporarily stopped and later reactivated

Run history

Each routine execution records status, timing, input context, and result details. Use the portal or API to monitor run history, troubleshoot failures, and understand how your automations are behaving in practice.

Installations

Installations connect agents to external data sources and capabilities.

Installation categories

Category	Examples
Email and messaging	Gmail, Outlook, Slack
Repositories and developer systems	GitHub
Web content	Sites and link collections
Platform content	Threads, uploaded files, and other app data

Installation lifecycle

For OAuth-backed installations, a user completes the provider's authorization flow, the connection is stored securely, and the installation can then be activated for the agent.

Working with installations

const kinds = await client.rest.listInstallationKinds();

const install = await client.rest.createAgentInstallation({
  agent_id: agent.id,
  kind: "integration/gmail",
});

await client.rest.activateAgentInstallation(install.id);
await client.rest.pauseAgentInstallation(install.id);

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

Design your context footprint carefully. An agent should only have access to the data it actually needs.

How the pieces fit together

flowchart TD
    A["Agent"]
    A --> B["Identity and instructions"]
    A --> C["Routines"]
    A --> D["Installations and context"]
    A --> E["Tools"]
    C --> F["Events trigger execution"]
    D --> G["Approved knowledge is retrieved when needed"]
    E --> H["Actions run through platform or app logic"]

Best practices

Keep each agent's scope narrow and intentional.
Attach only the routines and knowledge sources the agent actually needs.
Test new routines in sandbox environments before production rollout.
Monitor routine history for failures, unexpected triggers, and noisy behavior.
Gate side-effectful actions behind explicit approval or workflow steps.

Agents