
Show HN: Hybro – an open interoperability engine for AI agents
I built an open interoperability engine for AI agents. Connect your favorite agents and harnesses. Work together.Appreciate for any feedback.
以下正文同步自 Hacker News 最新,版权归原站所有,已转换为易读排版。
The open-source agent interoperability platform.
⭐ Star this repo to support the growing Hybro open-source community!
Hybro AI is an open-source, hybrid multi-agent platform built for seamless agent interoperability. It serves as the core orchestration engine powering the Hybro Agent Network—enabling local and remote AI agents to communicate, collaborate, and execute complex workflows.
Hybro AI allows developers and teams to deploy, coordinate, and inspect clusters of autonomous AI agents. Powered by an async FastAPI backend and an interactive Next.js dashboard, Hybro provides real-time agent visualization, execution room management, and protocol-agnostic message routing via the Agent2Agent (A2A) standard.
Hybrid Agent Execution: Seamlessly connect and orchestrate local on-device agents and remote cloud-hosted services.
Native Agent Interoperability: Built around the open Agent2Agent (A2A) protocol for standardized inter-agent communication.
Multi-Agent Execution Rooms: Group specialized agents in dedicated execution rooms to solve multi-step tasks collaboratively.
Real-Time Streaming & Inspection: Live SSE message streaming, multi-agent turn timelines, and an interactive A2A Agent Inspector for testing agent capabilities.
CLI-Managed Configuration: Configure models and authentication once, then start backend, frontend and Agents without maintaining environment files.
Getting Started
Prerequisites
Docker with Compose v2.24+ (docker compose; the v1 docker-compose binary is not supported)
Node.js 18+ to install the CLI from npm (not needed for release-asset installs)
uv for host-side hybro setup from a checkout
Node.js 20.19+ (if running the frontend outside of Docker)
Python 3.12+ and MongoDB 4.2+ (if running the backend outside of Docker; Docker Compose uses MongoDB 7.0)
Quick Start (Docker)
Install the CLI, configure it, and start the released stack:
npm install -g @hybroai/cli hybro setup # provider, authentication, models -> ~/.hybro/{config,auth}.json hybro start # pulls the images published for this CLI's version
Hybro App: http://localhost:3000
API Server: http://localhost:8000
MCP Server: http://127.0.0.1:8001/mcp (Streamable HTTP, same-host clients)
Running hybro with no arguments opens the same settings/services interface in a terminal. hybro --version prints the CLI and stack version.
Alternatively, run the CLI without installing it by unpacking a release asset (hybro-<version>-<platform>.tar.gz from the GitHub Release) and executing hybro/hybro.
The development channel builds images from source instead of pulling them:
git clone https://github.com/hybroai/hybro.git cd hybro ./scripts/hybro setup ./scripts/hybro start --build
Use this channel to change Hybro itself or to use settings the published images cannot carry (see Development and released stacks).
Existing installations should perform the one-time JSON migration below before removing old environment files.
Configuration contract
Backend, frontend and bundled-agent user settings belong to one local JSON configuration, not repository environment files:
~/.hybro/ ├── config.json # User settings; edit through the CLI or directly └── auth.json # Credentials; managed through the CLI
HYBRO_HOME is the sole directory override and must be an absolute path. Defaults, types and validation remain in a thin code loader; JSON only needs user overrides. backend/common/config/loader.py replaces the old settings.py environment-loading path. Startup validates syntax, known fields, types, ranges and required combinations. Missing model setup must direct the user to hybro setup; invalid configuration must not silently select a legacy Provider.
CLI edits use the same validation before saving. Manual JSON edits are validated at the next startup. Settings are a startup snapshot: restart services after changes with hybro start --recreate. Only api_prefix needs a rebuild, because the frontend image compiles its server-side API rewrite from it; the browser reads every other public setting from the running container.
.env, .env.example and frontend/.env.local are not required by this contract. The CLI supplies only scoped values to containers and frontend builds; transport environment variables do not become another user configuration source. Secrets must never enter the browser bundle or be forwarded wholesale to Agents.
./scripts/hybro config show ./scripts/hybro config check ./scripts/hybro config set backend.log_level '"DEBUG"' ./scripts/hybro config set frontend.max_message_length 12000 ./scripts/hybro start --recreate
Use config secret <name> for hidden service-credential input and setup for Provider/model changes. Startup generates missing internal tokens in auth.json without rotating existing values. Backend overrides live under backend, public frontend overrides under frontend, and image output size is image_size.
Waits for the owner or for a remote Agent:
./scripts/hybro config set backend.approval_deadline_hours 48 ./scripts/hybro config set backend.orchestrator_call_wait_ceiling_hours 72.5
A Run waiting for an answer or a remote Agent does not count that time against its profile deadline, so it can wait as long as these limits allow. While it waits it keeps the room's single active-Run slot.
Passthrough Runs (session sends, no orchestrator model turns):
If you previously ran hybro setup and have a ~/.hybro/config.yaml, convert it once (optionally importing known deployment values from the old root .env):
./scripts/hybro config migrate --from-env .env ./scripts/hybro config check ./scripts/hybro start --recreate
Omit --from-env if no deployment values need importing. Migration preserves Provider credentials and imports known deployment settings and service secrets; it refuses to overwrite an existing config.json. Original environment files, .env.example and config.yaml are not deleted.
Installations that only used the old root .env (no YAML setup) must instead re-run the interactive setup, then start:
./scripts/hybro setup ./scripts/hybro start --recreate
After either path, normal setup/start uses JSON only, even if the old files remain. migrate warns when it skips legacy route/model fields it cannot map.
The already-implemented Agent proxy shares backend's setup-selected gateway. Agents retain SDKs, tools, HITL and A2A execution. Image generation requires an eligible image model; ChatGPT OAuth alone does not enable it.
./scripts/hybro is the day-2 lifecycle CLI. Common commands:
./scripts/hybro start # up -d, no rebuild (fast daily loop) ./scripts/hybro start --build # rebuild images (after code/deps change) ./scripts/hybro start --recreate # recreate containers (runtime configuration changes) ./scripts/hybro start --build --recreate # rebuild and recreate (after code/deps change) ./scripts/hybro logs backend # stream one service (or all if no arg) ./scripts/hybro status # docker compose ps --all ./scripts/hybro stop # stop but keep containers ./scripts/hybro down # remove containers + default network
Only a source checkout can rebuild; a released install changes versions with hybro upgrade. Configuration never needs a rebuild, except api_prefix.
Run ./scripts/hybro --help for the full subcommand reference. Start through the CLI so Compose receives validated scoped projections, not ambient dotenv values.
hybro start and the TUI's Start services include MCP by default. In the app, open Connect (/connect/mcp) to copy the URL or a setup snippet for your assistant. The Overview Gateway tile shows whether MCP is reachable. Add the server manually to your client; Hybro does not automatically discover or register MCP clients.
{ "mcpServers": { "hybro": { "type": "http", "url": "http://127.0.0.1:8001/mcp" } } }
The Streamable HTTP URL is for clients on the machine running Hybro. If you open the app remotely, loopback in your client still refers to that client's machine, not the Hybro host. MCP has no authentication or user isolation and supports only a trusted local mock-auth backend, not Clerk. Do not expose it publicly.
Use Services > MCP connection in the TUI for status, URL, transport, start, stop, logs, and refresh, or run:
hybro mcp status hybro mcp start # requires setup and a running backend; starts only MCP hybro mcp logs hybro mcp stop
Exiting the TUI leaves services running. Stopping MCP is not a persistent opt-out: the next global start includes it again. The app checks MCP status only from the Overview Gateway tile, when Overview loads; it does not poll in the background, and it cannot start/stop services or relay tool calls. See MCP tools, health, and native startup.
The CLI runs one of two Compose files, both pinned to the hybro project name so containers keep their identity across install locations:
docker-compose.release.yml is generated from docker-compose.yml by default_agents/render_release.py, which swaps every build: block for an image: reference. It is checked in and verified by CI, so the two stacks cannot drift. The CLI supplies HYBRO_STACK_TAG (its own version) and optionally HYBRO_IMAGE_REGISTRY when it starts a released stack, which means a released install always runs the images published for the CLI that started it.
Because a released install has no sources, --build is refused with an explicit message. Upgrading is how you change versions:
hybro upgrade --check # report; exits non-zero when a newer release exists hybro upgrade # install it hybro start --recreate # move the containers onto its images
The container images are pinned to the CLI version, so upgrading the CLI is what moves the stack. hybro upgrade replaces an npm install in place; an install from a release archive prints the download, checksum, and unpack commands instead, because hybro does not overwrite its own directory. A source checkout is updated with git pull and hybro start --build.
Everything else, including frontend settings, applies at runtime:
hybro config set frontend.max_message_length 12000 hybro start --recreate # no rebuild needed
The one exception is backend.api_prefix: the published frontend image compiles its server-side API rewrite from the prefix at build time, so changing it needs the checkout channel. The browser reads the rest of the projection from a per-request route (/hybro-runtime-config) that packaging/frontend/public-config.json supplies at build time only for that routing.
release-please owns version numbers; everything else is produced from them.
The Release workflow is called rather than triggered by release: published because release-please acts with GITHUB_TOKEN, and GitHub does not start workflows for events that token triggers — a release event would never arrive. workflow_dispatch remains for re-publishing after a failure; give it the version so a retry cannot silently publish whatever VERSION happens to say. The same rule explains why release-please PRs get no automatic CI: GitHub does start those runs, but holds them until someone with write access approves them.
Requirements for the workflow: an NPM_TOKEN repository secret with publish rights for the @hybroai scope, and the scope must already exist on npm. Publishing the images also needs the ghcr.io/hybroai packages to be public; GitHub creates them private, and a private image makes hybro start fail with an authorization error.
backend/uv.lock records the project's own version and release-please does not update it, so a release leaves it one version behind. uv sync --frozen tolerates that, but uv lock --check does not.
Build the CLI locally with packaging/cli/build.sh, then stage it for npm with packaging/npm/build.sh <darwin-arm64|darwin-x64|linux-arm64|linux-x64>. Releases ship a PyInstaller onefile executable: a single binary with no symbolic links, because npm's packer drops links and a macOS onedir bundle depends on four of them. The bundle extracts to a new temporary directory per run, which is why both Compose files pin name: hybro.
This repository is the source
正文由 探How 从来源站点 RSS 同步,内容未经改写;遇到排版缺失或需要图片、视频时请以原文为准。