#Model Switching

A session runs against whatever model you pass in the model option. Declare the models your agent can reach once, then pick one per session — a fast model for high-volume, low-stakes work and a stronger model for review. Use this when you want to balance cost against capability without changing any of your prompts.

#Declaring models

Models are configured in your agent file. Each provider lists the models it exposes, and default_model is used when a session does not set model.

default_model = "provider/fast-model"

providers "provider" {
  apiKey = env("PROVIDER_API_KEY")
  baseUrl = env("PROVIDER_BASE_URL")

  models "fast-model" { tool_call = true }
  models "review-model" { tool_call = true }
}

#Per-session model

The model option is set when you open the session. Everything that session runs — send, run, task, parallel, pipeline — uses that model. One agent configuration can drive different model choices for different sessions.

import { Agent } from '@a3s-lab/code';

const agent = await Agent.create('agent.acl');

// A fast model for high-volume, low-stakes work.
const fast = agent.session('/repo', { model: 'provider/fast-model' });
const draft = await fast.run('Draft a short README intro for this project.');
console.log('draft:', draft);
await fast.close();

// A stronger model for review / higher-stakes reasoning.
const review = agent.session('/repo', { model: 'provider/review-model' });
const critique = await review.run(`Critique this README intro:\n${draft}`);
console.log('critique:', critique);
await review.close();

from a3s_code import Agent, SessionOptions

agent = Agent.create("agent.acl")

# A fast model for high-volume, low-stakes work.
fast_opts = SessionOptions()
fast_opts.model = 'provider/fast-model'
fast = agent.session('/repo', fast_opts)
draft = fast.run('Draft a short README intro for this project.')
print('draft:', draft)
fast.close()

# A stronger model for review / higher-stakes reasoning.
review_opts = SessionOptions()
review_opts.model = 'provider/review-model'
review = agent.session('/repo', review_opts)
critique = review.run(f'Critique this README intro:\n{draft}')
print('critique:', critique)
review.close()

#Per-worker-agent model override

Worker agents are registered with their own spec. Give a worker its own model so it runs on a different (often smaller, cheaper) model than the session that delegates to it. The orchestrating session keeps its own model; only the delegated work runs on the worker's model.

import { Agent } from '@a3s-lab/code';

const agent = await Agent.create('agent.acl');

const session = agent.session('/repo', {
  // Orchestrator stays on the stronger model.
  model: 'provider/review-model',
  // High-volume exploration runs on the cheaper model.
  workerAgents: [
    {
      name: 'scout',
      description: 'Reads files and reports findings.',
      model: 'provider/fast-model',
    },
  ],
});

// Delegate exploration to the cheaper worker, then reason on the strong model.
const findings = await session.task({
  agent: 'scout',
  description: 'List public APIs',
  prompt: 'List every public API in src/.',
});
const plan = await session.run(
  `Given these findings, propose a refactor:\n${findings.output}`,
);
console.log(plan);

session.close();

from a3s_code import Agent, SessionOptions, WorkerAgentSpec

agent = Agent.create("agent.acl")

opts = SessionOptions()
# Orchestrator stays on the stronger model.
opts.model = 'provider/review-model'
# High-volume exploration runs on the cheaper model.
scout = WorkerAgentSpec(
    name='scout',
    description='Reads files and reports findings.',
)
scout.model = 'provider/fast-model'
opts.worker_agents = [scout]
session = agent.session('/repo', opts)

# Delegate exploration to the cheaper worker, then reason on the strong model.
findings = session.task({
    "agent": "scout",
    "description": "List public APIs",
    "prompt": "List every public API in src/.",
})
plan = session.run(f'Given these findings, propose a refactor:\n{findings.output}')
print(plan)

session.close()

Notes:

• The model value is an identifier string your runtime resolves to one of the models declared in your agent file — there are no hard-coded model names in the SDK.
• A worker agent's model applies only to that agent's delegated work. The session's own send/run/task calls still use the session model.
• A worker without a model inherits the session model, so you only override the agents where a different model actually pays off.

A runnable version showing the model option on a session ships at crates/code/sdk/node/examples/basic/test_api_alignment.ts.