DOCSEARCHbyAlgolia
Submit Docs

OpenAB Documentation

repository·main·Indexed 20 days ago

https://github.com/openabdev/openab

A cloud-native Agent Client Protocol (ACP) broker that connects chat platforms such as Discord, Slack, Feishu, and LINE to AI agent runtimes including Claude Code, Gemini, and Kiro via stdio JSON-RPC. Includes documentation for the agy-acp adapter for Antigravity CLI, AgentCore runtimes for Kiro and Codex, and Helm charts for deploying agents on Feishu and LINE.

Tokens
276.5K
Snippets
627
Records
1.1K
Agent score
68%

What's inside OpenAB

  1. Overview of the OpenAB project structure

    main

    The OpenAB repository is organized as follows:

    • Dockerfile: A multi-stage build using a Rust build stage and a debian-slim runtime containing kiro-cli.
    • config.toml.example: A template configuration file containing all available agent backends.
    • k8s/: Kubernetes manifests for deployment.
    • src/: The core source code:
      • main.rs: The application entrypoint handling multi-adapter startup, cleanup, and shutdown.
      • adapter.rs: Defines the ChatAdapter trait and the AdapterRouter (platform-agnostic).
      • config.rs: Handles TOML configuration and ${ENV_VAR} expansion.
      • discord.rs: Implementation of DiscordAdapter using serenity's EventHandler and the ChatAdapter trait.
      • slack.rs: Implementation of SlackAdapter using Socket Mode and the ChatAdapter trait.
      • media.rs: Shared utilities for image resizing/compression and STT (Speech-to-Text) downloads.
      • format.rs: Logic for message splitting and thread name shortening.
      • reactions.rs: A status reaction controller featuring debounce and stall detection.
      • acp/: The Agent Communication Protocol implementation:
        • protocol.rs: JSON-RPC types and ACP event classification.
        • connection.rs: Manages spawning the CLI and communicating via stdio JSON-RPC.
        • pool.rs: A map managing AcpConnection instances by session key.

  2. What is OpenAB?

    main

    OpenAB (Open Agent Broker) is a lightweight, secure, cloud-native ACP (Agent Client Protocol) harness. It acts as a thin broker that bridges chat platforms like Discord and Slack to any ACP-compatible coding CLI (such as Kiro CLI, Claude Code, Gemini, or Copilot CLI) via stdio JSON-RPC.

    Core Architecture

    • Platform Adapters: Converge on a single dispatcher and session pool.
    • ACP Boundary: Communicates with the selected agent runtime across a single ACP stdio boundary.
    • Gateway Adapters: Can be embedded in a unified build or run as a standalone companion to support additional platforms like Telegram, LINE, Feishu/Lark, Google Chat, WeCom, and Microsoft Teams.

  3. Overview of OpenAB Discord Slash Commands

    main

    OpenAB uses Discord slash commands for session control and agent management. Most commands work in guild threads and DMs, except for /auth, which is restricted to DMs for security. All command responses are ephemeral, meaning only the user who ran the command can see the reply.

    Command Reference

    CommandDescriptionRequires active session?
    /modelsSelect the AI model via dropdown menuYes
    /agentsSelect the agent mode via dropdown menuYes
    /cancelCancel the current in-flight operationYes
    /resetReset the conversation session (clear history, start fresh)Yes
    /authAuthenticate the backend agent via device flow (DM-only)No
    /remindSet a one-shot delayed reminder to mention users/rolesNo
    /export-threadExport thread/DM as .txt (default: last 100 messages)No

    Platform Support

    • Discord (guild threads): Supported. Commands are registered per-guild.
    • Discord (DMs): Supported. Commands are registered globally (may take up to 1 hour to appear after first deploy).
    • Slack: Not supported. Slack blocks third-party slash commands in threads.

  4. What is OpenAB (Open Agent Broker)

    main

    OpenAB is a lightweight, secure, cloud-native Agent Client Protocol (ACP) harness. It acts as a thin broker that connects messaging platforms (like Discord and Slack) to any agent runtime compatible with the Agent Client Protocol via stdio JSON-RPC.

    Key Architecture Concepts:

    • Thin Broker: All platform adapters feed into a single dispatcher and session pool, which then connects to a selected agent runtime through a single ACP stdio boundary.
    • Gateway Adapters: While Discord and Slack are supported natively, other platforms (Telegram, LINE, Feishu/Lark, Google Chat, WeCom, and Microsoft Teams) are supported via gateway adapters. These can be embedded in a unified binary or deployed as a standalone Custom Gateway.
    • Agent Runtimes: OpenAB can switch between various backends such as Kiro CLI, Claude Code, Codex, Gemini, Copilot CLI, and many others.

  5. Overview of Codex Runtime for AgentCore

    main

    The Codex Runtime is a container designed to run the Codex CLI within the Amazon Bedrock AgentCore Runtime environment.

    Note: This feature is currently marked as Coming soon. For a reference implementation of how runtimes are structured in AgentCore, refer to the ../kiro/ directory.

  6. Compare AWS deployment architectures for Telegram and LINE bots

    main

    There are three primary production-grade reference architectures for deploying OpenAB bots with Telegram and/or LINE webhooks on AWS ECS Fargate without Kubernetes:

    OptionArchitectureMonthly CostBest For
    1API Gateway HTTP API + VPC Link + Cloud Map~$12–17Single/multi bot, no ALB, lowest AWS-native cost
    2ALB + ECS Fargate~$20+Health checks, auto-scaling, enterprise
    3Cloudflare Tunnel sidecar~$5–10Already have Cloudflare, simplest setup

    Note on OpenAB v0.9.0-beta.4+: These versions ship with unified webhook mode by default. You can set TELEGRAM_BOT_TOKEN or LINE_CHANNEL_SECRET + LINE_CHANNEL_ACCESS_TOKEN as environment variables directly on your bot container. The infrastructure paths described in this guide work regardless of how the platform adapter is wired; only the deployment shape changes.

  7. Compare AWS deployment options for OpenAB bots

    main

    When deploying OpenAB bots on AWS, choose an architecture based on your budget and requirements:

    FeatureOption 1: API Gateway + Cloud MapOption 2: ALB + ECS FargateOption 3: Cloudflare Tunnel
    Best ForBudget + AWS-nativeEnterprise / High TrafficCloudflare users / Lowest cost
    Est. Monthly Cost~$12–17~$18–21~$5–10
    ComplexityMediumLowLow
    AWS-nativeYesYesNo (Cloudflare dependency)
    Health ChecksManualBuilt-inManual
    Multi-platformSingle VPC LinkSingle ALBSingle Tunnel

    Summary of Options

    • Option 1 (API Gateway + Cloud Map): Recommended for those wanting a purely AWS-native, cost-effective setup.
    • Option 2 (ALB): Best for enterprise compliance (WAF/Shield) or if you need native auto-scaling and path-based routing for many bots.
    • Option 3 (Cloudflare Tunnel): The simplest and cheapest path if you already use Cloudflare, using a sidecar pattern on ECS Fargate.

  8. What is Ambient Mode?

    main

    Ambient mode allows an OpenAB bot to passively listen to messages in configured channels and autonomously decide whether to respond, rather than waiting for an @mention. The bot observes the conversation flow and only speaks when it has something valuable to add.

    How it works:

    1. Messages in configured channels (that are not @mentions) are buffered per-channel.
    2. A time trigger (flush_interval_seconds) or count trigger (flush_max_messages) fires, sending the batch to the LLM.
    3. The LLM either Replies (posted to the channel) or returns [NO_REPLY] (silently suppressed).
    4. If the bot is @mentioned, the current buffer is discarded and the mention is handled immediately via normal dispatch.

  9. What is the Hermes Agent?

    main

    The Hermes Agent acts as a multi-provider inference gateway for OpenAB agents. It supports the Agent Communication Protocol (ACP) natively via the hermes acp subcommand or the hermes-acp binary.

    Key benefits include:

    • Zero Auth Complexity: Hermes manages the OAuth token lifecycle, credential storage, and provider routing, so OpenAB agents do not need to manage authentication directly.
    • Multi-provider Access: Provides access to 30+ providers (e.g., xAI Grok, Anthropic, OpenAI, Google Gemini) through a single interface.
    • Cost Efficiency: Allows using consumer subscriptions (like SuperGrok) instead of expensive pay-per-token API pricing.
    • Multi-modal Support: Handles TTS, image generation, and video generation via the same OAuth tokens.
    • Fallback Chains: Can automatically switch providers if one fails.

  10. What is agy-acp?

    main

    agy-acp is an Agent Client Protocol (ACP) adapter for the Antigravity CLI. It acts as a bridge that translates OpenAB's stdio JSON-RPC protocol into commands that the agy CLI can understand by spawning agy -p "prompt" processes.

    Key features include:

    • Conversation Tracking: Uses SQLite .db files to track conversation IDs.
    • Response Extraction: Extracts agent responses from the protobuf step_payload (specifically field 20.1).
    • Session Persistence: Maintains state to support multi-turn conversations.

  11. What is the OAB MCP Facade?

    main

    The OAB MCP Facade is a loopback Streamable HTTP MCP server that acts as a single entry point for coding CLIs (like Kiro CLI, Claude Code, or Codex). Instead of exposing a flat list of every tool from every provider, it exposes exactly two meta-tools: search_capabilities and execute_capability.

    This architecture allows for progressive discovery of the entire provider catalog configured in your mcp.json files. The facade manages tool filtering (least-privilege), JSON-Schema validation, timeouts, and secret redaction before dispatching native tools/call requests to downstream providers.

  12. What is GBrain and how does it work with OpenAB?

    main

    GBrain is a persistent memory system designed for multi-agent deployments. In a standard OpenAB setup, agent pods are isolated, meaning they lack shared memory and context. GBrain solves this by providing a shared, queryable knowledge layer using PostgreSQL and pgvector.

    How it integrates: Each OpenAB agent pod runs gbrain serve as a local MCP (Model Context Protocol) server. All agent pods connect to a single, centralized PostgreSQL database. This allows one agent to write information (e.g., a task handoff) that other agents can immediately query and retrieve.

    Key Capabilities:

    • Pages: Stores markdown content with frontmatter and tags.
    • Hybrid Search: Supports vector similarity, keyword matching, and knowledge graph traversal.
    • Links: Allows creating typed edges between entities (e.g., assigned_to, depends_on).
    • Timeline: Maintains chronological events per entity.
    • MCP Native: Exposes 30+ tools (like brain_write, brain_query) via the MCP protocol, making it compatible with any MCP-supporting CLI (Kiro, Claude Code, Copilot, etc.).