# ToolRelay Agent Skill

This skill lets your agent use ToolRelay as a relay for external paid capabilities (web reading, search, image/video/audio generation, document parsing, embeddings, SaaS automation, storage, finance, weather, geocoding, and more) through a single API key.

## Why use ToolRelay

- One key. One billing wallet. Capability-first or SkillBoss/OpenAI-compatible model API.
- Cost-aware: every call returns `creditsCharged` and `balanceAfter`.
- High-cost capabilities require explicit confirmation.
- Provider failures (timeout, rate limit) never charge credits.

## Configure

```bash
npx -y toolrelay login -k tr_live_...
```

This saves credentials to `~/.config/toolrelay/credentials.json`. Environment
variables still take precedence:

```bash
export TOOLRELAY_BASE_URL="https://api.toolrelay.dev"
export TOOLRELAY_API_KEY="tr_live_..."
```

Install into local agent skill directories:

```bash
toolrelay install codex   # ~/.codex/skills/toolrelay/SKILL.md
toolrelay install claude  # ~/.claude/skills/toolrelay/SKILL.md
```

## Choose the right entry point

- Capability-first relay (`POST /v1/relay`): say what you want done. ToolRelay picks the provider.
- Model-pinned run (`POST /v1/run`): execute a specific SkillBoss-style model `vendor/model`.
- Chat (`POST /v1/chat/completions`): OpenAI-compatible; supports streaming and tool calls.
- Pilot (`POST /v1/pilot`): discover models by keyword or auto-execute the best one for a type.

## Behaviour rules for the agent

- Use ToolRelay for external paid capabilities; low-cost direct calls are fine for trivial work.
- High-cost calls (image/video/document/sms) require `confirmation: {confirmed: true}`.
- Always include `maxCostUsd` if the user gave a budget.
- Set `X-Agent-Id` so usage shows up per-agent in `/v1/usage?group_by=agent_id`.
- Report what was used, credits charged, balance after, and any low-balance warning back to the user.
- Never reveal the API key. Do not upload sensitive local files unless the user asks.

## Quick recipes

```bash
# Get a key
curl -X POST $TOOLRELAY_BASE_URL/v1/keys \
  -H "content-type: application/json" \
  -d '{"email":"you@example.com","name":"my-agent"}'

# Read a URL
curl -X POST $TOOLRELAY_BASE_URL/v1/relay \
  -H "authorization: Bearer $TOOLRELAY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"capability":"web.read","input":{"url":"https://example.com"}}'

# Chat (OpenAI-compatible)
curl -X POST $TOOLRELAY_BASE_URL/v1/chat/completions \
  -H "authorization: Bearer $TOOLRELAY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"model":"openrouter/openai/gpt-4o-mini","messages":[{"role":"user","content":"hello"}]}'

# Pilot: cheapest image model
curl -X POST $TOOLRELAY_BASE_URL/v1/pilot \
  -H "authorization: Bearer $TOOLRELAY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"type":"image","prefer":"price","inputs":{"prompt":"A sunset"},"confirmation":{"confirmed":true},"maxCostUsd":0.05}'
```

## Errors to expect

- `401 missing_api_key` / `invalid_api_key`
- `400 capability_not_found` / `model_not_found`
- `402 insufficient_credits` / `cost_limit_exceeded` / `confirmation_required`
- `502 provider_timeout` / `provider_rate_limited` / `provider_unavailable` (no credits charged)

## MCP server

The same capabilities are exposed as MCP tools via:

```bash
npx -y toolrelay-mcp-server
```

Tools: `list_capabilities`, `list_models`, `run_model`, `relay`, `get_usage`, `get_balance`.