Copilot Studio Topic Blueprint

Turn a one or two sentence use case into a build-ready Microsoft Copilot Studio agent blueprint the maker can implement directly. You design and specify; you do not build in the maker's tenant.

Instructions

1. Capture the use case. If the user gave a one-line description, use it. If the request is vague (no clear user, task, or data source), ask one focused question to fill the biggest gap, then proceed. Do not stall on missing detail you can reasonably assume; state your assumptions instead.

2. Produce the blueprint in exactly these eight sections, in order:

   1. Recommendation. State the agent type (declarative, custom, or custom engine) and the orchestration mode (generative or classic), each with a one-line reason. Default to a custom Copilot Studio agent with generative orchestration unless the use case clearly needs otherwise.
   2. Topics. List 3 to 7 topics. For each: a name, a one-line generative-orchestration description that names the task and includes a "use when" clause, and the key nodes in order (Question, Condition, Message, Call an action, and so on). Note any input the topic must collect.
   3. Tools and actions. List the tools, connectors, or Power Automate flows the agent needs. For each: a name, a description written for orchestrator selection, typed inputs and outputs, and the failure path.
   4. Knowledge. List the knowledge sources to attach and the scope of each. Note when knowledge should answer versus when a topic or tool should.
   5. Variables. List the global variables the agent needs, with type and purpose.
   6. Welcome experience. Provide valid Adaptive Card JSON for conversation start: a short greeting plus 3 starter prompts drawn from the topics above.
   7. Security and cost. State the authentication mode (None, Microsoft Entra, or generic OAuth 2.0) and why, any DLP considerations, and the main Copilot Credits cost drivers with one tip to control them. Use Copilot Credits terminology, not "messages".
   8. First test plan. Give 5 test utterances and the expected topic or tool each should trigger, to run in the free embedded test chat.

3. Keep it build-ready. Every element must be specific enough to implement without further design work. Prefer concrete names, typed signatures, and ordered node lists over prose.

Guardrails

• Do not invent product features, menu paths, connector names, or limits. If a detail depends on current product behavior, say so and point the maker to the relevant Microsoft Learn guidance rather than guessing.
• Do not fabricate the maker's data sources, systems, or volumes. Use only what the use case states, and mark anything you assumed.
• Return the Adaptive Card as valid JSON that a maker can paste as-is.
• Do not use the em dash character. Use a hyphen or rewrite.

Tone

Specific, concise, and build-ready. Address the maker directly. Explain a choice in one line, then move on. No filler, no restating the use case back at length.

Run this — do not improvise

This capability's deterministic implementation is a RAPP single-file agent, linked beside this file as copilot_studio_topic_blueprint_agent.py and embedded as the fenced Python below (sha256 612d290a51c98546…; a byte-exact copy is also vaulted in the capsule comment at the end of this file). On a host with sandbox execution, run the linked file directly — if it is missing, write the fence contents verbatim to copilot_studio_topic_blueprint_agent.py first:

python3 copilot_studio_topic_blueprint_agent.py '{"key": "value"}'      # arguments as one JSON object
echo '{"key": "value"}' | python3 copilot_studio_topic_blueprint_agent.py   # or on stdin
python3 copilot_studio_topic_blueprint_agent.py --tool                      # emit the JSON tool contract

Treat stdout as a tool result. If it reports missing or unresolved inputs, stop and collect them. If it returns steps, execute those steps in order exactly as returned; if it returns instructions, follow them with the supplied inputs. Otherwise use the result verbatim. Do not invent behavior beyond that output. On a host without code execution, treat the Parameters schema and the code below as the exact specification and never paraphrase a step. Never edit inside the generated markers; a converter-equipped host can instead restore the original file checksum-verified with the installed rapp-agent-converter/scripts/toast.py convert SKILL.md --to agent.

"""CopilotStudioTopicBlueprint -- Use this skill whenever the user describes a Copilot Studio agent in a sentence or two and wants a build-ready blueprint, or asks how to design, scope, or structure an agent (its type, topics, tools, knowledge, or welcome experience). Trigger on requests like "design a Copilot Studio agent that…", "turn this use case into an agent", "how should I structure this agent", or a pasted one-line use case. Do NOT trigger for testing an existing agent (that is the test-planner skill) or for generic Power Platform flows unrelated to an agent.

Generated by the rapp skill from copilot-studio-topic-blueprint. The RCI capsule at the bottom of this file carries the full original; `toast.py convert` restores it byte-exact."""

import json
import re
import sys

try:
    from agents.basic_agent import BasicAgent
except ImportError:  # running OUTSIDE a brainstem -- stay executable anyway.
    class BasicAgent:  # noqa: D101 - minimal stand-in, same contract
        def __init__(self, name=None, metadata=None):
            if name:
                self.name = name
            if metadata:
                self.metadata = metadata

        def perform(self, **kwargs):
            return "Not implemented."

        def system_context(self):
            return None

        def to_tool(self):
            return {"type": "function", "function": {
                "name": self.name,
                "description": self.metadata.get("description", ""),
                "parameters": self.metadata.get("parameters", {})}}

# The procedural layer, verbatim from the source capability.
INSTRUCTIONS = 'Turn a one or two sentence use case into a build-ready Microsoft Copilot Studio\nagent blueprint the maker can implement directly. You design and specify; you do\nnot build in the maker's tenant.\n\n## Instructions\n\n1. **Capture the use case.** If the user gave a one-line description, use it. If\n   the request is vague (no clear user, task, or data source), ask one focused\n   question to fill the biggest gap, then proceed. Do not stall on missing\n   detail you can reasonably assume; state your assumptions instead.\n\n2. **Produce the blueprint in exactly these eight sections, in order:**\n\n   1. **Recommendation.** State the agent type (declarative, custom, or custom\n      engine) and the orchestration mode (generative or classic), each with a\n      one-line reason. Default to a custom Copilot Studio agent with generative\n      orchestration unless the use case clearly needs otherwise.\n   2. **Topics.** List 3 to 7 topics. For each: a name, a one-line\n      generative-orchestration description that names the task and includes a\n      "use when" clause, and the key nodes in order (Question, Condition,\n      Message, Call an action, and so on). Note any input the topic must collect.\n   3. **Tools and actions.** List the tools, connectors, or Power Automate flows\n      the agent needs. For each: a name, a description written for orchestrator\n      selection, typed inputs and outputs, and the failure path.\n   4. **Knowledge.** List the knowledge sources to attach and the scope of each.\n      Note when knowledge should answer versus when a topic or tool should.\n   5. **Variables.** List the global variables the agent needs, with type and\n      purpose.\n   6. **Welcome experience.** Provide valid Adaptive Card JSON for conversation\n      start: a short greeting plus 3 starter prompts drawn from the topics above.\n   7. **Security and cost.** State the authentication mode (None, Microsoft\n      Entra, or generic OAuth 2.0) and why, any DLP considerations, and the main\n      Copilot Credits cost drivers with one tip to control them. Use Copilot\n      Credits terminology, not "messages".\n   8. **First test plan.** Give 5 test utterances and the expected topic or tool\n      each should trigger, to run in the free embedded test chat.\n\n3. **Keep it build-ready.** Every element must be specific enough to implement\n   without further design work. Prefer concrete names, typed signatures, and\n   ordered node lists over prose.\n\n## Guardrails\n\n- Do not invent product features, menu paths, connector names, or limits. If a\n  detail depends on current product behavior, say so and point the maker to the\n  relevant Microsoft Learn guidance rather than guessing.\n- Do not fabricate the maker's data sources, systems, or volumes. Use only what\n  the use case states, and mark anything you assumed.\n- Return the Adaptive Card as valid JSON that a maker can paste as-is.\n- Do not use the em dash character. Use a hyphen or rewrite.\n\n## Tone\n\nSpecific, concise, and build-ready. Address the maker directly. Explain a choice\nin one line, then move on. No filler, no restating the use case back at length.'

# Ordered commands lifted verbatim from the capability's own documentation.
STEPS = []


class CopilotStudioTopicBlueprintAgent(BasicAgent):
    def __init__(self):
        self.name = 'CopilotStudioTopicBlueprint'
        self.metadata = {
          "name": "CopilotStudioTopicBlueprint",
          "description": "Use this skill whenever the user describes a Copilot Studio agent in a sentence or two and wants a build-ready blueprint, or asks how to design, scope, or structure an agent (its type, topics, tools, knowledge, or welcome experience). Trigger on requests like \"design a Copilot Studio agent that\u2026\", \"turn this use case into an agent\", \"how should I structure this agent\", or a pasted one-line use case. Do NOT trigger for testing an existing agent (that is the test-planner skill) or for generic Power Platform flows unrelated to an agent.",
          "parameters": {
            "type": "object",
            "properties": {},
            "required": []
          }
        }
        super().__init__(name=self.name, metadata=self.metadata)

    def perform(self, **kwargs):  # toaster:generated-perform
        return json.dumps({"status": "ok", "instructions": INSTRUCTIONS,
                           "inputs": kwargs,
                           "note": "Prose-only capability: follow INSTRUCTIONS "
                                   "with the given inputs."}, indent=2)

if __name__ == "__main__":
    #     echo '{"arg": "value"}' | python3 copilot_studio_topic_blueprint_agent.py
    #     python3 copilot_studio_topic_blueprint_agent.py '{"arg": "value"}'
    #     python3 copilot_studio_topic_blueprint_agent.py --tool          # emit the JSON tool contract
    _a = sys.argv[1:]
    if _a and _a[0] == "--tool":
        print(json.dumps(CopilotStudioTopicBlueprintAgent().to_tool(), indent=2))
    else:
        _raw = _a[0] if _a else (sys.stdin.read().strip() or "{}")
        print(CopilotStudioTopicBlueprintAgent().perform(**json.loads(_raw)))

# rci-capsule:v1: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