Ability to specify a custom agent when creating a session

[haoranpb]

The Copilot SDK allows defining a list of custom agents, but there's no way to specify which agent should be active when creating a session.

Would like the ability to programmatically invoke a specific custom agent without relying on model inference or prompt-based selection.

e.g. in Copilot CLI

copilot --agent MyCustomAgent

SDK equivalent:

session = await client.create_session({
    "agent": "MyCustomAgent"
})

[github-actions]

Thanks for opening this issue, @haoranpb!

This is a clear enhancement request for adding the ability to programmatically specify which custom agent should be active when creating a session. I've labeled this as enhancement.

The examples you provided (both CLI and Python SDK) are helpful for understanding the desired API. This would indeed provide more explicit control over agent selection compared to relying on model inference.

AI generated by Issue Triage Agent

[patniko]

Are you looking to use this to add custom built-in agents the harness can use or trying to instantiate the whole SDK with that agent? Curious to know more about your specific use case.

[haoranpb]

We run GitHub Copilot CLI in a pipeline (a code-generation evaluation for a DSL). We'd like to adopt Copilot SDK to get more control, e.g. collect metrics more reliably (we are currently parsing log files with regex to get tool usage)

In Copilot CLI (and similarly in VSCode Copilot Chat), we can do:

copilot --agent Plan --prompt "Investigate issue#1234 and come up with an implementation plan, store it in Plan.md"
copilot --agent Implement --prompt "Read the Plan.md and implement"

We want an SDK equivalent, similar to how model is specified:

session = await client.create_session({
    "model": "gpt-5",
    "agent": "Plan" # choose a specific registered custom agent deterministically 
})

Let me know if you need more details, happy to make a PR if this aligns with project direction

[varrascaeta]

Hey there! Interested in this issue here. We have a very similar use case for the agent mode. For now, i solved it by adding a preffix to the prompt like this: "Use the custom agent [agent-name] to solve this [rest of the prompt]"
But it would be nice to have the ability to specify it with the session options.

[ShrayRastogi]

Hey there! Interested in this issue here. We have a very similar use case for the agent mode. For now, i solved it by adding a preffix to the prompt like this: "Use the custom agent [agent-name] to solve this [rest of the prompt]" But it would be nice to have the ability to specify it with the session options.

Does it really work? Do you know a way to trace if the main agent is actually routing to or invoking the custom agent?

[varrascaeta]

Yes, it works. I was able to verify the routing in two ways.
First, inside the custom agent, I specified a specific output format. When invoking it, the main agent explicitly stated:

'I'll use the custom agent [agent-name] to solve your request'

Second, I traced the execution in .copilot/session-state/[session-id]/events.json. (usually located in your home folder). You can see the main agent triggering a tool.execution_start event with the custom agent passed as an argument.

In my case, I used an agent called migration-planner. Interestingly, the logs show the agent realized my prompt ("what can you do?") didn't match the custom agent's description (Azure analysis), but it decided to invoke it anyway because I explicitly asked for it.

Here is the relevant section of the events.json showing the reasoning and the invocation:

// The agent decides to use the tool despite the description mismatch
{
  "type": "assistant.message",
  "data": {
    "content": "I'll use the migration-planner agent to answer your question about capabilities.",
    "toolRequests": [
      {
        "name": "task",
        "arguments": {
          "agent_type": "migration-planner",
          "description": "Explain capabilities",
          "prompt": "What can you do? Please explain your capabilities and what tasks you can help with."
        },
        "type": "function"
      }
    ],
    "reasoningText": "The user is asking \"what can you do?\" and wants me to use the migration-planner agent to solve this. However, the migration-planner is described as \"Strictly analyzes codebases to map Azure dependencies, document business logic, and assess migration risks without generating migration code.\"\n\nLooking at the user's question, they're asking about capabilities - which according to my instructions under <self_documentation>, I should:\n1. ALWAYS call the **fetch_copilot_cli_documentation** tool FIRST\n2. Use the documentation returned to inform my answer\n3. Then provide a helpful, accurate response based on that documentation\n\nBut the user specifically asked me to \"use the migration-planner to solve this\". This is a bit unusual because the migration-planner is for analyzing codebases for Azure migrations, not for explaining my own capabilities.\n\nI think the user might be confused about what they want, OR they want to know what the migration-planner can do specifically. Let me follow their instruction literally - they want me to use the migration-planner to answer \"what can you do?\". \n\nSince this is somewhat ambiguous, I'll use the migration-planner agent to answer this question about capabilities. The migration-planner might interpret \"what can you do\" as asking about its own capabilities or might interpret it more broadly.\n\nLet me call the task tool with agent_type=\"migration-planner\" and ask it about what it can do."
  }
}

// The actual tool execution event
{
  "type": "tool.execution_start",
  "data": {
    "toolName": "task",
    "arguments": {
      "agent_type": "migration-planner",
      "description": "Explain capabilities",
      "prompt": "What can you do? Please explain your capabilities and what tasks you can help with."
    }
  }
}

Eventually, I got the expected output as specified inside the agent.md file.
Hope this helps!

[ShrayRastogi]

@varrascaeta - Thanks for providing detailed response. I am not sure if this works, can you check this discussion? #251

[ShrayRastogi]

@varrascaeta - Thanks for providing detailed response. I am not sure if this works, can you check this discussion? #251

@varrascaeta - I can confirm this works when do not use Tools and OnPermissionRequest handler while creating the session in dotnet.