CustomAgents - Ignores agents loaded from .github/agents folder

[shudles]

When you set SessionConfig.CustomAgents all agents that would be otherwise loaded from the workspace .github/agent folder are ignored

This simple examples shows the behaviour

using GitHub.Copilot;

// path to .github folder containing agents folder
const string WorkingDirectory = @"C:\SomeWorkspace";

await using var client = new CopilotClient();

await using var session = await client.CreateSessionAsync(new SessionConfig
{
    WorkingDirectory = WorkingDirectory,
    EnableConfigDiscovery = true, // Note that this has to be true to get any agents to load from disk - (see https://github.com/github/copilot-sdk/issues/1887)
    CustomAgents = [ // Remove this property and you'll see that all agents are loaded from the .github/agents folder
        new() {
            Name = "Custom"
        }
    ]
});

var agentsList = await session.Rpc.Agent.ListAsync();

foreach (var agent in agentsList.Agents)
{
    // You'll only see the "Custom" agent.
    Console.WriteLine(agent.Name);
}

Agent file I was using in a .github/agents/sample.agent.md file:

---
name: sample
description: Sample Agent
---

You are an sample agent for this repository, you're just happy to be here!

The agent list isn't merged together like skills, instructions and MCPs are.

Additionally, are there any plans to bring the agents loaded in via the CustomAgents property into full parity with agents loaded from the .github/agents folder? It seems that not all properties are supported, like Handoffs, which means no SessionHandoffEvent can ever be raised and agent passing can only happen via sub-agents via the task tool.

[github-actions]

Investigation findings

Thanks for the detailed report. I investigated the relevant code in the .NET SDK (dotnet/src/Types.cs, dotnet/src/Client.cs) and the documentation (docs/features/custom-agents.md) to understand this behavior.

What I found

The non-merging behavior is by design, not a bug. The EnableConfigDiscovery property's documentation explicitly describes what it merges:

When true, automatically discovers MCP server configurations (e.g. .mcp.json, .vscode/mcp.json) and skill directories from the working directory and merges them with any explicitly provided McpServers and SkillDirectories, with explicit values taking precedence on name collision.

Agents from .github/agents are not listed among what gets merged. The SDK simply passes both customAgents and enableConfigDiscovery as separate parameters to the Copilot CLI runtime — no merge is performed on the SDK side either. The runtime treats programmatic CustomAgents and workspace-discovered agents as distinct, non-combined sources.

This asymmetry is real — MCPs and skills are merged, but agents are not — but it reflects the current design rather than a defect.

On the Handoffs / SessionHandoffEvent parity concern

You are correct that CustomAgentConfig (in dotnet/src/Types.cs) does not expose a Handoffs property. The current public properties are: Name, DisplayName, Description, Tools, Prompt, McpServers, Infer, Skills, and Model. SessionHandoffEvent exists in the generated session events, but it can only be raised by workspace-file-based agents today.

Reclassification

Both observations — merging workspace agents with CustomAgents when EnableConfigDiscovery is true, and adding Handoffs support and other missing properties to CustomAgentConfig — represent new capabilities beyond what is currently designed and documented. I'm relabelling this as an enhancement request.

The workaround today, as you noted, is to either:

• Use only CustomAgents (and duplicate any workspace agents programmatically), or
• Use only EnableConfigDiscovery = true without setting CustomAgents (relying entirely on .github/agents files).

Agent merging and full CustomAgentConfig parity with workspace agents would be a valuable addition to the SDK. Leaving this open for the team to evaluate.

Generated by Bug Handler for issue #1889 · sonnet46 2M · ◷