How agentscope-ai/copaw works
1. Project shape
CoPaw is a Python-first assistant platform with three major faces: a backend runtime under src/copaw, a React/Vite web console in console/, and a documentation site in website/. The backend is the product core; the frontend and docs are separate build targets that get packaged alongside it.
2. Entry points and process model
The main user-facing entry points are the CLI (src/copaw/cli) and the app/server runtime (src/copaw/app). The CLI covers install/init/admin workflows, while the app runtime starts the API, background services, channel integrations, and agent execution. Docker and desktop packaging wrap the same backend runtime for different deployment modes.
3. API boundary
src/copaw/app/routers is the HTTP API surface consumed by the console. It exposes domains such as agents, auth, settings, files, workspace, skills, tools, providers, local models, token usage, voice, and chat/messages. The frontend’s console/src/api/* mirrors these routes, so the console is a thin client over the backend rather than an independent stateful app.
4. Agent execution core
The src/copaw/agents package contains the reasoning and execution layer: agent prompts, model selection, routing/chat model logic, memory managers, skills loading, schema definitions, and tool dispatch. This is where user requests are turned into agent actions, tool calls, and responses. react_agent.py and related modules suggest a tool-using, iterative agent loop at the center of the runtime.
5. Models and provider abstraction
src/copaw/providers abstracts LLM backends across cloud and local runtimes. It includes provider-specific adapters for OpenAI, Anthropic, Gemini, and Ollama, plus compatibility wrappers, retries, rate limiting, and multimodal probing. src/copaw/local_models handles local model download and execution via llama.cpp-style workflows, giving the system a no-API-key deployment path.
6. Skills as the main extension mechanism
Skills live under src/copaw/agents/skills as markdown-defined capabilities, often with scripts, schemas, or reference assets alongside them. The platform supports built-in skills, hub/import flows, and skill pool management in both backend and console. This is a major boundary: the assistant’s capabilities are expanded by loading skills, not by hardcoding every behavior into the agent core.
7. Tooling and side-effect boundaries
Tool execution is isolated in src/copaw/agents/tools. The tool set covers file I/O, shell, browser control, screenshots, media viewing, file search, memory search, time, token usage, and file sending. This layer is the main bridge from language-model decisions into real-world side effects on the local machine or workspace.
8. Channels and multi-channel ingress
src/copaw/app/channels normalizes external message sources into one internal conversation model. It supports the built-in console channel plus third-party integrations such as DingTalk, Feishu, WeCom, WeChat, QQ, Telegram, Discord, Matrix, Mattermost, MQTT, iMessage, voice, and others. The channel manager/registry/renderer layers are the boundary between platform-specific messaging APIs and CoPaw’s shared agent runtime.
9. State, workspace, and persistence
Local state is organized around the working directory, env store, workspace services, agent context, and JSON-backed repositories. Configuration and secrets are kept separate, and the README/Docker setup emphasizes persistent volumes for working data versus secrets. This is the main data persistence boundary: configuration, memory, skills, and workspace artifacts are stored locally and reused across restarts.
10. Scheduling, background work, and multi-agent coordination
src/copaw/app/crons manages scheduled jobs and heartbeats, while src/copaw/app/runner handles background task execution, command dispatch, and task tracking. src/copaw/app/multi_agent_manager.py and related code support multiple agents running independently and collaborating. These subsystems turn CoPaw from a single chat loop into a long-running orchestration system.
11. Security gates
CoPaw adds security at multiple layers: security/tool_guard blocks dangerous shell/file operations, security/skill_scanner scans skills for risky patterns, and app/approvals provides an approval flow. Security is not centralized in one place; instead, it guards the main effectful boundaries where skills, tools, and file access can impact the host system.
12. Frontend and docs packaging
The console/ app is a TypeScript/React UI for chat, settings, agent configuration, models, skills, channels, workspace, and token usage. The website/ app is a separate public documentation/marketing site with static docs, release notes, and search. In packaging terms, the console is built and copied into the Python package, while the website is deployed independently.
13. Deployment/runtime surfaces
The repo supports pip install, Docker, desktop packaging, and hosted deployment. deploy/ contains container entrypoints and supervisord setup, scripts/ contains build/install/release helpers, and GitHub Actions automate testing, PyPI publishing, Docker releases, and website deployment. A tunnel/ package exists for connectivity/relay scenarios, indicating optional external network exposure.
14. Primary end-to-end flow
A typical flow is: user enters through the console or a chat channel → backend router/channel normalizes the request → agent runtime selects a model/provider and loads context/skills → tools execute against local resources or external services → results are persisted in workspace/memory and returned to the channel/UI. That loop, plus the security gates and background schedulers, is the core architecture to diagram.
Main entry points: app App runtime · agents Agent core · workflows CI releases · security Security gates
Components 19
Python backend
Core runtime, CLI, APIs, agents, providers, security, and persistence.
- CLI · Install, init, auth, daemon, and admin workflows.
src/copaw/cli - App runtime · Starts API, channels, background work, and agent execution.
src/copaw/app - HTTP API · Backend routers consumed by the console and external clients.
src/copaw/app/routers - Channels · Normalizes console and third-party messaging platforms into conversations.
src/copaw/app/channels - Agent core · Prompts, routing, memory, skill loading, and tool dispatch.
src/copaw/agents - Skills · Markdown-defined capabilities and packaged scripts/reference assets.
src/copaw/agents/skills - Tools · File, shell, browser, media, search, memory, and token-usage actions.
src/copaw/agents/tools - Providers · Cloud and local model adapters with retries, limits, and probing.
src/copaw/providers - Local models · Downloads and runs local models for no-key deployments.
src/copaw/local_models - Workspace state · Configuration, env store, workspace services, and local data reuse.
src/copaw/app/workspace - Runner + crons · Background task execution, scheduling, heartbeats, and task tracking.
src/copaw/app/runner - Multi-agent · Coordinates multiple agents and independent sessions.
src/copaw/app/multi_agent_manager.py - Security gates · Tool guard, skill scanning, and approval flow around effectful actions.
src/copaw/security
Web console
React/Vite UI used as a thin client over backend routers.
- Console UI · Chat, settings, skills, models, channels, workspace, and usage screens.
console/src - Console API client · Mirrors backend routers and powers the UI data flows.
console/src/api
Docs site
Public documentation and marketing site.
- Docs site · Public docs, release notes, search, and marketing pages.
website/src
Packaging
Docker, desktop, scripts, and CI/CD release surfaces.
- Docker · Container entrypoints and supervisord wrapping the backend runtime.
deploy - Desktop packaging · Desktop build and bundle scripts for shipped installs.
scripts/pack - CI releases · Build, test, publish, and website deployment workflows.
.github/workflows
Connections 22
- CLI → App runtime: starts · CLI launches or manages the backend runtime.
- App runtime → HTTP API: serves · Runtime exposes HTTP routes for console and integrations.
- App runtime → Channels: hosts · Runtime runs channel adapters and queueing.
- App runtime → Agent core: executes · Runtime hands normalized messages to the agent loop.
- Agent core → Skills: loads · Agent core discovers and uses skills as capabilities.
- Agent core → Tools: invokes · Agent decisions dispatch into effectful tools.
- Agent core → Providers: selects models · Routing and model selection go through provider abstraction.
- Providers → Local models: falls back to · Provider layer can route to local model runtime.
- App runtime → Workspace state: persists to · Runtime stores config, workspace, and local state.
- Runner + crons → Agent core: triggers · Background tasks can start or resume agent work.
- Multi-agent → Agent core: coordinates · Multiple agents share the same execution core.
- Security gates → Tools: guards · Tool execution is filtered through policy and approvals.
- Security gates → Skills: scans · Skills are checked for risky patterns before use.
- Console UI → Console API client: calls · UI uses typed API modules as its backend client.
- Console API client → HTTP API: consumes · Console client mirrors backend route domains.
- Docs site → CI releases: deployed by · Docs site has its own build and deployment path.
- Docker → App runtime: wraps · Container image packages the same backend runtime.
- Desktop packaging → App runtime: bundles · Desktop packaging ships the backend runtime with assets.
- CI releases → Console UI: builds · CI validates and builds the console frontend.
- CI releases → Docker: publishes · CI produces Docker release artifacts.
- CI releases → Desktop packaging: packages · CI builds desktop distribution artifacts.
- CI releases → Docs site: deploys · CI deploys the public website.