Test mode
A test key (agy_test_) is a key for development traffic: it reaches every
endpoint, every error and every webhook a live key does, under a tighter rate
limit — so a runaway loop in development hits a 429 instead of your
production budget.
Mint one from the same place as a live key; the prefix tells you which you are holding.
What changes
Only the rate limit.
agy_test_ | agy_live_ | |
|---|---|---|
| Default rate limit | 300 requests/minute | 1,200 requests/minute |
Test keys share their own ceiling, separate from the live one: all test keys of
an account together get 300 requests a minute by default, and the same account's
live traffic keeps its full budget. The exact figures for your deployment are in
x-agentency-rate-limits in the OpenAPI document.
What does not change
Everything else. Scopes, the error envelope, idempotency, version headers, pagination, webhook signing — identical. That is the point: an integration that works against a test key works against a live one, with no code differences.
A test key reads and writes your real account, and its chat turns spend the same message credits as a live key's. It will happily delete a real chatbot. If you want somewhere disposable, create a chatbot for the purpose rather than assuming the key protects you, and keep test traffic small.
A development setup that works
- Create a chatbot named something obvious like "Dev — do not use", and do your experimenting there.
- Use a test key locally and in CI. Keep the live key out of both.
- Register a
test-mode webhook endpoint pointing at a tunnel to your machine. - Seed one small knowledge source. A short text dataset trains in seconds, where a large PDF makes every test slow.
- Point staging at its own test key, so revoking a developer's key does not break the shared environment.
Webhooks in development
Webhook URLs go through the same safety checks in both modes: internal addresses and private ranges are refused, because a URL that looks harmless in development is a way into the network in production.
For local work, use a tunnelling service so your machine has a real public
HTTPS URL. Register that as an endpoint with mode: test. The mode is a label
for your own bookkeeping: test and live endpoints receive the same events, and
both need HTTPS. Signature verification behaves exactly as it will in
production, which is what you want — the failure mode you most need to rehearse
is a verifier that rejects valid deliveries.
POST /v1/webhook_endpoints/{id}/test sends a ping through the real
pipeline, so you can confirm the whole path without waiting for something to
happen.
Moving to live
- Mint a separate live key. Do not promote the test key you have been pasting into terminals.
- Grant the same scopes — no more, and check whether any were only needed for experimenting.
- Register your production webhook endpoint, and delete the test one that points at your machine — it receives every event too.
- Re-check your rate handling: the live limit is higher, so a bug that showed up as 429s in development may not show up until production load.
See Going live for the full checklist.
Common mistakes
- Assuming test data is isolated. It is your real account.
- Testing with an unrealistically small dataset. Training time and answer quality both change with volume; a one-paragraph source teaches you little.
- Only ever seeing the happy path. Force a
429, an expired key, and a webhook signature failure at least once before launch. - Forgetting the production webhook endpoint. A common launch-day surprise: the integration works, but every event is still delivered to a tunnel on a laptop.
What's next
- Authentication — key formats and rotation.
- Webhooks — receiving events locally.
- Going live — the switch to a live key.