Building an employee portrait from chat

In user language: This article is for workspace admins and everyday users. It explains how to talk to a work agent in Messages to go from “explore → save a skill → (optional) create an app → produce a report on a fixed path”, without pasting scripts or config files by hand in Skill center. Implementation notes are in Implementation map at the end.

Date: 2026-07-10 Examples and templates: examples/employee-profile-pipeline/ Related mechanisms: docs/core-mechanisms/技能组成规范.md, docs/core-mechanisms/工作区应用.md, help/product-features/writing-workspace-skills.md

Takeaway

Cadau can turn an employee portrait request into a repeatable program pipeline, instead of asking the model to invent SQL and HTML every time.

Recommended path:

1. Try once in conversation (optional);
2. Say “create an employee-portrait skill” → the platform installs the built-in template (pipeline + scripts + layout) and binds it to the current agent;
3. An admin writes predefined queries in conversation (once);
4. Day to day, only say “generate so-and-so’s employee portrait” → fixed-step fetch, assemble, deliver HTML;
5. For a desktop entry, say “make an employee-portrait app” in conversation.

Before you start: environment

Five steps (recommended wording)

Step 1: Explore (optional, first time)

In Messages, type:

Generate Zhao Jiang’s employee portrait

(In a Chinese UI the same request is often: 生成赵江的员工画像.)

What happens

• The agent tries the data connection for HR data and attempts a portrait (HTML or a structured write-up).
• If predefined queries are not configured yet, it may only use table preview for samples — not a production path.

Suggestion: once exploration looks good, lock it in with steps 2 and 3. Do not rely on improvisation long term.

Step 2: Create the skill in one sentence (the core)

In the same conversation or a new one, tell the work agent:

Create an employee-portrait skill

Or more completely:

Create an employee-portrait skill; fetch on a fixed pipeline; assemble HTML with a script

The platform will

Two different “generate a skill” phrases

Step 2b: Migrate an existing skill to the pipeline (optional)

If Skill center already has an “employee portrait” skill (for example an LLM write-up), type / to pick that skill in Messages and say:

更新 /生成员工画像HTML（含证件照与统计图），按固定 pipeline 取数，脚本组装 html

Must include all of: 更新/修改 + pipeline (or “fixed fetch”) + 脚本组装 + employee portrait/HTML keywords.

The platform will write references/pipeline.json, scripts/assemble_profile.py, assets/profile.html, and publish a new version — not only an AI Markdown edit of the body.

If you only say “update this skill” without mentioning pipeline, you still get a write-up revision, not an automatic fixed-fetch install.

Step 3: Write predefined queries (admin, once)

HR table structure differs by customer; read-only queries must go on the data connection. An admin can say in conversation:

帮我把员工画像需要的预定义查询写入 HR 数据连接

And add:

请按 examples/employee-profile-pipeline 里 query-defs 的清单，逐条 query.upsert；写完后用「赵江」逐条 query.run 验证。

Query list (summary) (full JSON: examples/employee-profile-pipeline/data-connection/query-defs.example.json):

Verification example (admin or agent in a tool call):

{
  "source_slug": "your-HR-connection-slug",
  "action": "query.run",
  "params": {
    "query_id": "employee_by_name",
    "params": { "empName": "赵江" }
  }
}

If SQL does not match the real CareTop/HR tables, say in conversation: “correct the employee_by_name query to our tables”, then query.upsert after the admin confirms.

When a query is missing (fill in during conversation)

You do not have to pre-configure every query. If the user asks stats, duplicate-name checks, ID-number checks, and so on, and query.list has no match, the agent should:

1. Propose a read-only SELECT and a suggested query_id (parameters with ?, never @empName);
2. Wait for the user to confirm (e.g. “yes, add it and run”);
3. Admin query.upsert, then query.run in the same conversation and return the result.

Do not answer “are there duplicate names” or “are the ID numbers the same” from the first rows of table preview — preview is not the whole database.

Predefined-query SQL placeholders: must be WHERE empName = ? with params count matching ?. @empName causes save failure or run errors.

Step 4: Create an app (optional)

When you need an app desktop entry (type a name, get a portrait, see history), say in Messages:

做一个员工画像应用，输入姓名、能看历史记录

The platform will

• Create an Employee portrait app on the Apps desktop (form + history list);
• Write Python scripts at create time (logic/generate_profile.py, assemble script, layout assets);
• After you submit a name in the app, run those scripts directly to fetch data and generate HTML — no round-trip through conversation.

You can still say “generate so-and-so’s employee portrait” in Messages; both entries share the same fetch path and layout.

Step 5: Day-to-day use

After setup, users only need:

生成赵江的员工画像

Expected behavior (fixed program, not improvised):

sequenceDiagram
  participant U as User
  participant A as Work agent
  participant DS as Data connection
  participant S as Assemble script

  U->>A: Generate 赵江's employee portrait
  A->>A: Recall the employee-portrait skill
  loop pipeline steps
    A->>DS: query.run fixed query_id
    DS-->>A: row data / photo upload_id
  end
  A->>S: run_script fill HTML template
  S-->>A: output_files/*.html
  A->>U: Preview / download link

Deliverable: a fixed-layout HTML employee portrait; missing fields show “无” or “—” — never invented.

Duplicate names: if the name lookup returns multiple employees, list employee number, created time, status, and so on, and ask the user to pick an empId. Do not fetch later steps until confirmed.

Follow-up after duplicates (e.g. “do these three have the same ID number”): use a lookup ID number predefined query (or the propose → confirm → save → run path above). Do not scan the whole table with preview.

FAQ

Photo does not show

• HTML img must use /api/v1/uploads/{upload_id}, not a placeholder domain.
• BLOB photos in query results should be saved as attachments by the platform, then embedded.

“Create an employee-portrait skill” does nothing

• Confirm you are in a work-agent conversation with a workspace selected;
• Wording must include “员工画像” + “技能” + “创建/生成” (for example “生成赵江的员工画像” is produce a report, not create a skill);
• Backend must be a build that includes the employee-portrait built-in template (see Implementation map).

Script execution failed

• Check Assistant capability pack → Script execution and workspace member authorization;
• Open the skill in Skill center and confirm scripts/assemble_profile.py exists.

Write-up only, no pipeline

• That means “save this conversation” or a plain “update skill” was used; type / to pick the target skill and say: “更新，按固定 pipeline 取数，脚本组装 html”, or roll back in Skill center and migrate.

Duplicate-name / ID-number answers are wrong

• Table preview only shows the first unfiltered rows; it cannot tell whether the whole database has duplicates or compare ID numbers.
• Configure a predefined query (e.g. look up citizenID by name), or have an admin save the query then run after confirming in conversation.
• SQL must use ? placeholders, never @empName.

Smart check and fix is slow or has no progress

• In Data integration → Data connections, Smart check and fix runs per item; wait for the progress bar when there are many queries.
• In full-screen edit of predefined queries, the progress dialog is on the top layer; if it still does not respond, confirm AI is configured and retry.

It stopped halfway and asked you to say “continue”

• In the same conversation say: “继续把周珊珊的员工画像做完” or “继续生成画像” — no need to explain technical details.
• The platform tries to resume in the background; if it still only talks and produces nothing, send a new “生成某某的员工画像” (with the confirmed correct name).
• If it is stuck on duplicate confirmation or name candidates, pick from the agent’s list and reply “就是这个”.

Relation to hand configuration in admin

Implementation map

Further reading

• Employee portrait and data connections — admin one-shot upsert wording and alignment checks
• Skill writing: help/product-features/writing-workspace-skills.md (§8.4 script skills, §8.6 predefined queries)
• Workspace apps: docs/core-mechanisms/工作区应用.md
• Explore-to-program design: share the architecture notes in examples/employee-profile-pipeline/README.md with colleagues