{"id":47311920,"url":"https://github.com/liujuanjuan1984/a2a-client-hub","last_synced_at":"2026-04-08T07:01:47.907Z","repository":{"id":343874817,"uuid":"1152595944","full_name":"liujuanjuan1984/a2a-client-hub","owner":"liujuanjuan1984","description":"Self-hosted A2A client and control plane for managing and invoking multiple A2A agents across web and mobile.","archived":false,"fork":false,"pushed_at":"2026-03-26T14:24:09.000Z","size":2483,"stargazers_count":1,"open_issues_count":20,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-03-27T00:37:16.051Z","etag":null,"topics":["a2a","a2a-client","a2a-protocol","ai-agent","control-plane","expo","fastapi","react-native","self-hosted"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/liujuanjuan1984.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/security-baseline.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-08T05:33:24.000Z","updated_at":"2026-03-26T14:24:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/liujuanjuan1984/a2a-client-hub","commit_stats":null,"previous_names":["liujuanjuan1984/a2a-client-hub"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/liujuanjuan1984/a2a-client-hub","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liujuanjuan1984%2Fa2a-client-hub","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liujuanjuan1984%2Fa2a-client-hub/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liujuanjuan1984%2Fa2a-client-hub/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liujuanjuan1984%2Fa2a-client-hub/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/liujuanjuan1984","download_url":"https://codeload.github.com/liujuanjuan1984/a2a-client-hub/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liujuanjuan1984%2Fa2a-client-hub/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31243323,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-31T15:15:33.278Z","status":"ssl_error","status_checked_at":"2026-03-31T15:15:28.327Z","response_time":111,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["a2a","a2a-client","a2a-protocol","ai-agent","control-plane","expo","fastapi","react-native","self-hosted"],"created_at":"2026-03-17T12:00:22.893Z","updated_at":"2026-03-31T16:00:40.769Z","avatar_url":"https://github.com/liujuanjuan1984.png","language":"Python","funding_links":[],"categories":["Utilities","⚙️ Implementations \u0026 Libraries"],"sub_categories":["🚆 \u003ca name=\"travel-and-transportation\"\u003e\u003c/a\u003eTravel \u0026 Transportation"],"readme":"# a2a-client-hub\n\n`a2a-client-hub` is a self-hosted A2A client hub for teams and individuals who need one place to manage, invoke, and operate multiple A2A agents across web and mobile.\n\nIt is a client/control plane, not an A2A provider itself. It is also not an MCP server, MCP registry, or MCP gateway.\n\n## Why this project exists\n\nWhen A2A adoption grows, teams usually face the same problems:\n\n- Agent endpoints, credentials, and access policies are scattered.\n- Session history and operational visibility are fragmented per provider.\n- Cross-platform user experience (web/mobile) is inconsistent.\n- Calling external A2A endpoints directly creates security and governance risks.\n\n`a2a-client-hub` addresses this by providing a unified frontend + backend system for agent discovery, invocation, session continuity, scheduling, and controlled outbound access.\n\n## Ecosystem Positioning\n\nThis project is designed for the A2A ecosystem first.\n\n- It aims to work with multiple A2A peer profiles rather than one provider only.\n- Current repository examples still use OpenCode-flavored contracts heavily because that profile is one of the most fully exercised in this codebase.\n- The Hub is not intended to replace MCP. MCP is an agent-internal tool/context protocol; this project focuses on agent-to-agent integration and control-plane concerns.\n\nCurrent compatibility framing:\n\n- First-class today: A2A peers that expose standard Agent Cards plus the shared session / interrupt capabilities consumed by the Hub.\n- Explicitly exercised in this repository: OpenCode-compatible peers and other coding-agent peers, including Codex-family deployments, when they publish a compatible A2A surface.\n- Partial compatibility: standard A2A peers that only support invoke / stream without the shared extension workflows used for session continuity.\n\nRepository-level A2A service references that match the current target profile:\n\n- [`Intelligent-Internet/opencode-a2a`](https://github.com/Intelligent-Internet/opencode-a2a)\n- [`liujuanjuan1984/codex-a2a`](https://github.com/liujuanjuan1984/codex-a2a)\n- [`Swival/swival`](https://github.com/Swival/swival)\n\nSee [docs/compatibility-and-non-goals.md](docs/compatibility-and-non-goals.md) for the maintained compatibility notes and explicit non-goals.\n\n## What value it delivers\n\n- Faster integration: connect multiple A2A agents from one product surface.\n- Better governance: enforce allowlists, admin-only control, and secure token handling.\n- Better user continuity: keep chat and session flows available across devices.\n- Better extensibility: support A2A extension workflows (for example, OpenCode session query) without tightly coupling to provider-specific schemas.\n\n## Core capabilities\n\n- Personal A2A agent management\n  - Add, validate, update, and remove user-managed agents.\n  - Invoke via HTTP and WebSocket.\n- Admin-managed Hub Catalog\n  - Publish global agents for all users (`public`) or selected users (`allowlist`).\n  - Keep admin credentials encrypted and hidden from normal users.\n- Session and chat continuity\n  - Persist sessions/messages and query them from user-facing APIs.\n  - Continue existing upstream sessions in the same chat UI flow.\n- Scheduled invocation\n  - Create and manage recurring A2A schedule tasks.\n  - Support both anchor-based `interval` and completion-based `sequential` modes.\n  - Track execution history for operational visibility.\n- Security controls\n  - Outbound A2A host allowlist enforcement.\n  - Short-lived access token + rotating HttpOnly refresh cookie model.\n  - WebSocket one-time ticket flow and origin validation.\n\n## Architecture at a glance\n\n- `frontend/`\n  - Expo + React Native + Web client\n  - Auth, catalog browsing, chat/session UI, schedule UI, admin screens\n- `backend/`\n  - FastAPI + PostgreSQL + Alembic\n  - Auth, agent orchestration, scheduling, A2A proxy/runtime, persistence\n- `docs/`\n  - Cross-cutting architecture and API examples\n\nSee [docs/architecture-and-api.md](docs/architecture-and-api.md) for request flows and endpoint examples.\n\n## Quick start (local development)\n\n### Prerequisites\n\n- Python 3.12+\n- Node.js 18+\n- PostgreSQL\n- `uv` (Python package manager)\n\n### 1. Start backend\n\n```bash\ncd backend\nuv sync --extra dev --locked\ncp .env.example .env\nuv run python scripts/setup_db_schema.py --create\nuv run alembic upgrade head\nuv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000\n```\n\nNotes:\n\n- RS256 JWT keys are required. Configure them in `backend/.env` based on `backend/.env.example`.\n- Configure `A2A_PROXY_ALLOWED_HOSTS` before invoking downstream A2A endpoints.\n\n### 2. Start frontend\n\n```bash\ncd frontend\nnpm install\ncp .env.example .env\nnpm run start\n```\n\nSet `EXPO_PUBLIC_API_BASE_URL` in `frontend/.env` for your backend.\n\n## Production Parameter Baseline (Scheduler and Streaming)\n\nSet the following parameters explicitly in production to avoid long transactions and stuck scheduler runs:\n\n- `A2A_SCHEDULE_TASK_INVOKE_TIMEOUT`\n  - Total timeout for a single scheduled invoke (the only run-time upper bound). It should be higher than your common task duration ceiling.\n- `A2A_SCHEDULE_RUN_HEARTBEAT_INTERVAL_SECONDS`\n  - Heartbeat update interval during scheduler execution. Recommended: 15-60 seconds, and it must be lower than invoke timeout.\n  - Heartbeat writes use short `lock_timeout/statement_timeout` values so lock contention fails fast and retries on the next heartbeat cycle.\n- `A2A_SCHEDULE_TASK_STREAM_IDLE_TIMEOUT`\n  - Upstream stream idle timeout. Recommended: 30-120 seconds.\n- `A2A_SCHEDULE_EXECUTION_RETENTION_DAYS`\n  - Retention window for terminal schedule execution history. Recommended: 14-30 days for small deployments unless you need a longer audit trail.\n- PostgreSQL `idle_in_transaction_session_timeout`\n  - Set a database-level fallback (for example, 60s-300s) to prevent long `idle in transaction` sessions on exceptional paths.\n- Cross-process mutual exclusion for the scheduler dispatcher\n  - PostgreSQL advisory lock ensures only one process executes the dispatch loop at a time, reducing extra contention from multi-instance concurrent scan-and-claim behavior.\n\nYou can observe these via `/health` under `a2a.ops_metrics`:\n\n- `db_idle_in_tx_count`\n- `db_pool_checked_out`\n- `schedule_running_task_count`\n- `schedule_run_finalize_latency`\n\n## Key docs\n\n- Documentation index: [docs/README.md](docs/README.md)\n- Contributor guide: [CONTRIBUTING.md](CONTRIBUTING.md)\n- Automation protocol: [AGENTS.md](AGENTS.md)\n- Backend details: [backend/README.md](backend/README.md)\n- Frontend details: [frontend/README.md](frontend/README.md)\n- Authentication conventions: [docs/authentication.md](docs/authentication.md)\n- Production security baseline: [docs/security-baseline.md](docs/security-baseline.md)\n- Release automation: [docs/release-workflow.md](docs/release-workflow.md)\n- Shared session query contract: [docs/contracts/shared-session-query-canonical-contract.md](docs/contracts/shared-session-query-canonical-contract.md)\n- Architecture and API examples: [docs/architecture-and-api.md](docs/architecture-and-api.md)\n- Compatibility notes and non-goals: [docs/compatibility-and-non-goals.md](docs/compatibility-and-non-goals.md)\n\n## License\n\nThis project is licensed under the Apache License 2.0. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fliujuanjuan1984%2Fa2a-client-hub","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fliujuanjuan1984%2Fa2a-client-hub","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fliujuanjuan1984%2Fa2a-client-hub/lists"}