For developers

How an assistant gets connected

1. The owner adds the assistant

   In Agen Keys: Assistants → Add an assistant, then Copy message on the assistant’s Setup page. The message looks like this:

   Setup message (example)Copy

   Set up Agen Keys for me: https://keys.example/u/your-name/openapi.json
   Start with the x-agen-setup section in that file.

2. The assistant reads the owner’s address

   The message points to the owner’s personal address, /u/<slug>/openapi.json. Start with its x-agen-setup section: it has the full, current setup steps. Every assistant the owner adds uses this same address, each with its own key.

3. The owner reveals the key when asked

   The owner chooses Reveal access key and pastes the key into the chat or the assistant’s settings. Agen Keys shows it only once; if it gets lost, the owner removes the assistant and adds it again.

4. The assistant sends the key on every request

   Every request to that address carries this header:

   Authorization: Bearer <access key>

   There is no token exchange and the key does not expire. Removing the assistant in Agen Keys deletes its key, and the address stops accepting it.

Calling tools

GET /v1/tools

Lists what the assistant may use. It is also the connection check: an empty list means it is connected, but nothing is usable yet.

POST /v1/tools/call-tool

Every connector tool goes through here, with this body:

{"toolName": "…", "input": {…}}

POST /v1/tools/<name>

Built-in tools, each at its own path. Sending one through call-tool fails with tool_not_found.search-toolslist-connected-integrationslist-available-integrationsget-integration-auth-urlget-large-response

get-integration-auth-url

Returns a link. The assistant gives it to the owner, who opens it to connect a service.

When a request fails

• 401
  authentication_requiredassistant_removedgateway_error

  Agen Keys no longer accepts this access key, most likely because the owner removed the assistant. Don’t retry and don’t guess why. Tell the owner what is quoted below. gateway_error can also come back as 403, 429 or 502, and the call may already have reached the gateway, so never retry a POST on your own; on 429, wait before any retry.

  “Agen Keys isn't accepting my connection anymore; maybe I was removed there. Please add me again: open Agen Keys, go to Assistants, choose Add an assistant, and send me the new access key.”

  Copy

• 503
  verification_unavailableauth_verification_unavailableroute_store_unavailable

  Agen Keys couldn’t check the key right now; the key itself is fine and the call did not run. Wait a few seconds and retry, at most twice, then tell the owner Agen Keys isn’t answering.

• 504
  delivery_unknown

  The tool may have run, but its answer was lost. Never retry a POST automatically: check the result first, or tell the owner.