add-other-agents

Files (1)

• SKILL.md

SKILL.md (first lines)

# Add Other Agents

Add multi-agent capabilities to a Copilot Studio agent. Two patterns are supported:

| Pattern | Use when | What it creates |
|---------|----------|----------------|
| **Child agent** | The agent needs a specialist sub-agent owned by the same parent | `AgentDialog` in `agents/` subdirectory |
| **Connected agent** | The agent needs to call an external, independently-managed agent | `InvokeConnectedAgentTaskAction` in a topic (TaskDialog) |

Ask the user which pattern they need if unclear.

---

## Pattern 1: Child Agent

Create a new child agent (AgentDialog) that the parent agent's orchestrator can delegate to.

### Instructions

1. **Auto-discover the parent agent directory**:
   ```
   Glob: **/agent.mcs.yml
   ```
   Use the top-level agent (not one inside an `agents/` subdirectory). NEVER hardcode an agent name.

2. **Look up the AgentDialog schema**:
   ```bash
   node ${CLAUDE_SKILL_DIR}/../../scripts/schema-lookup.bundle.js resolve AgentDialog
   node ${CLAUDE_SKILL_DIR}/../../scripts/schema-lookup.bundle.js resolve OnToolSelected
   ```

3. **Determine from the user**:
   - Child agent name and display name
   - What the child agent specializes in (for the description and instructions)
   - What inputs the child agent needs (if any)
   - Whether it will need its own knowledge sources (handled in Phase 2 — see below)

4. **Create the child agent directory** (Phase 1 — plain agent only, NO knowledge):
   ```
   <parent-agent>/agents/<ChildAgentName>/
   └── agent.mcs.yml
   ```

5. **Generate `agent.mcs.yml`** using `${CLAUDE_SKILL_DIR}/../../templates/agents/child-agent.mcs.yml` as the starting template. Read the template, then customize all placeholder values (`<...>`) based on the user's requirements.

   Key structure:
   - `kind: AgentDialog` — marks this as a child agent
   - `beginDialog.kind: OnToolSelected` with a `description` — tells the parent orchestrator when to route here
   - `settings.instructions` — the child agent's system prompt
   - `inputType` — context the orchestrator passes in
   - `outputType` — what the child agent returns (use `outputType: {}` if no structured output is needed)

   **CRITICAL: AgentDialog must NOT have `beginDialog.actions`.** Child agents use generative orchestration — all behavior is driven by `settings.instructions`. Do NOT add action nodes (Question, SendActivity, BeginDialog, ConditionGroup, etc.) to the actions array. If the user's scenario requires hardcoded action flows, it should be an AdaptiveDialog topic in the parent agent, not a child agent.

6. **Key fields explained**:
   - `beginDialog.description` — This is what the parent orchestrator reads to decide when to route. Be specific and action-oriented (e.g., "This agent handles billing inquiries, refund requests, and payment issues").
   - `settings.instructions` — The child agent's system prompt. Define its personality, scope, and behavior guidelines.
   - `inputType` — for context the orchestrator should pass. The parent fills these automatically.

### Two-Phase Workflow (Important)

Child agents MUST be created in two phases:

**Phase 1 — Create the plain agent** (steps 1-6 above):
- Create ONLY `agent.mcs.yml` with configuration, instructions, inputs, and outputs.
- Do NOT create a `knowledge/` directory or any knowledge sources yet.
- Tell the user: "The child agent has been created. Please push these changes to your environment using the Copilot Studio VS Code Extension before we can add knowledge sources to it."

**Phase 2 — Add knowledge sources** (only after the user confirms they pushed):
- Once the user confirms the child agent has been pushed and exists in the environment, you can add knowledge sources to it using `/add-knowledge`.
- Create the `knowledge/` directory under the child agent and add knowledge source files there.

This constraint exists because knowledge sources reference the agent they belong to — the child agent must exist in the environment first.

### Example: Customer Support Child Agent

```yaml
kind: AgentDialog

beginDialog:
  kind: OnToolSelected
  id: main
  description: This agent handles billing inquiries, payment issues, refund requests, and subscription management. Route here when users ask about charges, invoices, or account billing.

settings:
  instructions: |
    You are a billing support specialist. Help customers with:
    - Understanding their charges and invoices
    - Processing refund requests
    - Managing subscription plans
    - Resolving payment issues

    Always verify the customer's account before making changes.
    Escalate to a human agent for refunds over $500.

inputs:
  - kind: AutomaticTaskInput
    propertyName: CustomerQuery
    description: The customer's billing-related question or issue

inputType:
  properties:
    CustomerQuery:
      displayName: Customer Query
      description: The customer's billing-related question or issue
      type: String

outputType: {}
```

---

## Pattern 2: Connected Agent

Call an external, independently-managed agent from your agent. This creates a `TaskDialog` with an `InvokeConnectedAgentTaskAction` that the orchestrator can invoke.

### What you can do (calling side)

The plugin creates the **calling side** YAML — a TaskDialog in your agent that invokes the connected agent with inputs/outputs.

From microsoft/skills-for-copilot-studio, MIT.

More from microsoft/skills-for-copilot-studio