# SlashAgents Convention v0.1 (Draft)

## 1. Purpose

SlashAgents defines a simple convention for publishing a runtime guide for AI agents at a predictable path.

## 2. Discovery

### 2.1 Canonical path

For an API base URL, providers SHOULD expose:

- `GET /agents`

Example:

- Base URL: `https://api.example.com`
- Discovery URL: `https://api.example.com/agents`

### 2.2 Optional compatibility paths

Providers MAY additionally expose:

- `/.well-known/agents`
- `/.well-known/agent-api`

If exposed, they SHOULD return the same content as `/agents` or redirect to `/agents`.

## 3. Response format

`/agents` should return plain text.

Recommended header:

- `Content-Type: text/plain; charset=utf-8`

Markdown-style formatting is acceptable as long as the response remains plain text.

## 4. Relationship to OpenAPI and docs

SlashAgents is complementary and is not a replacement.

- `/openapi.json` defines endpoint contracts and schemas.
- `/docs` provides human-facing API exploration.
- `/agents` provides runtime operating guidance for autonomous agents.

## 5. Suggested sections (not required)

The following sections are suggestions only. Providers can include any subset and add custom sections.

- `Context`: extra context and assumptions for safe operation
- `Auth`: how to authenticate and get tokens
- `Base URLs`: production/sandbox environments
- `Versioning`: current version and deprecation windows
- `Limits`: rate limits, concurrency, quotas
- `Retries`: retryable failures and backoff guidance
- `Idempotency`: safe replay instructions
- `Pagination`: cursor/offset behavior
- `Errors`: concise error taxonomy and meanings
- `Specs`: links to OpenAPI and docs
- `Runtime`: health/status, incidents, recovery runbook

## 6. About context

`Context` is intentionally free-form. It can include:

- What this API is optimized for
- Operational constraints and workload expectations
- Safety/compliance boundaries
- Known edge cases and recommended client behavior

This helps agents make better decisions than schema-only integration.

## 7. Optional JSON companion

Teams MAY publish `/agents.json` for stricter machine parsing.

- `/agents` (plain text) remains canonical in this convention.
- `/agents.json` is optional and should mirror the same guidance.
- JSON keys are suggestions, not required fields.

## 8. Plain-text example

```text
SlashAgents-Version: 0.1
API: Example Payments API

Context:
- This API is optimized for low-volume, high-value payment operations.
- Prefer sequential writes over burst concurrency.
- During bank cutoff windows, latency may increase.

Auth:
- OAuth2 Client Credentials
- Token endpoint: https://auth.example.com/oauth/token

Base URLs:
- Production: https://api.example.com
- Sandbox: https://sandbox-api.example.com

Versioning:
- Header: X-API-Version
- Default: 2026-01-01

Limits:
- Soft target: 20 req/s
- Burst: 40 req/s
- Recommended in-flight writes per account: <= 2

Retries:
- Retry 408/429/5xx with exponential jitter
- Respect Retry-After when present

Idempotency:
- Use Idempotency-Key on write operations
- Reuse same key when retrying after timeout

Pagination:
- Cursor-based with `cursor` and `limit`
- Max limit: 100

Specs:
- OpenAPI: https://api.example.com/openapi.json
- Docs: https://api.example.com/docs

Runtime:
- Status: https://status.example.com/api/summary
- Recovery: replay timed-out writes with same idempotency key
```

## 9. Security considerations

- Do not include secrets in `/agents`.
- Keep sensitive internal topology out of public profiles.
- If needed, publish a reduced public guide and a richer authenticated guide.