Extensions & Integrations

Overview

ArchAstro agents connect to outside systems in five ways:

Method	What it does	When to use it
Built-in integrations	Connect to GitHub and Slack with OAuth or app installations	You need an agent to read from or act in a known service
Custom tools	Define your own tool backed by a script, workflow, or HTTP endpoint	You need the agent to call your own APIs or business logic
MCP servers	Connect to any remote MCP-compatible tool server	You want to use tools from the MCP ecosystem
Webhooks	Receive inbound events from external systems	You need to trigger agent behavior from outside ArchAstro
Scripts	Write custom logic with HTTP calls, JWT auth, and data transformation	You need to call any API with full control over the request

These methods compose. An agent can use built-in GitHub integration for knowledge, a custom tool for your billing API, and a script-based routine that calls a third-party webhook — all at the same time.

---

Built-in integrations

ArchAstro has native support for connecting to common services. Each integration handles authentication, token refresh, and data access.

Integration	What it provides
GitHub (OAuth)	Personal-account repo access, issues, PRs — for knowledge indexing and code context
GitHub App	Org-wide repo access with a bot identity — for PR reviews, automated comments
Slack (OAuth)	User-level Slack workspace access
Slack Bot	Post messages to channels, read channel history

Two install models:

• Per-agent OAuth — one credential, one agent. Best when each agent needs its own scope or a separate workspace.

  archastro create agentinstallation --agent <agent_id> --kind integration/github
  archastro authorize agentinstallation <installation_id>
  archastro activate agentinstallation <installation_id>
  

• Shared app installation (Slack Bot and GitHub App only) — an org admin first creates the shared org integration, then each agent gets an enablement/* binding to that shared integration.

  # After the org-level GitHub App integration exists:
  archastro create agentinstallation --agent <agent_id> --kind enablement/github_app
  

  enablement/github_app is only the binding step. Passing GitHub's numeric installation_id in the installation config does not create the required shared org integration; a pending install with next_action: configure_shared_integration means the org-level prerequisite still needs to be completed or selected. If multiple shared integrations exist, pass --shared-integration <integration_id> when creating the enablement installation. See Org-wide integrations for the full setup path and permission requirements.

Once connected, the agent can use the integration through its builtin tools (e.g. integrations, knowledge_search) and script bindings.

See Installations for the full list of available kinds and the setup lifecycle.

---

Custom tools

When the agent needs to call your own APIs or run business-specific logic, create a custom tool.

Custom tools can be backed by:

Handler	How it works
Script	Runs an ArchAstro script that can make HTTP calls, transform data, and return results
Workflow	Triggers a multi-step workflow with branching, approvals, and external calls
HTTP endpoint	Calls an external URL directly with the tool arguments as the request body

Define custom tools in an AgentTemplate:

tools:
  - tool_type: custom
    name: lookup_order
    description: Look up a customer order by ID
    parameters:
      type: object
      properties:
        order_id:
          type: string
    handler_type: script
    config_ref: order-lookup-script

Or create them directly:

archastro create agenttool --agent <agent_id> \
  --kind custom \
  --name "lookup_order" \
  --description "Look up a customer order by ID"

See Tools for the full tool model and embed workflow.

---

MCP servers

ArchAstro supports connecting to remote MCP (Model Context Protocol) servers. This lets agents use any tool from the MCP ecosystem — Stripe, Notion, Sentry, Linear, and hundreds of others.

MCP servers are defined as configs:

kind: MCPServer
key: stripe-mcp
name: Stripe
url: https://mcp.stripe.com
auth:
  type: bearer
  token_source: integration

When an MCP server is connected with an integration credential, the agent gets access to all the tools that server exposes — without you writing any custom tool definitions.

---

Webhooks

Inbound webhooks let external systems trigger agent behavior. When ArchAstro receives a webhook, it can:

• trigger an automation
• start a workflow
• ingest data into knowledge

Webhooks are configured from the CLI, or in the developer portal under Dashboard -> Apps -> your app -> Webhooks. Each webhook gets a unique URL that external systems can POST to.

---

Scripts with HTTP access

For full control over external API calls, use scripts with the requests namespace:

let http = import("requests")
let jwt = import("jwt")
let dt = import("datetime")

// Sign a JWT for service account auth
let token = unwrap(jwt.sign({
  iss: env.CLIENT_EMAIL,
  scope: "https://www.googleapis.com/auth/cloud-platform",
  aud: "https://oauth2.googleapis.com/token",
  iat: dt.unix(),
  exp: dt.unix() + 3600
}, env.PRIVATE_KEY, "RS256"))

// Exchange for access token
let resp = unwrap(http.post("https://oauth2.googleapis.com/token", {
  headers: {"Content-Type": "application/x-www-form-urlencoded"},
  body: "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=" + token
}))

resp.body.access_token

Scripts can call any HTTP API — REST, GraphQL, webhooks, OAuth token exchanges. Combined with env variables for secrets, this gives you full programmatic access to any external service.

See Scripts and the Script Language Reference for the full language.

---

The API

Everything in ArchAstro is API-first. The same operations available in the CLI and portal are available through the REST API:

• Create and manage agents, teams, threads, and messages
• Deploy configs and manage installations
• Send messages and trigger agent behavior programmatically

See the API Reference for the full specification.

---

Choosing the right approach

You want to...	Use
Connect to GitHub or Slack	Built-in integration
Call your own product API from an agent	Custom tool
Use tools from the MCP ecosystem	MCP server
Trigger agent work from an external system	Webhook
Call any HTTP API with full control	Script with requests
Build a product on top of ArchAstro	REST API

Start with built-in integrations for supported services. Use custom tools or scripts when you need something specific to your business.