Skip to main content

Developer Guide

This guide provides technical details about the CopilotStudioAgent model and its implementation within the Deepdesk assistant framework.

Overview​

The CopilotStudioAgent model enables integration with Microsoft Copilot Studio agents as tools within your assistants. When configured, these agents are automatically converted into callable tools that can be invoked by your assistant during conversations.

Data Model​

The CopilotStudioAgent model represents a Microsoft Copilot Studio agent that can be integrated as a tool within Deepdesk assistants.

Key Relationships:

  • Many-to-Many: Multiple assistants can use the same Copilot agent, and each assistant can have multiple Copilot agents
  • Tool Conversion: Each CopilotStudioAgent is automatically converted to a Tool when attached to an Assistant
  • Immutable Code: The code field becomes part of the tool name and cannot be changed after creation

Model Fields​

name (CharField)​

  • Type: String
  • Max Length: 255 characters
  • Required: Yes (blank=False)
  • Description: Human-readable name for the Copilot Studio agent
  • Example: "Customer Support Agent", "Order Processing Agent"

code (CharField)​

  • Type: String
  • Max Length: 45 characters
  • Required: Yes (blank=False)
  • Unique: Yes
  • Limitations:
    • Maximum 45 characters (restricted because the system prepends "copilot_agent__" (15 characters) to create the tool name, and total tool name length is limited to 64 characters)
    • Must be unique across all Copilot Studio agents
    • Cannot be modified after creation (read-only in admin interface)
  • Description: Unique identifier used to reference the agent programmatically
  • Example: "customer-support", "order-processor"

token_url (URLField)​

  • Type: URL
  • Required: Yes (blank=False)
  • Description: OAuth2 token endpoint URL for authenticating with the Copilot Studio agent
  • Example: "https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token"
info

To get the token URL navigate to your Copilot Studio agent → Channels → Direct Line Speech → Token Endpoint

description (TextField)​

  • Type: Text (unlimited length)
  • Required: Yes (blank=False)
  • Description: Concise description of what the agent does. This description is used by the LLM to determine when to invoke this agent, so it should be clear and comprehensive.
  • Best Practice: Include information about:
    • What the agent does
    • When it should be used
    • What kind of inputs it expects

Tool Conversion​

When a CopilotStudioAgent is attached to an assistant, it is automatically converted into a tool with the following structure:

{
  "name": "copilot_agent__{code}",
  "description": "{agent.description}",
  "parameters": {
    "type": "object",
    "properties": {
      "input": {
        "type": "string",
        "description": "The input to the copilot studio agent"
      }
    },
    "required": ["input"]
  }
}

Example: A Copilot Studio agent with code "customer-support" becomes a tool named "copilot_agent__customer-support".

Tool Invocation​

Invocation Flow​

Process Steps​

When the assistant's LLM determines that it needs to use the Copilot Studio agent:

  1. The LLM calls the tool with a string input
  2. The system authenticates with the token URL
  3. The input is sent to the Copilot Studio agent
  4. The agent's response is returned to the LLM
  5. The LLM incorporates the response into its final answer