Import Agent Builder Agents into WIQD Projects Safely

The prototype worked. Great. Now WIQD has to turn that Agent Builder win into files your team can review, validate, test, and improve without accidentally rebuilding the agent from vibes and a suspiciously confident memory.

Start with WIQD References, Not Memory

An Agent Builder import is a preservation exercise first and an engineering exercise second. The goal is not to create a nicer agent. The goal is to capture the agent people already approved, make its hidden configuration visible, and prove the local project behaves the same way before anyone edits it.

That is why I want the coding agent grounded in WIQD and its reference files, not in a generic Agents Toolkit skill path. WIQD owns the workflow shape for this handoff: project discovery, manifest mapping, validation, provisioning, asking, and evals. The Microsoft 365 Agents Toolkit still matters underneath, but it should not be the thing inventing the import plan.

Reference input	What it proves
wiqd doctor	The installed preview, dependencies, and local environment are ready
wiqd auth status	The signed-in account and tenant are the ones that can see the source agent
wiqd agent --help	The command surface exists in this preview build
WIQD agent workflow references	Agent Builder fields map to local files, validation, provisioning, ask, and eval steps
Declarative agent schema references	Imported capabilities, file references, and schema versions are valid

That response tells me the agent is using the WIQD workflow as its source of truth. Much better than “I know agents.” I also know how to make espresso, but you should still not let me wire a tenant from memory.

Inventory the Agent Builder Source

Before WIQD writes a file, capture the source agent exactly as it exists. Do not improve the instructions. Do not rename starters. Do not broaden SharePoint scope because the folder name is ugly. The first baseline should answer one boring question: did the prototype survive the move?

For an HR policy helper, the inventory can stay compact:

Agent Builder field	Source value to capture	WIQD import decision
Identity	Display name, description, icon, owner, sharing scope	Preserve user-facing text, generate new development IDs
Instructions	Citation behavior, refusal rules, escalation language	Externalize into appPackage/instructions.txt
Starters	Vacation, remote work, expenses, benefits enrollment	Preserve all starter text
Knowledge sources	SharePoint site, library, folder, or resolved identifiers	Preserve the reference if permissions allow
Actions	API or MCP capability, auth owner, side effects	Import only when ownership and auth are clear
Environment values	Tenant IDs, app IDs, title IDs, deployment outputs	Move environment-specific values into env files

Run the boring checks before the import. Boring is a compliment here.

wiqd auth login --interactive
wiqd auth status
wiqd doctor
wiqd agent list --name "HR Policy Helper" --top 5 --json

If the source agent is not visible to the signed-in account, stop. An import that starts from the wrong tenant is not an import. It is fan fiction with JSON.

Materialize the WIQD Project

The safest ask is outcome-based and strict about scope. You want WIQD to preserve behavior, write a report, and stop before it starts “helping.”

A clean materialized project should be boring on disk:

hr-policy-helper/
├── appPackage/
│   ├── color.png
│   ├── outline.png
│   ├── manifest.json
│   ├── declarativeAgent.json
│   └── instructions.txt
├── env/
│   ├── .env.local
│   ├── .env.dev
│   └── .env.dev.user.example
├── evals/
│   └── prompts.json
├── m365agents.yml
└── IMPORT.md

The important transformation is the instruction reference. Agent Builder stores behavior in the authoring experience. WIQD turns that behavior into a file your team can diff.

{
  "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.8/schema.json",
  "version": "v1.8",
  "name": "HR Policy Helper",
  "description": "Answers employee questions from the official HR policy library.",
  "instructions": "$[file('instructions.txt')]",
  "capabilities": [
    {
      "name": "OneDriveAndSharePoint",
      "items_by_url": [
        {
          "url": "https://contoso.sharepoint.com/sites/hr/policies"
        }
      ]
    }
  ],
  "conversation_starters": [
    {
      "title": "Vacation balance",
      "text": "How many vacation days do I accrue after five years?"
    },
    {
      "title": "Remote work",
      "text": "What does the remote work policy require?"
    },
    {
      "title": "Expenses",
      "text": "How do I submit a travel expense?"
    },
    {
      "title": "Benefits",
      "text": "When can I change my benefits enrollment?"
    }
  ]
}

Read IMPORT.md like a reviewer, not like a success banner. I want four buckets: preserved, transformed, warned, and unsupported. “Unsupported” is not failure. It is the tool refusing to hide uncertainty from you.

Prove Parity Before You Improve

Validation comes before taste. Fix import correctness only: malformed JSON, missing files, broken file references, environment placeholders, and schema mismatches.

wiqd agent show --path ./hr-policy-helper --env dev --verbose
wiqd agent validate --path ./hr-policy-helper --mode static
wiqd agent validate --path ./hr-policy-helper --mode deep --env dev
wiqd agent provision --path ./hr-policy-helper --env dev

Then compare the Agent Builder prototype and the WIQD-provisioned development copy with a tiny parity set:

Test	Pass condition
Vacation accrual after five years	Same policy conclusion, with a citation to the approved policy source
Remote work from another country	Same approval requirement, with no invented legal exception
Manager salary band	Same refusal or HR support redirect because individual compensation is out of scope

Once those manual checks are stable, turn them into evals so the baseline keeps paying rent.

wiqd agent ask --path ./hr-policy-helper --env dev --query "How many vacation days do I accrue after five years?"
wiqd agent ask --path ./hr-policy-helper --env dev --query "What does the remote work policy require before I work from another country?"
wiqd agent ask --path ./hr-policy-helper --env dev --query "What is my manager salary band?"
wiqd agent eval init --path ./hr-policy-helper --env dev
wiqd agent eval --path ./hr-policy-helper --env dev --threshold 0.8

Keep secrets and per-user values out of the repo. Commit templates, non-secret identifiers, and import notes. Put tokens, cookies, client secrets, and user-specific auth state somewhere boring and private, which is where secrets like to live.

The Value of a Boring Import

• A preserved prototype: The Agent Builder version remains the behavioral source, not a vague memory of a good demo.
• A reviewable project: Instructions, manifests, environment files, and evals become normal source artifacts.
• Reference-backed decisions: WIQD help and schema references drive the workflow instead of stale command snippets.
• Visible uncertainty: Permissions, unsupported fields, and tenant-specific assumptions land in IMPORT.md instead of disappearing.
• A safe improvement path: Parity checks and evals create the baseline you need before refining instructions or capabilities.

That is the whole win. You are not making the agent smarter yet. You are making it owned, inspectable, and boring enough that the next change has something solid to stand on.

Resources

• Work IQ Developer Tools documentation
• Work IQ Developer Tools on GitHub
• Agent Builder in Microsoft 365 Copilot
• Declarative agents overview
• Declarative agent schema 1.8
• Agent Evaluations CLI overview
• Microsoft 365 Agents Toolkit overview