# Authenticated A2A company research

**Status:** the software is installed separately, but paid AI generation is
**off until the operator provisions credentials and a daily limit**.
Nothing on this endpoint uses AI Gateway.

- Agent Card: https://rinatsultan.com/.well-known/agent-pro.json
- Endpoint: `POST https://rinatsultan.com/a2a/pro/v1`
- Protocol: A2A 1.0 / JSON-RPC 2.0 / synchronous `SendMessage`.
- Upstream: direct DeepSeek API at `https://api.deepseek.com/chat/completions`,
  model `deepseek-flash`, non-thinking JSON mode; only after configuration.
- Model access: private Bearer token in the HTTP `Authorization` header.
- Input: `company` and `website` (the actual official public HTTPS site).
  Optional: `industry`, `challenge`, `description`.
- Output: Markdown and/or structured JSON with relevant pilots, baseline KPIs,
  questions and evidence quotes. Not an audit, offer or guaranteed ROI.

## Safety and limits

- Authentication required before site fetching and before any paid model call.
- No credentials or tokens in Git, Agent Cards, browser JS or the request body.
- Public HTTPS hostnames on port 443 only; private IPv4 ranges and IP literals
  rejected. DNS results are checked and a public IPv4 is pinned for TLS
  requests; redirects are restricted to the same apex/www domain.
- At most three HTML pages, 300 KB HTML and 6,500 characters of visible text
  per page, no cookies or JavaScript execution; timeout per page.
- At most 3 requests/minute per IP, at most 2 simultaneous paid calls and
  a persistent, hard daily ceiling on attempts. Quota is reserved before
  website retrieval or the external model call; failed attempts consume quota.
- Provider request: fixed model, fixed URL, JSON-only, up to 2400 output tokens
  and a 25-second timeout. A2A does not publish pages, send messages, change
  settings or operate industrial equipment.
- Facts returned with a source link only if their exact quoted evidence
  is found in the extracted official page text. Nevertheless, a human
  must check business claims, safety implications and proposed KPI baselines.
- No sensitive company data should be submitted: information in the request
  and extracted public pages is sent to the selected model provider.

## Enable privately on the VPS (operator action)

**Never paste your keys into this chat or commit them to GitHub.**
Store the following environment values in the VPS outside the deployed repo,
at `/etc/rinatsultan/a2a.env` with mode `0600` (root-owned):

```ini
A2A_DEEPSEEK_API_KEY=YOUR_SECRET_DEEPSEEK_KEY
A2A_RESEARCH_ACCESS_TOKEN=YOUR_RANDOM_PRIVATE_TOKEN_AT_LEAST_32_CHARACTERS
A2A_RESEARCH_DAILY_LIMIT=10
```

Generate the A2A access token on the VPS with `openssl rand -hex 32`.
Restart the existing service with `sudo systemctl restart rinatsultan-mcp`.
This file is not in Git and is not touched by `rsync --delete`.
The daily reservation file is kept at `/var/lib/rinatsultan/a2a-research-usage.json`
across deployments. Configure an additional spend cap/alerts with the model
provider. Set `A2A_RESEARCH_DAILY_LIMIT=0` to disable paid research immediately.

## Sample request

```bash
curl -fsS https://rinatsultan.com/a2a/pro/v1 \
  -H 'Content-Type: application/json' \
  -H 'A2A-Version: 1.0' \
  -H "Authorization: Bearer $A2A_RESEARCH_ACCESS_TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "id": "company-1",
    "method": "SendMessage",
    "params": {
      "message": {
        "role": "ROLE_USER",
        "messageId": "research-1",
        "parts": [{"data": {
          "skillId": "company-ai-proposal",
          "company": "ПримерХлеб",
          "website": "https://example.org/",
          "industry": "хлебопекарное производство",
          "challenge": "Снизить списания и ускорить планирование выпуска"
        }}]
      },
      "configuration": {
        "acceptedOutputModes": ["text/markdown", "application/json"]
      }
    }
  }'
```

The example domain is illustrative, not a real company source.
Anonymous calls return HTTP 401; paid calls without operator configuration
return HTTP 503. The free, rule-based A2A agent at `/a2a/v1` remains available.

Run `npm run test:a2a:research` locally to exercise mock public pages, model
results, authentication, source verification and quotas without paid calls.