Set Up Agent Orchestration
This guide is for company administrators who want to enable agent-assisted work in IntuitivePM.
Agent orchestration works best when the company first defines who may plan work, which agents may execute it, which runtimes are trusted, and how completed work is reviewed.
Managed internal agents, external agent runtimes, and custom AI execution environments are available for Enterprise workspaces and must be approved by a company administrator.
Before You Start
Make sure you have:
- Company administrator access.
- At least one project and board.
- The members who will own orchestrator or agent Virtual Colleagues.
- Company AI providers configured, an approved managed internal agent, or an approved external runtime available.
- A decision on whether agents may use Work Files.
Step 1: Create Orchestrator And Agent Virtual Colleagues
Open Virtual Colleagues and create the colleagues your company needs.
Recommended starting point:
- One personal Agent Orchestrator for each member who will coordinate work.
- One or more Agent colleagues for execution work.
The orchestrator is the planning and review assistant. Execution agents are the workers that receive tasks or subtasks.
Task owners can refine dispatch by saving structured Selection requirements on a task. API-backed subtasks also expose their own Requirements expander, which is useful when one parent task contains separate coding, documentation, review, or operations work.
Step 2: Configure Behavior
Open each Virtual Colleague and review the Behavior tab.
Use these settings intentionally:
- AI Analysis: enables project insight such as stale work, overdue work, blockers, risks, and planning summaries.
- Auto-Act on Assignment: allows the colleague to act when work is assigned to it.
- Action Mode: chooses whether execution uses company-approved built-in AI services or an approved external runtime.
AI Analysis and Auto-Act are separate settings. A colleague can analyze project health without executing tasks, and an execution agent can act on assigned work without being used for periodic planning analysis.
Step 3: Choose Internal Or External Runtime Ownership
Before creating an execution agent, choose the runtime model:
| Choose this | When |
|---|---|
| Managed internal agent | You want IntuitivePM to operate the runtime and the work can use IntuitivePM context, approved AI providers, Knowledge Sources, and Work Files. |
| External runtime | The agent must run inside your environment, use private tools, access local workspaces, or execute custom automation. |
When managed internal agents are enabled for your workspace, create them from System -> Integrations -> Agent Registry with Create Agent -> Internal Agent. The agent is usable only after Runtime details shows an active managed runtime.
See Managed Internal Agents for lifecycle states, troubleshooting, and security boundaries.
Step 3A: Set Agent Access
Before adding an agent to production workflows, review its access policy in Agent Registry.
Use Can see for catalog visibility and Can use for workflow/task invocation. These are intentionally separate controls. A platform owner or company admin may need to see an agent for governance, while only a specific team or project should be allowed to use it.
Recommended defaults:
| Scope | Use when |
|---|---|
| Owner only | New agent, smoke test, sensitive capability, or temporary experiment. |
| Selected users | A small number of named operators own the first rollout. |
| Selected teams | A team should use the agent across its accessible work. |
| Selected projects | The agent is trained or governed for a specific project. |
| Selected boards | The agent should be available only inside a board’s workflow. |
| Company | The agent is broadly approved, low risk, and support-ready. |
Use the Agent Registry access audit panel to verify the effective policy before enabling the agent in a workflow. If users report that an agent is missing from a selector, first check Can use, runtime status, and company rollout limits.
Step 4: Approve External Agents
If your company uses external execution, open System -> Integrations -> Agent Registry.
For each external agent:
- Select Add external agent.
- Enter a clear name, such as “Claude Code Agent” or “n8n Document Worker”.
- Choose whether the agent is an Execution agent or an Orchestrator.
- Assign an owner member.
- Optionally map it to a Virtual Colleague.
- Create credentials for the runtime.
External agents are company-approved so members cannot connect unauthorized workspaces, models, or automation tools.
Step 5: Register And Approve External Runtimes
An external runtime is the actual destination that executes work. It can be a script, container, workflow automation, IDE agent, or another approved process.
When the runtime registers, review it in System -> Integrations -> Agent Registry:
- Open the agent row.
- Review the runtime name, status, specialization, capabilities, and environment.
- Approve the runtime if it matches your company policy.
- Copy the setup command from the runtime details when configuring a managed Ubuntu runtime.
- Copy the Runtime ID from the runtime list only when configuring another runtime type manually.
Do not approve runtimes you do not recognize.
Use a versioned IntuitivePM runtime package or approved container image for customer runtime hosts. The package should be obtained from Agent Registry, a company-approved download location, or IntuitivePM support. It should be verified before installation and updated through a controlled rollout. See External Runtime Packages for the package, checksum, update, and rollback process.
Managed Ubuntu runtimes should start in smoke mode. Smoke mode lets you validate task assignment, progress, comments, lease handling, and Review handoff before allowing the runtime to invoke Claude Code or another executor against real files.
When live execution is enabled, keep the workspace root narrow. Managed runtimes reject approved paths outside that root, require explicit yolo policy for full CRUD, and write local run logs for support review. Approve live execution only when the runtime is isolated from other executor sessions through a dedicated user, container, or pod with separate home/config/cache/workspace/log paths.
Step 6: Describe Agent Capabilities
Use clear descriptions and capability settings for each approved agent. Open the agent in System -> Integrations -> Agent Registry and edit the Capability profile section. The orchestrator uses reviewed agent capability data, runtime status, model family, risk limits, and task requirements to decide which agent should receive work.
Good capability information includes:
- The kind of work the agent can perform, such as code changes, documentation, testing, review, data processing, or planning.
- The tools and workspaces the runtime can safely use.
- Any model family or tier expectation, such as Opus, Sonnet, Haiku, GPT, Gemini, or an approved external runtime-managed model.
- Risk and autonomy boundaries, especially whether the agent needs human supervision.
Keep this information current when you change runtimes, AI providers, repositories, or agent responsibilities.
Use AI Assist when you want a faster starting point. The reviewed draft flow uses company-approved AI services to draft the profile, review it with a second model when available, and resolve the feedback into a final draft. Review the confidence markers before applying anything:
- Confirmed fields are strongly supported by the agent and runtime context.
- Adjusted fields were changed during the review loop.
- Needs review fields require administrator judgment.
- Low confidence fields should not be treated as trusted until you verify them.
AI Assist never saves the profile by itself. Apply the draft, adjust it if needed, and then click Save profile.
Approved external runtimes may submit their own capability claims after they connect. Use the Runtime capability claims panel in Agent Registry to review those claims. The panel compares the claim with the current reviewed profile and current runtime tags, marking which fields are added, changed, unchanged, or not claimed. Approve and apply only when the evidence matches your approved workspace, tools, model route, and autonomy policy. Reject claims that overstate capability or reference unapproved systems.
IntuitivePM uses the reviewed profile as the dispatch contract. During automatic selection it ranks approved agent/runtime candidates and records the score breakdown, matched signals, and rejection reasons. Do not rely on free-text descriptions alone for routing decisions.
For external runtimes where the runtime controls the exact model, use External runtime managed as the model routing mode and still fill in the model family, tier, tools, scopes, risk, and autonomy limits. For built-in or custom provider models, select the approved model route your company has configured. IntuitivePM shows both the friendly model family/tier and the exact provider model ID when it is known, so admins can audit whether “latest” slots currently point to the expected provider model.
Step 7: Let IntuitivePM Derive Task Requirements
When a task is prepared for agent work, IntuitivePM can derive a structured requirement profile from the task title, description, labels, priority, estimates, linked repositories, documentation requirements, Work Files, and orchestration rule sets. The task modal also lets authorized users infer, AI infer, edit, and save the requirement profile before dispatch. Saved requirements are used by automatic agent selection.
The orchestrator uses this profile to understand what kind of agent is needed. For example, a Kubernetes task with linked git work and required documentation may need a code-capable agent, platform engineering skills, git access, documentation tooling, and human review.
When dispatch runs, the selected agent/runtime and the selection reason are saved with the task orchestration metadata. Candidate ranking also includes a bounded reliability signal from recent immutable outcome history, including completions, failures, expiries/stale leases, cancellations, releases, caveats, review accepts/rejects, and duration. If no candidate passes the policy gates, the task waits on orchestration with the most useful rejection reason visible for troubleshooting.
IntuitivePM keeps append-only outcome history for selections, lease outcomes, and review accept/reject decisions. This gives admins and auditors a durable record of which candidate was selected, what score breakdown was used, how the work finished, whether caveats were present, and how long each step took. Recent lease rows are used only as a migration fallback when no relevant outcome history exists yet.
Review accept/reject decisions also store a review-quality assessment. The first scoring slice uses deterministic criteria from default templates, runtime review template IDs, runtime quality gate IDs, rule-set review template IDs, and task metadata hints. Admins can monitor accepted/rejected review counts, low-quality reviews, and average review-quality score through the Agent Activity dashboard widget.
You can still adjust task instructions manually. Keep task descriptions clear and attach relevant files or repository links before starting agent work.
Task owners and orchestrators can provide three focused instruction types in the task Orchestration section:
- Execution agent instructions for how the agent should perform the work.
- Orchestrator/reviewer instructions for how the result should be reviewed.
- Completion evidence for the proof that must be supplied before review.
Use the task-modal dispatch preview to validate routing before live execution. The preview lists the selected candidate, score, reliability contribution, model family/tier, exact provider model ID when available, matched signals, and rejected-candidate reasons. If the preview does not match your expectations, update the agent capability profile, runtime configuration, task selection requirements, task instructions, or attached context before moving the task to In Progress.
Step 8: Configure Work Files
Open Work -> Files to confirm the workspace model your team will use.
By default, agents can:
- Read the owning member’s files.
- Create new files.
- Update only files they created last.
Agents cannot delete files or freely edit everything unless the member explicitly enables full access for that agent.
Step 9: Define Review Expectations
Agent-executed work always needs review before it becomes Done.
Tell agents and reviewers what evidence is required. Common completion evidence includes:
Code updated:Docs updated:Docs touched:Tests run:
The completion comment should also say whether the work was completed with no issues or completed with caveats.
When automated orchestrator review is enabled, IntuitivePM uses a dedicated review lease for the decision step. The execution lease ends when the agent submits work to Review; the review lease starts when the orchestrator claims the review. This lets admins monitor execution and review separately, recover stale review attempts, and keep human override auditable.
Configure retry policy in the orchestrator rule set. The default allows two automated review returns before escalation. reviewEscalationWaitingOn decides whether the task waits on a user or orchestrator after that limit. Use a lower limit for high-risk work where repeated automated retries should quickly reach a person.
Step 10: Start With A Smoke Test
Before assigning important work:
- Create a small test task.
- Assign an approved execution agent.
- Move the task to In Progress.
- Confirm the task shows an execution state and runtime.
- Confirm the agent writes a comment.
- Move the work through review.
If the task does not start, check that the agent is approved, the runtime is online, and the work is actually assigned to the agent before it entered In Progress.