EnableConfigDiscovery - Incorrect Behaviour

[shudles]

The SessionConfig.EnableConfigDiscovery property's summary tag reads:

    /// <summary>
    /// When <see langword="true"/>, automatically discovers MCP server configurations
    /// (e.g. <c>.mcp.json</c>, <c>.vscode/mcp.json</c>) and skill directories from
    /// the working directory and merges them with any explicitly provided
    /// <see cref="McpServers"/> and <see cref="SkillDirectories"/>, with explicit
    /// values taking precedence on name collision.
    /// <para>
    /// Custom instruction files (<c>.github/copilot-instructions.md</c>, <c>AGENTS.md</c>, etc.)
    /// are always loaded from the working directory regardless of this setting.
    /// </para>
    /// </summary>
    public bool? EnableConfigDiscovery { get; set; }

Using this simple example, you can discover it's not this the case. Agents will ONLY be loaded when the value is set to true. Which is counter to:
"Custom instruction files (.github/copilot-instructions.md, AGENTS.md, etc. are always loaded from the working directory regardless of this setting"

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 = false, // switch this to true if you want agents to be actually loaded.
});

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

foreach (var agent in agentsList.Agents)
{
    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!

Additionally, are there any plans to support an AgentsDirectories property similar to SkillDirectories, PluginDirectories & InstructionDirectories?

[github-actions]

Investigation findings

Files reviewed: dotnet/src/Types.cs (lines 2885–2896), dotnet/test/E2E/SkillsE2ETests.cs, dotnet/test/E2E/RpcAgentE2ETests.cs

---

What's happening

The reported behavior is working as designed, but the XML doc comment for EnableConfigDiscovery is ambiguous and has caused a reasonable misunderstanding.

There are two distinct concepts at play here that have similar-sounding names:

Concept	Example paths	What it does	Controlled by
Custom instruction files	AGENTS.md, .github/copilot-instructions.md	Markdown files injected into the AI's system prompt as project context/guidelines	Always loaded, regardless of EnableConfigDiscovery
Custom agent definitions	.github/agents/sample.agent.md	Defines a named subagent (with its own prompt, tools, etc.) that can be selected at runtime	Requires EnableConfigDiscovery = true to be auto-discovered

The doc comment's mention of AGENTS.md refers to the first category — an AI-conventions instruction file (similar to README.md but consumed as context by AI tools like Claude Code). It is not referring to .github/agents/*.agent.md custom agent definition files.

Your .github/agents/sample.agent.md file defines a new subagent, which falls under config discovery. Setting EnableConfigDiscovery = false intentionally suppresses that auto-discovery, so your sample agent won't appear in Agent.ListAsync() unless you also provide it via the CustomAgents property in SessionConfig.

---

Why this is a documentation issue

The doc comment is misleading because it mentions AGENTS.md without clarifying that this refers to a flat instruction file convention — not custom agent definition files under .github/agents/. A reader can reasonably interpret "AGENTS.md, etc." as covering .github/agents/ agent files.

The specific documentation gaps are:

1. EnableConfigDiscovery doc comment (Types.cs line 2885–2895) should explicitly state that custom agent definition files (.github/agents/*.agent.md) are part of config discovery and are not loaded when EnableConfigDiscovery = false.
2. The comment should clarify that AGENTS.md is an AI-convention instruction file (project context for AI tools), distinct from custom agent definitions.

---

Regarding AgentsDirectories

Your second question — whether an AgentsDirectories property is planned — is a separate feature request. Currently, the workaround is to use the CustomAgents property in SessionConfig to register agent definitions programmatically, rather than relying on filesystem discovery. InstructionDirectories exists for adding extra instruction file directories, and PluginDirectories bundles agents + MCP + skills together, but there is no standalone AgentsDirectories equivalent at this time.

I've labelled this documentation to track the doc improvement needed for EnableConfigDiscovery.

Generated by Bug Handler for issue #1887 · sonnet46 1.2M · ◷

[shudles]

@github-github-actions-bot, I don't think AGENTS.md is an example of a "Custom instruction files"