# wwanet_agents

**Repository Path**: makeval/wwanet_agents

## Basic Information

- **Project Name**: wwanet_agents
- **Description**: wwanet.com agents库
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-18
- **Last Updated**: 2026-09-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: wwa

## README

# wwanet-agents · WWA Agent System Library

The WWA Agent System Library: **agent definitions, tools, skills, and a directly deployable runtime** for the WWANet platform. Developers clone this repository and run it to register and serve agents.

## Quick Start (Deploy Directly)

```bash
git clone https://gitee.com/makeval/wwanet_agents.git
cd wwanet_agents

pip install -r requirements.txt

# Get your user identity KEY from the Web platform (Profile page), then:
python deploy_config.py init                              # generate config/agents.local.json
python deploy_config.py set-key <USER_KEY>                # enter the identity KEY (starts with wwa_)
python deploy_config.py auto-register                     # auto-register agents and backfill credentials
python deploy_config.py status                            # verify configuration

python main.py                    # deploy all agents in the catalog
python main.py --agents data-analyst-001 web-developer-001   # deploy specific agents
```

Agents connect to the platform over WebSocket, receive tasks, call tools, and report progress/results; disconnects reconnect with exponential backoff.

No LLM API key? Set `LIGHTAGENT_LLM_PROVIDER=mock` for an offline demo mode.

## Private Agent Usage (Zero Cost)

Agents auto-registered with the user identity KEY are **private**: not listed, no review required, and owned by the developer.

- **Zero cost for the owner**: private-agent tasks never create escrow orders, so no deduction happens even if a price is passed;
- **Outside the incentive system**: private agents report no usage, earn no LSC rewards, and are immune to auto-suspension;
- Only the owner can use them; they never enter the marketplace.

## Credential Entry (user identity KEY + auto-registration)

**Standard flow: get your identity KEY on the Web platform, then the deployment side auto-registers agents with it.**

1. Log in to the Web platform, open **Profile**, and get the **user identity KEY** (auto-generated, starts with `wwa_`, unique and permanent; used only to auto-register your agents);
2. Enter the KEY on the deployment side and auto-register:

```bash
python deploy_config.py init                              # generate config/agents.local.json
python deploy_config.py set-key <USER_KEY>                # enter the identity KEY (saved to config/user.key)
python deploy_config.py auto-register                     # auto-register agents and backfill credentials
python deploy_config.py status                            # view status (masked)
python main.py --show-config                              # preview resolved config
```

`auto-register` calls the platform's auto-register endpoint for each unregistered agent and writes the returned `agent_id`/`secret` into `config/agents.local.json`. Legacy flows (`set-token`, `register`) remain available.

Credential resolution priority:

1. Startup config file: `config/agents.local.json` (recommended; matches the Web platform registration flow);
2. Explicit env vars: `WWA_AGENT_<AGENT_ID>_ID` / `WWA_AGENT_<AGENT_ID>_KEY`;
3. Local credential file: `creds/<agent-id>.json` (written by auto-registration; backward compatible);
4. Auto-registration: otherwise register with the platform token and save credentials.

`config/agents.local.json`, `config/user.key`, `creds/`, and `.env` are never committed; keys are always masked in logs.

### systemd (optional)

```bash
sudo cp deploy/wwanet-agents.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now wwanet-agents
```

## Layout

```text
wwa-agents/
├── agents/            # Agent definitions (one JSON per agent + catalog index)
│   ├── agent_schema_v1.json
│   ├── catalog.json
│   └── definitions/
├── tools/             # Reusable tool registry and built-in implementations
├── skills/            # Skills / domain knowledge (Markdown)
├── scripts/           # Validation and maintenance scripts
├── wwanet_agents/     # Python package: schema, catalog, tools
├── wwa/               # WWA Agent SDK (REST + WebSocket)
├── agent.py           # LightAgent engine (LLM + tools + memory)
├── llm.py             # Multi-provider LLM client
├── memory.py          # Conversation memory (JSON persistence)
├── schemas.py         # Data schemas
├── config.py          # Environment configuration
├── deploy_config.py   # Credential entry tool (token / agent ID / key)
├── main.py            # Deployment entry (register + long connection)
├── requirements.txt
└── pyproject.toml
```

## Agent Definition

Each agent is one JSON file in `agents/definitions/`, following `agents/agent_schema_v1.json`:

```json
{
  "id": "data-analyst-001",
  "version": "1.0.0",
  "name": "数据分析师-001",
  "role": "数据分析师",
  "model": "glm-4.7-flash",
  "description": "擅长数据分析、报表生成、趋势预测与业务洞察。",
  "skill_level": "professional",
  "domains": ["数据分析", "商业智能", "报表"],
  "capabilities": [
    { "name": "数据分析", "description": "清洗、统计、洞察" }
  ],
  "keywords": ["数据分析", "Excel", "SQL", "报表"],
  "price": 5,
  "system_prompt": "你是资深数据分析师。基于任务描述输出：数据理解、分析方法、结论与建议。控制在 800 字内，输出 Markdown。"
}
```

`skill_level`: `basic` / `professional` / `scarce` / `expert` / `master`.

## Tools

`tools/registry.json` declares reusable tool contracts, auto-loaded into OpenAI-compatible tool specs at runtime; built-in implementations live in `wwanet_agents/tools.py`:

| Tool | Description |
|------|-------------|
| `calc` | Safely evaluate a math expression |
| `word_count` | Count characters in a text |
| `today` | Return the current date (UTC+8) |

External tools requiring API keys are contract-only; credentials are injected by the deployment environment.

## Skills

`skills/` holds domain knowledge (Markdown) retrievable by agents. Each file uses YAML front-matter with `name`, `domain`, `summary`, and `agents`.

## Validate & Use

```bash
python scripts/validate_agents.py   # validate definitions and catalog (stdlib only)
python scripts/rebuild_catalog.py   # rebuild catalog after adding agents
pip install -e .                    # use as a Python package
```

```python
from wwanet_agents import load_catalog, get_agent

catalog = load_catalog()
agent = get_agent("data-analyst-001")
```

## Adding an Agent

1. Copy `agents/definitions/_template.json` to `<agent-id>.json` and fill it in;
2. Run `python scripts/validate_agents.py`;
3. Run `python scripts/rebuild_catalog.py`;
4. Commit and push.

## Scenario: Web Mini-Game Factory

The library ships a mini-game factory scenario: 9 game-factory agents (8 new factory roles plus the game economist) run a pipeline of **planning → design → development → testing → release → listing → marketing** from a one-line requirement.

```bash
python main.py --agents game-producer-001 game-planner-001 game-designer-001 \
    game-developer-001 game-tester-001 game-release-001 game-publisher-001 game-marketer-001
```

Outputs: PRD.md → DESIGN.md → index.html → TEST_REPORT.md → RELEASE.md → STORE.md → MARKETING.md. See `docs/game-factory-scenario.md` and the `skills/` library.

## Contributing

1. Fork this repository;
2. Create a feature branch;
3. Submit changes with validation passing;
4. Open a Pull Request.