Skip to content

Virtual employees

A virtual employee is an assistant given a standing task: an instruction it carries out on its own, on a timetable or when someone presses Run now, as an account of its own with the rights you give that account, within limits on actions and time, and able to stop and ask a person before it acts. Every time it starts is a run, which people follow in the Cockpit. This page is for administrators: those who hold the organisation's administrator role.

A virtual employee can do exactly what its account may, and nothing more. The account is a service account of your organisation, one per assistant, which several virtual employees of that assistant share. Give the account only what the work needs.

Who may do what

Right on virtual employees What it gives
See List and read every virtual employee and account, and every run with its history and waits.
Use Run one now, stop and run again any run, answer every run's waits, switch one on and off.
Change Create and change a virtual employee, set up the account, change its monthly cap.
Delete Delete a virtual employee, or a finished run.

Administrators and operators hold all four, an auditor holds See, and members and people administrators hold none; give others a custom role. Without any right, people the virtual employee names for an event, and the person who started a run, still see that run, read its history and answer its waits.

On the screen

Open the assistant's settings and choose the Triggers tab. The Runs tab beside it lists the runs of that assistant.

  1. Set up the account. In the section Act as, choose Set up the account. Choose the roles, groups and attribute values the account gets, as for a service account; you can only give what you hold yourself. The account joins the members as a service account. Roles, groups and status are changed afterwards on its member page, which Manage roles and groups on its member page opens. Give it a right to the assistant and to everything its instructions use.
  2. Set a monthly cap, if you want one. In Act as, fill in Monthly cap (€): what the account's runs may cost in a calendar month. Core stops them at that limit. The section also shows this month's turns, cost and refusals, where your organisation lets you see costs.
  3. Add a virtual employee. Choose Add virtual employee. Fill in Name and Instruction, write the instruction the way you would ask a colleague. Under Criteria for a successful run you can list checks, one per line; the assistant reports on each when it is done, and a run that does not meet them fails.
  4. Choose when it runs. Under Schedule, choose Repeat (daily, weekly on a weekday, or monthly: on a day from 1 to 28, on the first to fourth or the last of a weekday, or on the last day of the month; at a time), Once (one moment, after which it switches itself off) or, last, Advanced (cron) with five fields. The times are read in the timezone shown. Two moments must lie at least five minutes apart. The screen shows the next five moments as you type, read from Core, so what you see is what will fire.
  5. Choose whether it asks. Switch Human approval on and say in your own words when the assistant involves a person: it then asks for approval before an action, or asks for what is missing. Left empty, it asks before any action that changes something outside the conversation. Core then holds the assistant's tool calls until a person decides: a call the assistant marks as needing approval waits, and so does one it leaves unmarked; a rejected call never runs. A call it marks as not needing approval runs at once: only your words guide that choice, so say plainly what must be asked. Without human approval a run waits for a person only when its account needs a sign-in at a connection: the people named for "needs attention" and your administrators are told, and only someone who may change the virtual employee and holds all its account holds can sign in, with the account set aside for it, not their own. Without one the run stops after 7 days. For a tool that asks for approval on every call, whatever the assistant thinks, use Tools that always ask for approval (Have tools approved).
  6. Choose who is told. Per event (started, completed, needs attention, failed) choose the members and groups to notify. Whoever is named also sees that virtual employee's runs and may answer its waits. A new virtual employee tells you when a run needs attention or fails. Reminder sets after how many hours (1, 4 or 24) the people asked get one reminder of a wait.
  7. Set the limits. Maximum number of actions in a run (up to 250) and Time limit per run (minutes) (up to 120; waiting for a person does not count), and Cost limit per run (€) (up to €25, €2 unless you change it), which only whoever your organisation lets see costs sees and changes. A run that passes a limit stops as failed.
  8. Save, and use Run now to try it. If the virtual employee already has a run open, OS says so and opens nothing.
  9. Switch off, change, delete. The switch in the list turns the timetable on or off. Delete removes the virtual employee and its timetable; a run still going is cancelled and finished runs stay until you delete them.

Not built yet: webhook and mail triggers, variables for the instruction and the account's own logins.

What a run costs

A run is metered under its account, so it counts toward your organisation's allowance and toward nobody's fair-use amount. A run's cost shows under Details on its page, only for whoever your organisation lets see costs.

Via the API

  • GET, POST, PATCH and DELETE /api/v1/organisations/{id}/assistants/{agent_id}/virtual-employee-account read, set up, cap and remove the account.
  • GET and POST /api/v1/organisations/{id}/virtual-employees; GET, PATCH (with If-Match) and DELETE …/virtual-employees/{employee_id}; POST …/virtual-employees/{employee_id}/run is Run now; POST …/virtual-employees/schedule-preview reads the next five moments.
  • GET …/runs lists runs, GET …/runs/summary counts them for a period, and GET …/runs/attention counts those waiting on the caller.