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.

ACL

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.

Rust

Node.js

Python

Rust

use a3s_code_core::{Agent, SessionOptions};

#[tokio::main]
async fn main() -> a3s_code_core::Result<()> {
    let agent = Agent::new("agent.acl").await?;

    let fast = agent
        .session_builder("/repo")
        .options(SessionOptions::new().with_model("provider/fast-model"))
        .build()
        .await?;
    let draft = fast
        .send("Draft a short README intro for this project.", None)
        .await?
        .text;
    println!("draft: {draft}");
    fast.close().await;

    let review = agent
        .session_builder("/repo")
        .options(SessionOptions::new().with_model("provider/review-model"))
        .build()
        .await?;
    let critique = review
        .send(&format!("Critique this README intro:\n{draft}"), None)
        .await?;
    println!("critique: {}", critique.text);

    review.close().await;
    agent.close().await;
    Ok(())
}

TypeScript

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();

Python

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()

package main

import (
	"context"
	"fmt"
	"log"

	code "github.com/A3S-Lab/Code/sdk/go/v6"
)

func main() {
	ctx := context.Background()
	agent, err := code.Create(ctx, "agent.acl")
	if err != nil {
		log.Fatal(err)
	}
	defer agent.Close(context.Background())

	fast, err := agent.Session(ctx, "/repo", &code.SessionOptions{
		Model: "provider/fast-model",
	})
	if err != nil {
		log.Fatal(err)
	}
	draft, err := fast.Run(ctx, "Draft a short README intro for this project.")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("draft:", draft.Text)
	fast.Close(ctx)

	review, err := agent.Session(ctx, "/repo", &code.SessionOptions{
		Model: "provider/review-model",
	})
	if err != nil {
		log.Fatal(err)
	}
	defer review.Close(context.Background())
	critique, err := review.Run(ctx, "Critique this README intro:\n"+draft.Text)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("critique:", critique.Text)
}

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.

Rust

Node.js

Python

Rust

use a3s_code_core::{
    subagent::ModelConfig as WorkerModelConfig, Agent, SessionOptions, WorkerAgentSpec,
};
use serde_json::json;

#[tokio::main]
async fn main() -> a3s_code_core::Result<()> {
    let agent = Agent::new("agent.acl").await?;

    let mut scout = WorkerAgentSpec::read_only(
        "scout",
        "Reads files and reports findings.",
    );
    scout.model = Some(WorkerModelConfig::from_model_ref(
        "provider/fast-model",
    ));
    let session = agent
        .session_builder("/repo")
        .options(
            SessionOptions::new()
                .with_model("provider/review-model")
                .with_worker_agent(scout),
        )
        .build()
        .await?;

    let findings = session
        .tool(
            "task",
            json!({
                "agent": "scout",
                "description": "List public APIs",
                "prompt": "List every public API in src/."
            }),
        )
        .await?;
    let plan = session
        .send(
            &format!("Given these findings, propose a refactor:\n{}", findings.output),
            None,
        )
        .await?;
    println!("{}", plan.text);

    session.close().await;
    agent.close().await;
    Ok(())
}

TypeScript

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();

Python

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()

package main

import (
	"context"
	"fmt"
	"log"

	code "github.com/A3S-Lab/Code/sdk/go/v6"
)

func main() {
	ctx := context.Background()
	agent, err := code.Create(ctx, "agent.acl")
	if err != nil {
		log.Fatal(err)
	}
	defer agent.Close(context.Background())

	session, err := agent.Session(ctx, "/repo", &code.SessionOptions{
		Model: "provider/review-model",
	})
	if err != nil {
		log.Fatal(err)
	}
	defer session.Close(context.Background())

	findings, err := session.Task(ctx, code.DelegateTaskOptions{
		Agent:       "explore",
		Description: "List public APIs",
		Prompt:      "List every public API in src/.",
		Model:       "provider/fast-model",
	})
	if err != nil {
		log.Fatal(err)
	}
	plan, err := session.Run(
		ctx,
		"Given these findings, propose a refactor:\n"+findings.Output,
	)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(plan.Text)
}

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 sdk/node/examples/basic/test_api_alignment.ts.

#Model Switching

#Declaring models

#Per-session model

#Per-worker-agent model override

Model Switching

Declaring models

Per-session model

Per-worker-agent model override