Choosing Built-In Agents for a Coder Session — Agentuity Documentation

Choosing Built-In Agents for a Coder Session

Use agentSlugs and defaultAgent to choose which built-in Coder agents are available in a session

A session can start with only the built-in Coder agents you care about. Use agentSlugs to pick which built-ins are mounted, and defaultAgent to route prompts to a specific one instead of the normal lead flow. A builder-plus-reviewer pair is a common shape.

The Pattern

Create the session with an explicit built-in selection, then inspect the session detail:

import { CoderClient } from '@agentuity/coder';
 
const DEFAULT_TASK =
  'Inspect the repo, identify the main implementation risks, and suggest a clean next step.';
const AGENT_SLUGS = ['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 built-in the Hub routes to when no specific agent is named
      defaultAgent: DEFAULT_AGENT, 
      // agentSlugs: the only built-ins mounted for this session; others stay hidden
      agentSlugs: [...AGENT_SLUGS], 
      tags: ['docs-example', 'built-in-agents'],
    });
 
    // Read the session back to confirm the default agent and lifecycle state
    const session = await client.getSession(created.sessionId);
 
    console.log(
      JSON.stringify(
        {
          sessionId: session.sessionId,
          workflowMode: session.workflowMode,
          defaultAgent: session.defaultAgent,
          status: session.status,
          bucket: session.bucket,
        },
        null,
        2
      )
    );
  } catch (error) {
    const message = error instanceof Error ? error.stack ?? error.message : String(error);
    console.error('Failed to create a built-in agent session');
    console.error(message);
    process.exitCode = 1;
  }
}
 
void main();

Example Output

{
  "sessionId": "codesess_142090f92556",
  "workflowMode": "standard",
  "defaultAgent": "builder",
  "status": "creating",
  "bucket": "provisioning"
}

What this means:

  • agentSlugs limits which built-ins are mounted when you create the session
  • defaultAgent tells the Hub which built-in 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:

  • lead is the default orchestration posture for a normal session
  • agentSlugs is the set of built-in specialists mounted for this session
  • defaultAgent is the built-in preferred when the session isn't using the normal lead path

So if you create a session with:

{
  agentSlugs: ['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

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

Key Points

  • Start with the built-ins you need. You can widen the selection later.
  • Prefer getSession() over list views when you need a definitive view of one session.
  • Use built-in names your Hub exposes.
  • For agent definitions you author yourself, switch to the custom-agent flow.

See Also