Choosing Coder Agents for a Session

Use enabledAgents and defaultAgent to choose which built-in or published custom Coder agents are available in a session

A session can start with the exact agents you care about. Use enabledAgents to choose the built-in or published custom agents mounted for a session, and defaultAgent when you want new work to route to one agent by default. The example below uses builder and reviewer; replace them with names your Hub exposes.

The Pattern

Create the session with an explicit agent selection, then inspect the session detail:

import { CoderClient } from '@agentuity/coder';
import { logger } from '@agentuity/telemetry';
 
const DEFAULT_TASK =
  'Inspect the repo, identify the main implementation risks, and suggest a clean next step.';
const ENABLED_AGENTS = ['builder', 'reviewer'] as const;
const DEFAULT_AGENT = 'builder';
 
function getTask(): string {
  const task = process.argv.slice(2).join(' ').trim();
  return task || DEFAULT_TASK;
}
 
async function main(): Promise<void> {
  const client = new CoderClient();
  const task = getTask();
 
  try {
    const created = await client.createSession({
      task,
      workflowMode: 'standard',
      // defaultAgent: the route target used when no specific agent is named
      defaultAgent: DEFAULT_AGENT, 
      // enabledAgents: the only built-in or published custom agents mounted for this session
      enabledAgents: [...ENABLED_AGENTS], 
      tags: ['docs-example', 'agent-selection'],
    });
 
    // Read the session back to confirm the agent roster, default agent, and lifecycle state
    const session = await client.getSession(created.sessionId);
 
    logger.info(
      JSON.stringify(
        {
          sessionId: session.sessionId,
          workflowMode: session.workflowMode,
          enabledAgents: session.enabledAgents,
          defaultAgent: session.defaultAgent,
          status: session.status,
          bucket: session.bucket,
        },
        null,
        2
      )
    );
  } catch (error) {
    const message = error instanceof Error ? error.stack ?? error.message : String(error);
    logger.error('Failed to create a Coder agent session');
    logger.error(message);
    process.exitCode = 1;
  }
}
 
void main();

Example Output

{
  "sessionId": "codesess_142090f92556",
  "workflowMode": "standard",
  "enabledAgents": ["builder", "reviewer"],
  "defaultAgent": "builder",
  "status": "creating",
  "bucket": "provisioning"
}

What this means:

  • enabledAgents limits which agents are mounted when you create the session
  • defaultAgent tells the Hub which agent should handle routed work by default
  • status and bucket still describe the lifecycle state of the session itself

How agent selection works

The simplest mental model:

  • enabledAgents is the set of specialists mounted for this session
  • defaultAgent is the preferred route target for session prompts
  • omitting both fields lets the Hub use its normal Coder Lead behavior

So if you create a session with:

{
  enabledAgents: ['builder', 'reviewer'],
  defaultAgent: 'builder',
}

you're saying: make builder and reviewer available, and route to builder by default.

When to use this pattern

Use this pattern when you want:

  • a focused implementation session with builder
  • a review-oriented session with reviewer
  • a tighter set of agents than the full default team
  • a consistent default specialist for repeated automation
  • a published custom specialist mounted alongside built-in agents

If you want a normal Coder session, omit both fields.

Key Points

  • Start with the agents you need. You can widen the selection later.
  • Prefer getSession() over list views when you need a definitive view of one session.
  • Use agent names your Hub exposes.
  • Publish custom-agent drafts before selecting their slugs in enabledAgents or defaultAgent.

See Also