Create and work with an employee
Start with a job you want to hand off, such as checking invoices or answering support questions. In Employees, give that job a name and a face, add the documents it needs, and prepare its workflow in a conversation. Test examples before putting the employee to work.
The example below follows Robin, an employee that reviews supplier invoices. Give Robin a purchasing policy, try an invoice with a missing purchase order, inspect the result, and publish the reviewed workflow for chat. The same process works for support, legal review, research, and the other role starters.
How an employee connects to an application
Creating an employee creates an Assistant application with an employee profile. The employee is the identity people see. Its application holds the agents, knowledge, persona, channels, and access settings. The employee and application share the same ID, permissions, and resources. One agent usually handles the job. Several agents can cooperate inside the same employee when the work needs specialists. An older Assistant application without an employee profile remains a regular application. It does not automatically appear in Employees.
| What you see in Employees | Where it lives in Docana |
|---|---|
| Name, portrait, goal, and category | The application's employee profile |
| Skills and workflow steps | One or more agents inside the application |
| Knowledge files and connected sources | Collections available to the application |
| Expectations and test results | The agents' evaluation scenarios and runs |
| Performance measures | Conversation Insights captured by the agents |
| Chat and channels | The application's assistant and channel settings |
In Applications, employee applications show their portrait and an Employee link. Click that link to return to preparation. Advanced workspace opens the underlying agents when you need to inspect the workflow or its settings.
Bring an existing assistant onto your team
You can keep the assistant you already built. In Applications, open an active Assistant application's card menu and select Add to Employees. Review its goal, choose a portrait, and select the primary agent if the application has several. Then select Add to Employees to open its preparation room.
The application keeps the same ID, agents, knowledge, persona, members, connections, routines, and published versions. This adds an employee profile around the existing setup. It does not copy the application or rewrite its workflows. A published, enabled primary agent stays available for chat; a draft still needs publication. Applications without agents can continue setup in preparation. You need permission to edit the application.
1. Describe the job and choose an identity
Open Employees. Start with a role sits at the top of the creation form. Choose Customer support, Invoice review, or Legal document review, or select Browse all 20 roles to search the catalog. Each role supplies detailed responsibilities and checks behind the scenes, plus a suggested name, category, portrait, and persona. The text area stays available for your own context: your process, policies, systems, examples, and expected result. You can leave it empty and start with the role alone. Review the settings before selecting Create employee. Choosing a role does not create anything. Switching roles or selecting Clear role preserves your notes and attachments. Clear role resets the suggested name, category, persona, and portrait.
The catalog also covers research, sales, lead qualification, HR onboarding, recruiting, IT helpdesk, meeting follow-up, executive assistance, expenses, procurement, projects, construction, compliance, content, financial reporting, knowledge questions, and order operations. Templates include source verification, expected outputs, PDF and chart creation, performance measures, and cases that need a person. Preparation combines those instructions with your context and turns your requirements into expectations. These are starting points for preparation, not workflows that have already passed tests.
To start from an existing job description, drop a file into the brief or select Attach a brief. To explain the job aloud, choose Describe it by voice, then Stop & review. Replay the recording before selecting Attach recording, or discard it and try again. The recording stays as audio in the preparation conversation.
You can create from attachments without typing a goal. If you leave the name empty, the selected portrait supplies a starting name. Briefs accept up to 10 files and 20 MB total. Select Create employee to save the employee and prepare from the brief. Keep the page open until preparation finishes. The saved conversation opens afterward. If it is interrupted, Open saved employee lets you inspect progress and reattach any missing files without creating another employee.
Brief attachments provide context for preparation. Add lasting source documents and larger folders through Choose files or Choose folder after creation.
You can also enter your own name and goal. Include what comes in, what a good result looks like, and when the employee should ask for help.
For example: “Review incoming invoices against our purchasing policy. Check the supplier, amount, due date, and purchase order number. Flag missing information and prepare a summary for a person to approve.”
Choose a Category, a Persona and tone of voice, and a Portrait, then select Create employee. The portrait picker has 2 rows and page controls. Category and persona sit together below the brief. The category settings icon opens the shared catalog, and Preview this voice shows a sample of the selected tone. The persona changes communication style independently of the portrait.
Employees and Applications share one company category catalog. Choose from 20 industry categories, including Finance, Construction, Legal, Healthcare, and Education. Company administrators can type a new name in either creation form, choose Create, and select an icon without losing the draft. Open Company → Categories to rename categories or change their icons. Existing assignments stay together. To change an employee's category or portrait, click its portrait on the preparation page.
2. Add knowledge and prepare the workflow
Drop files or folders into the knowledge area above the preparation chat, or use Choose files, Choose folder, or Connect knowledge. A batch accepts up to 1,000 files. Select File limits in the drop area to check the maximum size for each file.
Folder uploads preserve the root folder and subfolders in the employee's collection. For example, Company policies/Legal/policy.pdf and Company policies/Finance/policy.pdf stay separate. Message attachments in the composer belong to the conversation. Use the knowledge area for documents the employee should reuse in future work.
Select View uploads to inspect progress, search filenames, or page through a large batch. Closing the dialog lets you keep preparing while uploads continue. Saved means the file reached the collection. Background processing must finish before the employee can retrieve its contents.
The knowledge summary counts all accessible files in connected collections and separates ready, processing, and failed files. Page totals include only known page counts from ready files. Select the summary to browse compact rows, search filenames, and move through pages of 50 files. File, collection, and folder links open the relevant source in a new tab. These counts describe source coverage, not a measure of intelligence or accuracy.
Tell the preparation assistant what the employee needs to do. It can create and revise the underlying agents, connect knowledge, define expectations, and set up performance measures using Docana's existing tools. Review what it created and ask it to improve missing steps.
The progress panel above the conversation shows the current step: building the draft, checking the workflow, running expectations, or fixing and retesting a failed check. It uses the tool results from the current conversation turn. A tool marked Completed only means the tool call finished. The progress panel shows whether the expectation passed and, when available, why it failed.
Open Details to review the observed checks and their run counts. View run opens the execution log when a run has one. View expectations opens the employee's expectations panel without starting another test. After a saved workflow or expectation changes, earlier results show Needs retest until a new run verifies those changes. If preparation stops or is interrupted, the activity animation stops and the recorded results remain available. The panel does not claim the whole employee is ready based on a partial set of checks.
For source-based work, preparation includes matching the correct document version and entity, bounded retrieval retries, and an independent review gate for consequential answers. It also considers context-dependent follow-ups, corrections, and reports with evidence-backed checklists.
Include details that matter to the job:
- Which sources support an answer, and how to check totals or conflicting information.
- When to ask for missing information or hand a decision to a person.
- Whether the output needs a PDF, document, chart, or report.
- Whether conversation history, a bounded follow-up, or a recurring routine is needed.
Every new employee starts with skills and sandbox code execution enabled for PDF reports and data charts. Preparation preserves instructions to create a real file, check its contents and layout, and return a download link. Ask for the output you need; a pre-existing business template is optional. Test file creation with representative data before relying on it. Deployment credentials for the sandbox must be configured.
For a website task, use Website access to register the site and enter its login in the secure form. A connected website can still require sign-in verification or another step such as MFA. For synced document sources, follow the connector setup and return to preparation.
Use MCP connections beside Website access to add tools from another service. Select an existing provider or choose Add a provider. The shared setup form offers presets, including Attio, and a custom server URL. Save the server, enable it for this employee, then sign in and test its connection. OAuth consent opens in a separate tab so preparation stays open. Return to check the discovered tools and choose Continue preparation to help the employee use them.
The connection count shows providers selected for the employee. Each user must complete their own OAuth sign-in. API keys and other secrets belong in the secure form. Advanced MCP settings opens the application's full configuration. Adding a new provider requires company administrator access.
3. Test expectations and inspect performance
Select the blue expectation card to inspect saved results without starting another run. Its short status line shows the latest observed outcomes: green when all saved expectations passed, red when some failed, and yellow while running or when checks remain. Select Test expectations to run the employee's saved scenarios. Use examples of successful work, missing data, conflicting sources, and requests that should reach a person. Open each result to understand what happened, then revise the workflow and test again.
For an invoice reviewer, test a complete invoice, a missing purchase order, a duplicate invoice, and an amount requiring finance review under your actual policy. Check the final answer, sources, calculations, and any generated files. Fix the workflow when it fails a correct requirement. Change an expectation when the requirement itself is wrong or has changed, not merely to get a passing result.
Structural validation checks the workflow's format. It does not prove the business result is correct. Keep the workflow and test cases in an agent project when you want reviewed changes and automated CI checks.
The portrait pulses while preparation or expectation tests are running, and becomes still when they finish. Reduced-motion settings keep a still outline. This indicates activity; tests improve the workflow and its instructions, not the underlying model.
From each fresh expectation result, Details opens the execution logs filtered to that test conversation. Edit expectation opens its definition. All expectations opens the agent’s evaluation screen. The log link appears after the test has a conversation to inspect.
Recent test runs shows when each test ran, how long it took, and its recorded score out of 10 when available. The small bar represents that score; a run without a recorded score shows only its status. View run opens the execution logs, the pencil opens the expectation for editing, and Review all tests opens the full evaluation screen.
The Results & activity drawer groups expectations, work history, performance, and knowledge. Each Work history row shows its status and date, elapsed time, recorded step count, and workflow version when available. Runs with recorded errors show their error count. Elapsed time includes waits and appears once a run ends. Select View execution to follow the steps behind that result; Open execution logs opens the full history. Earlier passing tests describe the version that was tested. Run them again after changing the workflow, instructions, or knowledge.
Preparation sets up Conversation Insights for new employee agents by default and tailors the measures to the goal. The Performance card shows a few recorded measures. View performance opens the rest and links to agent charts and measure settings. Data appears as conversations are processed, so a new employee may have no values yet.
These measures describe observed work. They are separate from test results and do not form a universal employee score. See Testing Agents and Insights for the underlying controls.
4. Publish, then work together
The team list distinguishes Setup needed, Not published, and Ready to chat. A saved draft shows Review & publish, which opens preparation. The Publish to start chatting callout appears near the portrait: review the workflow and test results, then select Publish for chat. Once published, the callout becomes Work together. Ready to chat means the selected agent is enabled and published. Readers without editing permission see that an application editor needs to publish the draft. A readiness label does not replace testing.
Select Work together beneath the employee's portrait and status to open the application's existing assistant. The employee's portrait and goal stay visible, and Employee profile returns to preparation. Your conversation history, attachments, and agent selection use the same assistant experience as other applications.
Long goals start as a short preview in the welcome screen. Select Read the full goal to expand the instructions, or Show less to return to the preview.
To connect WhatsApp, choose Add a channel → WhatsApp beneath the portrait. The dialog reads the application's current provider setup and lets you enable or pause the channel. Once a number is assigned, the profile shows it and a QR code can open a conversation with that number.
If provider setup is incomplete, use Channel settings to finish it. Getting a new paid Twilio number requires acknowledging the purchase in the dialog. The QR code opens a chat with the employee's number. It does not pair a personal WhatsApp account.
Connect channels remains available for the full settings. See WhatsApp, Slack, Microsoft Teams, and the web widget.
Recurring work and calls from your systems
A responsibility is a saved job that an employee can repeat, such as reviewing invoices every Friday or checking a document when it arrives. Each responsibility uses an agent's routine to store the instructions and triggers that start the work.
On the employee list, the Responsibilities card shows up to 2 saved jobs, their frequency and whether they are active or paused. If there are more, the card shows how many remain. Select the card to see them all.
The same summary appears beside the goal in preparation. Responsibilities cover all custom agents in the employee's application, so a specialist's routine appears alongside the primary agent's work.
Selecting either summary opens Work history. Each routine shows its agent, triggers, active or paused state, next scheduled run and last run. Select Manage routine to change its prompt or schedule in the existing routine editor. Members with read access see View routine. Schedules are labeled in UTC. API and document-arrival triggers are shown separately.
Active means the agent and routine are enabled and at least 1 trigger is enabled. Paused means the routine has been switched off or none of its triggers is enabled. Agent disabled means its agent is switched off. A next scheduled run appears only for an enabled schedule on an active routine and agent. These states describe when work can start. Check the execution history to see what actually happened.
Confirm the prompt, schedule, time zone and enabled state before activating a routine. Publishing an agent does not activate a paused routine or connect a channel. To supply a one-off prompt from your own backend and consume the result, run the agent through the API. Developers can also list an employee's responsibilities through REST, the CLI or MCP.
Add specialists when the work needs them
Split responsibilities when they need different knowledge, tools, or ownership. Several agents can cooperate within one employee's application. Separate employees have their own application settings and access. Define each specialist's output, configure handoffs explicitly, and test the complete process as well as each part. For example, request triage can pass documents to a reviewer and route exceptions to a person.
Use the same employee from code or an AI client
The UI uses the same employee services exposed through REST, MCP, and the CLI. The Employee API overview maps this walkthrough to individual operations. A connected AI client can create the employee, continue preparation, inspect tests and performance, and manage its knowledge using your Docana permissions. Its employee ID is the application ID.
See Employees from Code for complete REST, MCP, and CLI examples. For direct workflow authoring, use the agent builder or the build-agent prompt in an MCP client that supports prompts. Validate and review the specification before importing it into the intended application. Building an agent inside an existing application does not add an employee profile to that application.
An MCP client acts with the connected account's or API key's permissions. Client support for tools, prompts, and workflow execution varies. Use the CLI or API if your client does not expose the operation you need. Applications explains how knowledge, agents, members, and channels fit together.
Export and restore an employee
Select Export employee at the top of preparation to save the employee's setup. The preview shows the portrait, category, goal, agents, expectations, and source references. Expand Review source references to inspect the original knowledge and connections before downloading.
The JSON package includes the employee profile, application instructions and local persona settings, draft agent workflows, evaluation definitions, routines, insights configuration, mock baselines, document templates, and recommendation definitions. It records the names and IDs of the collections, files, connectors, websites, skills, channels, and MCP providers the application used.
File binaries, provider credentials, memberships, conversations, execution history, and published revisions stay in the source workspace. Authored instructions, examples, and template content travel with the package, so review that content before sharing it. A connection's name is a reference, not permission to use it.
To restore it, select Import employee on the team page, choose the package, review its contents, and choose a name and destination category. Import as a draft creates a new application. It does not overwrite the original. Agents arrive unpublished, and routines, recommendation schedules, and evaluation schedules stay paused.
Open Import checklist in the restored employee to review the original dependencies. Reconnect the destination's collections, files, providers, and channels through their existing setup screens. Source resource IDs are made unresolved; review and update the workflow's references after reconnecting. Run expectations and review the output before publishing. The checklist preserves source references and does not automatically certify that each one has been restored.
Employees and applications share this package format. Applications → Import application also accepts employee packages, and application cards offer Export application. The agent definitions use the same export utilities as the standalone agent export.