Skip to content

Calling agents from code ​

An API key lets a script, a CI job or another app ask your agents something and get the answer back, as you: with your access to agents, your connected accounts, your budgets and limits.

Making a key ​

Account → API keys: name it after what will use it ("Release CI"), choose when it expires (30 days, 90 days, a year, or never), and Create key. The key starts with chk_ and is shown once: copy it into your script's secrets. CrewHall keeps only a fingerprint of it, and shows its first characters so you can tell your keys apart, with when each was last used.

Delete a key to revoke it: whatever uses it stops at once. A key stops working when it expires, when your account is disabled, or if you delete your account.

A key only talks to agents. It can't change your account, make other keys, or approve anything.

Asking an agent ​

bash
curl https://crewhall.example.com/api/v1/ask \
  -H "Authorization: Bearer $CREWHALL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent": "acme/release-notes", "message": "What changed since v1.4?"}'

agent is the agent's address, space/slug as in its page's URL, or its slug alone when only one of your agents has it, or its id. The answer comes back when it's written:

json
{
  "conversation_id": "01a1…",
  "run_id": "01a1…",
  "status": "done",
  "answer": "Three things changed…",
  "error": null,
  "input_tokens": 1830,
  "output_tokens": 412
}

status is done, failed (with error) or stopped (someone pressed Stop in the app).

  • Carry on in the same conversation: send its conversation_id with the next message. Without one, each call starts a new conversation.
  • Stream the answer as it's written: add "stream": true. You get the same events as the app, as server-sent events: run, then delta (text), tool_start and tool_end, approval, and finally done, error or stopped.
  • Read a conversation: GET /api/v1/conversations/<id> returns its messages.
  • List your agents: GET /api/v1/agents, with each one's ref to use as agent.

Conversations started with a key are ordinary ones: they're in your chat list in CrewHall, where you can read them or carry on.

Writes that ask first ​

When the agent wants to change data in an integration that asks first, nobody is watching the call, so you're notified (under the bell, and by email or Telegram if you chose so) and decide in the conversation, or with the Telegram buttons. The call waits for your decision, up to an hour; then the write is skipped and the agent says so.

What's recorded ​

Creating and deleting a key is recorded like other changes to your account, and each call is in the agent owner's audit log with the key's name. What the agent does costs what it would in the app, and counts against the same budgets.

Keep it secret

Anyone with your key can talk to your agents as you, including agents that read your connected accounts. Keep it in a secret store (your CI's secrets, a password manager), not in code, and delete it when you stop using it.

CrewHall