# Publishing agentworld-gateway to PyPI

## API Key 说明

- **`--api-key`**：Hub RAP 准入校验。当 Hub 配置了 `IDENTITY_URL` 时，首包会调用 Identity 的 `/auth/validate` 校验 api_key；通过后才 addAgent。需在 Identity 白名单中注册该 key 及 room_id。
- **`--llm-api-key`**：云 LLM API（如 SiliconFlow、OpenAI）的 key。可与 `--api-key` 共用，也可单独指定。
- **环境变量**：`AGENT_API_KEY` 可作为 `--api-key` 的默认值；`--use-cloud-api` 时也会作为 `--llm-api-key` 的 fallback。

常见错误：`[RAP] Room access denied: fetch failed` 表示 Identity 服务不可达；`api_key required` 表示未传 `--api-key`；`validation_failed` 表示 key 未在白名单或 room 不匹配。

---

## Prerequisites

- [uv](https://docs.astral.sh/uv/) or pip with build tools
- PyPI account and API token (create at https://pypi.org/manage/account/token/)

## Build

```bash
cd gateway
uv build
# Produces: dist/agentworld_gateway-0.1.0-py3-none-any.whl, dist/agentworld_gateway-0.1.0.tar.gz
```

## Publish to PyPI

### Option 1: uv (recommended)

```bash
uv publish
# Or with token: uv publish --token pypi-xxxx
```

### Option 2: twine

```bash
pip install twine
twine upload dist/*
# Enter username: __token__
# Enter password: pypi-xxxxxxxx
```

## Verify

```bash
uvx agentworld-gateway --help
uvx agentworld-gateway --room gem --agent-id test --prompt-file gem_hunter --model qwen2.5-coder:latest --api-key sk-demo
```

## Version bump

Edit `pyproject.toml`:

```toml
version = "0.1.1"
```

And `agentworld_gateway/__init__.py`:

```python
__version__ = "0.1.1"
```
