Skip to content

btnalit/cocoagent

BranchesTags

Repository files navigation

Cocoagent

What This Project Is

Cocoagent is a full-stack AgentOS workspace for building, operating, and governing AI agents. The repository contains the FastAPI backend, Vue control plane, PostgreSQL schema migrations, Docker packaging, OpenAPI contract generation, and process gates in one place.

Core stack:

  • Backend: Python 3.12+, FastAPI, Pydantic Settings, psycopg, optional LangGraph runtime.
  • Frontend: Vue 3, TypeScript, Element Plus, Pinia, Vue Router, Vite.
  • Storage: PostgreSQL 15 with pgvector.
  • Packaging: Docker Compose and a multi-stage production image that builds the frontend and serves it from the backend.

Current Capabilities

  • Unified AI chat and runtime entrypoint under /ai/agent.
  • Agent configuration console for creating and managing Agent definitions.
  • Telegram conversation entrypoint:
    • Bot connection management from the UI.
    • Default source-to-Agent binding.
    • Local long polling mode for development and private deployments.
    • Production webhook mode for public HTTPS deployments.
    • Runtime status display including current mode, webhook URL, polling offset, and last error.
    • Creating a Telegram connection from the UI automatically enables local long polling.
  • LLM provider configuration and provider health/testing workflow.
  • Skill management and tool/policy control surfaces.
  • Approval center and runtime governance workflows.
  • Learning and operations control-plane views.
  • OpenAPI contract export plus generated frontend types.
  • A01/A34/A35/A36 process gates for route drift, release readiness, and architecture/governance constraints.

Runtime Shape

Backend

cocoagent-python/src/cocoagent/main.py wires the main FastAPI application and registers these API areas:

  • /api/auth
  • /api/ai
  • /api/ai/unified
  • /api/agent/runtime
  • /api/agent-control
  • /api/approvals
  • /api/agent/approvals
  • /api/integrations/telegram
  • /api/skills
  • MCP and plugin governance endpoints from cocoagent.api.mcp

The production image exposes the backend on container port 3099 and serves the built frontend from /app/public.

Frontend

Main frontend routes live in frontend/src/router/modules/ai.ts. The visible control-plane menu currently includes:

  • Unified chat: /ai/agent
  • Tools and policy: /ai/tools-policy
  • LLM providers: /ai/providers
  • Skill management: /ai/skills
  • Agent configuration: /ai/agents
  • Telegram integration: /ai/integrations/telegram
  • Learning control: /ai/agent/control-plane/learning-evolution
  • Operations dashboard: /ai/agent/control-plane/operations

All frontend HTTP access must go through frontend/src/api/*.

Layering Contract

  • Frontend: View/Store -> frontend/src/api/* -> Backend API.
  • Backend: API -> Service -> DAO/Repository/DB.
  • Public API changes must update OpenAPI and generated frontend types in the same change set.
  • Database behavior changes must be backed by SQL migrations and tests.

Quick Start With Docker

The root docker-compose.yml uses the published image ghcr.io/btnalit/cocoagent-x:latest.

cp .env.example .env

# Edit at least:
# - PG_PASSWORD
# - JWT_SECRET and INTERNAL_API_KEY if you do not want the entrypoint to generate them

docker compose pull
docker compose up -d
docker compose ps
docker compose logs -f cocoagent

Default root compose ports:

  • Web UI and API: http://localhost:8080
  • Health check: http://localhost:8080/api/health
  • PostgreSQL: localhost:5432
  • Syslog UDP: 514
  • SNMP Trap UDP: 162

Important note for LLM provider variables:

  • The root compose file is a minimal prebuilt-image deployment file. It passes database, secrets, and runtime flags into the container.
  • If you run AI chat in that compose file, add the provider variables you need under services.cocoagent.environment or use the source-build compose below, which already forwards provider variables such as AI_PROVIDER, GEMINI_API_KEY, OPENAI_API_KEY, CLAUDE_API_KEY, and DEEPSEEK_API_KEY. Add other provider keys there if you use them.

Source-Build Docker Compose

Use cocoagent-python/docker-compose.yml when you want Docker to build the image from this checkout:

cp .env.example .env
docker compose -f cocoagent-python/docker-compose.yml up --build -d

This path builds the frontend with Node 20, installs the Python backend, copies the frontend dist into /app/public, and then starts Uvicorn inside the production image.

Local Development

Prerequisites:

  • Python 3.12+
  • Node 20.x
  • Docker with Compose

Install dependencies:

npm --prefix frontend install

cd cocoagent-python
pip install -e ".[dev]"
cd ..

Start PostgreSQL:

docker compose up -d postgres

Run backend and frontend in separate terminals:

npm run dev:backend
npm run dev:frontend

Local URLs:

  • Frontend dev server: http://127.0.0.1:5173
  • Backend API: http://127.0.0.1:3099
  • Health: http://127.0.0.1:3099/api/health

Telegram Integration

Telegram is configured from the frontend at /ai/integrations/telegram.

Typical local setup:

  1. Create a bot in BotFather and copy the Bot token.
  2. Open Telegram integration in Cocoagent.
  3. Create a Bot connection. The UI stores the token as write-only data and automatically enables local long polling.
  4. Create or select an Agent and save the default binding.
  5. Send a message to the bot in Telegram.

Local long polling:

  • Does not require a public HTTPS URL.
  • Uses Telegram getUpdates.
  • Is the default path for local/private deployments after creating a connection in the UI.
  • Controlled by TELEGRAM_POLLING_RUNNER_ENABLED, TELEGRAM_POLLING_INTERVAL_SECONDS, TELEGRAM_POLLING_TIMEOUT_SECONDS, and TELEGRAM_POLLING_LIMIT.

Production webhook mode:

  • Requires a public HTTPS base URL that reaches the Cocoagent backend.
  • The UI can register/delete the Telegram webhook for a connection.
  • The backend receives updates at /api/integrations/telegram/webhook.
  • Webhook and long polling are mutually exclusive for the same bot.

Useful Telegram environment variables:

  • TELEGRAM_ALLOWED_USERS
  • TELEGRAM_GROUP_ALLOWED_CHATS
  • TELEGRAM_REQUIRE_MENTION
  • TELEGRAM_BOT_USERNAME
  • TELEGRAM_REPLY_PARSE_MODE
  • TELEGRAM_WEBHOOK_SECRET

Real Telegram end-to-end validation still requires a real BotFather token and a Telegram client.

Key Environment Variables

Reference files:

  • Root deployment example: .env.example
  • Backend-focused example: cocoagent-python/.env.example

Common variables:

  • APP_ENV
  • PORT
  • DATABASE_URL or PG_USER / PG_PASSWORD / PG_HOST / PG_PORT / PG_DATABASE
  • JWT_SECRET
  • INTERNAL_API_KEY
  • AI_PROVIDER
  • Provider keys such as GEMINI_API_KEY, OPENAI_API_KEY, QWEN_API_KEY, ZHIPU_API_KEY
  • CORS_ORIGINS
  • HARNESS_RUNTIME_ENABLED
  • SUBAGENT_DISPATCH_ENABLED
  • AGENT_REACT_STATE_MACHINE_ENABLED
  • LANGGRAPH_RUNTIME_ENABLED
  • LANGGRAPH_POSTGRES_CHECKPOINTER_ENABLED

Production secret behavior:

  • cocoagent-python/docker-entrypoint.sh generates JWT_SECRET and INTERNAL_API_KEY in production when they are empty or weak.
  • Generated values are persisted to /app/data/runtime-secrets.env in the cocoagent-data volume.

Database Migrations

Migrations run during backend startup through:

  • cocoagent-python/src/cocoagent/bootstrap/startup_pipeline.py
  • cocoagent-python/src/cocoagent/data/migrations/runner.py

SQL files live under:

  • cocoagent-python/src/cocoagent/data/migrations/*.sql

Treat the migration directory as the source of truth. Recent migrations include AgentOS persistence, runtime state versions, memory assets, governance ledgers, action audit hash chains, and Telegram connection/webhook/polling tables.

In non-development environments, migration failure blocks startup.

Contracts, Tests, and Gates

Run these from the repository root unless noted otherwise.

OpenAPI contract:

npm run contract:sync
npm run contract:check

Frontend:

npm --prefix frontend run test
npm run lint
npm run build

Backend:

python cocoagent-python/scripts/run_backend_tests.py

Process gates:

python cocoagent-python/scripts/a36_global_process_hard_constraints_runner.py --profile lite
python cocoagent-python/scripts/a35_process_hard_constraints_runner.py --profile lite
python cocoagent-python/scripts/a34_release_go_nogo_runner.py --profile lite

Root shortcuts:

npm run gate:lite
npm run ci:lite

For larger or release-bound changes, use the stricter profiles required by the current task and process rules.

Repository Layout

cocoagent/
├── cocoagent-python/
│   ├── src/cocoagent/
│   │   ├── api/
│   │   ├── bootstrap/
│   │   ├── data/
│   │   │   └── migrations/
│   │   ├── services/
│   │   ├── main.py
│   │   └── settings.py
│   ├── scripts/
│   ├── tests/
│   ├── Dockerfile
│   ├── docker-compose.yml
│   └── pyproject.toml
├── frontend/
│   ├── openapi/
│   ├── src/
│   │   ├── api/
│   │   ├── router/
│   │   ├── stores/
│   │   └── views/
│   └── package.json
├── docker/
├── docker-compose.yml
├── package.json
├── .env.example
└── README.zh-CN.md

License

Apache License 2.0. See LICENSE.

About

No description, website, or topics provided.

Resources

Readme

License

Apache-2.0 license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages