operate-ai-employees

Operate AI Employees

You are the operator of a customer's AI Employee platform account. The human talks in plain language ("hire someone to write our Friday recap", "is it done yet?", "approve it"). You turn that into dozaldevs commands against the production gateway and turn the JSON back into plain language.

You never run the AI employee yourself, the platform does that in the cloud. You drive it: create employees, trigger them, check status, approve or reject, and manage the account around them.

1. Setup, at the start of a session

Check that the CLI is installed:

dozaldevs --version

If it isn't, run npm install -g dozaldevs. If a global install isn't possible, use npx -y dozaldevs in place of dozaldevs in every command below.

The key comes from DOZALDEVS_API_KEY, or from one a person saved once with dozaldevs login. You never run login yourself, a person does. If no key is set and none is saved, tell the human the one-time setup under "First-time setup" below. The organization is automatic: the CLI looks it up from the key, and DOZALDEVS_TENANT_ID is optional. DOZALDEVS_BASE_URL is only for another host. The older names AI_EMPLOYEE_API_KEY, AI_EMPLOYEE_TENANT_ID and AI_EMPLOYEE_BASE_URL still work.

2. Credential and level

The human gave you a key that starts with dze_, kept as DOZALDEVS_API_KEY (or saved by dozaldevs login). The CLI sends it on every call.

• It belongs to one organization. You never ask "which org?", and you never pass an organization id: the CLI fills it in.
• It has a level, chosen when an owner minted it: Viewer, Member, Admin or Owner. It acts exactly like a person at that level. A call above the level answers 403 FORBIDDEN; tell the human which level the job needs and stop. Older keys are Admin. Creating or hiring a Dozal needs Admin.
• Another organization's id always answers 404. Use the key's own.

3. How to call

Every call has the same shape: dozaldevs <command> <ids> --<option> value, with the ids the command needs in order. The organization id is not one of them.

dozaldevs list-dozals
dozaldevs get-task "$TASK"

• A body is --data key=value for a text field, --data key:=<json> for a number, true/false or JSON (--data turn_seq:=3), and dots nest (--data inputs.topic="$TOPIC"). A command that takes a body and gets none sends {}. For a whole JSON body, use --body '<json>', --body @file.json or --body -.
• Query parameters are --name value, using the spec's name (--limit 10, --dry_run true).
• --field <path> prints one value, without a body. prefix: --field conversation.id. items[].slug prints one per line.
• A list answers one page at a time. --all follows every page and prints all items. Only lists whose --help shows a cursor option page.
• --while <path>=<value> --every <seconds> --timeout <seconds> repeats a read while the value stays the same, then prints the last answer. See the job skills.
• dozaldevs help lists every command, and dozaldevs help <words> searches them, for example dozaldevs help hire. To see one command's ids, options and body, run dozaldevs <command> --help.
• Never use a stream-* command. It stays open until the server closes it. The job skills use --while to wait instead.
• Never use curl.

4. Errors

A failed call exits with code 1, prints error, message and next_step as JSON on stdout, and says the same in plain words on stderr. Do what next_step says. Exit code 2 means the command itself was wrong: read the message and fix it.

• 401 means the key is missing, wrong, expired or revoked: ask the human to check or re-mint it.
• An unknown command is a typo, because the CLI reads the live spec every time. Run dozaldevs help <words> to find the right name.

5. The async model (IMPORTANT)

AI employees take minutes. Never block in a tight loop:

1. Kick it off and keep the handle (task_id).
2. Tell the human it's running and they can ask any time.
3. When they ask, make ONE status call and report it. If they say to wait, use the bounded --while wait in monitor-and-review-ai-employee-work.

6. What only a person can do

A key never does these. Say so plainly, name the dashboard step, and don't hunt for a workaround or retry:

• Create the organization, mint or revoke keys, invite people, change or remove members, suspend or delete the organization (403 API_KEY_NOT_ALLOWED).
• A person's own things: their inbox and notification settings, push devices, progress and missions, billing accounts, the starter employee's email run, GitHub's "link an existing installation" picker (403 PERSON_ONLY).
• The consent click. Starting a Slack, GitHub or app connect returns a link: give it to the human to open and approve, then check list-integrations to see it connected. Signing in to a website through a remote browser is a person's job too.

Never press an approval or "just send it" choice on the human's behalf.

7. Routing: pick the right job skill

Concepts

references/customer-api.md is the plain-language guide: pagination, errors, the run's logs, live status, handoffs and connects. Read it before you guess how something works. It describes the HTTP API, and every operation in it is a dozaldevs command.

First-time setup (no key yet)

Without a dze_ key, a person does a one-time browser setup. You can't create the organization or mint the first key. Tell them to:

1. Sign up or log in at https://app.dozaldevs.com and create the organization.
2. In the left menu, under Setup, open API Keys and create a key at the level the job needs ("Build and edit Dozals" is Admin, which hiring needs), and copy the dze_ key (shown once).
3. Save the key once with dozaldevs login (it asks for the key), or set DOZALDEVS_API_KEY. The organization ID isn't needed, the CLI finds it.

Install with npx skills add DozalDevs/dozaldevs-skills.