archagent-integration-patterns

Integration Patterns

Most customer integrations collapse to one of seven shapes. When a customer describes what they want, map it to the closest pattern below and produce the minimal agent.yaml snippet. Then load the deeper skill (archagent-author-agent, archagent-build-script, archagent-build-workflow) to fill in details.

Pattern 1 — GitHub PR review

Use when: customer wants to review PRs, triage issues, or react to pushes.

installations:
  - kind: integration/github
    config: {}

routines:
  - name: review-prs
    handler_type: preset
    preset_name: do_task
    event_type: webhook.github_app.pull_request
    event_config:
      webhook.github_app.pull_request:
        filters: {}
    status: active

Critical: GitHub sends multiple events per PR. Enforce action in {"opened", "synchronize"} filter or in the identity prompt, otherwise the agent reviews the same PR N times.

Reference sample: agents/code-review-agent in this repo.

Pattern 2 — Slack bot

Use when: the customer's users should talk to the agent in Slack.

Install the Slack app installation. The simplest shape uses thread.session.join + the participate preset — Slack messages get proxied into threads automatically.

installations:
  - kind: archastro/thread
    config: {}
  - kind: integration/slack
    config: {}

routines:
  - name: participate-slack
    handler_type: preset
    preset_name: participate
    event_type: thread.session.join
    event_config:
      thread.session.join:
        filters: {}

To post outbound (from scripts/workflows), use the slack script namespace: let slack = import("slack"); unwrap(slack.post_message(...)).

Pattern 3 — Scheduled job

Use when: "run every Monday at 9am", "check this feed every hour".

routines:
  - name: weekly-digest
    handler_type: preset
    preset_name: do_task
    event_type: schedule.cron
    schedule: "0 9 * * 1"
    event_config:
      schedule.cron:
        filters: {}