Get Started

Agents CLI

View as Markdown

The smallestai agents command group manages the agent itself. Create new agents, list what you have, look up config, print a dashboard URL, check phone-number status, and place outbound calls. It sits alongside smallestai agent-crew (which manages crew code) and smallestai auth (which manages credentials). One binary, three concerns.

Setup

$pip install smallestai

Auth resolution is the same across every smallestai subcommand.

  1. SMALLEST_API_KEY environment variable. Takes precedence.
  2. ~/.smallestai/credentials.json. Written by smallestai auth login.

If neither is set, every agents command exits with an auth error before making a request.

Base URL. Set SMALLEST_BASE_URL to point at a non-production environment (https://api.dev.smallest.ai, self-hosted, etc.). Defaults to https://api.smallest.ai.

Commands

Usage: smallestai agents create [OPTIONS] {name}

Creates an agent with the given name. Everything else is optional and can be set later from the dashboard, edit_and_publish, or the versioning API.

Arguments

ArgumentTypeDescription
namestring, requiredHuman label for the agent.

Options

OptionTypeDescription
--first-messagestringThe greeting the agent speaks when a call connects.
--promptstringGlobal system prompt.
--descriptionstringInternal description shown in the dashboard.
--allow-inboundflagEnable inbound calls on this agent.

Example

$smallestai agents create "support-bot" \
>  --prompt "You are a friendly support agent. Keep answers under 20 words." \
>  --first-message "Hi! How can I help you today?" \
>  --allow-inbound

Prints the created agent’s ID.

Usage: smallestai agents list [OPTIONS]

No arguments. Returns every agent the API key can see, most-recently-created first. Useful for grabbing an ID to feed the other commands.

Usage: smallestai agents get [OPTIONS] {agent_id}

Prints the full agent config. Includes prompt, voice, language, model, tools, timeouts, and every other field. What you see is the active revision on the live branch, which is the exact config used on the next call. See Agent Versioning for the branch and revision model.

Usage: smallestai agents dashboard {agent_id}

Prints the dashboard URL for the agent. Pipe to open (macOS) or xdg-open (Linux) to jump straight there.

$smallestai agents dashboard <agent_id> | xargs open
Usage: smallestai agents phone-status {agent_id}

Shows whether the agent has a phone number assigned. Run before agents call. If phone-status says no number is attached, the outbound call fails with a missing-caller-ID error. Rent or attach a number from Deploy → Phone Numbers first.

Usage: smallestai agents call [OPTIONS] {agent_id}

Dials --to from the agent, using either the agent’s assigned number or the one you pass via --from-product-id. The command exits as soon as the call is queued; check status with client.atoms.calls.get(id=call_id) (see gotcha below).

Options

OptionRequiredDescription
--toyesDestination phone number in E.164 format (e.g. +14155550100).
--from-product-idnoProduct ID of the acquired number to dial from. Omit to use the agent’s assigned number.

Example

$smallestai agents call <agent_id> \
>  --to +14155550100 \
>  --from-product-id <product_id>

Prints the call ID on success. Track status with client.atoms.calls.get(id=<call_id>).

client.atoms.calls.get(...) takes id=<call_id> as the keyword, not conversation_id=.

End-to-end example

Create an agent, check its phone attachment, place a call.

$# 1. Create
$AGENT_ID=$(smallestai agents create "quick-test" \
>  --prompt "You are a curt assistant. Confirm you heard the caller in one sentence." \
>  --first-message "Hi, are you there?" | tail -n1)
$
$# 2. Attach a phone number (dashboard step, one-time)
$smallestai agents dashboard "$AGENT_ID" | xargs open
$
$# 3. Sanity-check the phone attachment
$smallestai agents phone-status "$AGENT_ID"
$
$# 4. Place the call
$smallestai agents call "$AGENT_ID" --to "+14155550100"

Diagnose a crew agent

smallestai agent-crew doctor inspects an agent’s live config and flags the mistakes that most often stop a crew agent from working:

$smallestai agent-crew doctor                 # the agent linked in this project
$smallestai agent-crew doctor --agent-id <id> # or a specific agent

It checks for:

  • No live crew build (deploy hasn’t been made live, so your code isn’t serving).
  • A workflow type that isn’t single_prompt (a crew attaches to single-prompt agents).
  • PII redaction turned on (it rewrites the transcript, including emails and numbers).
  • transfer_call enabled in the dashboard Tools panel (ignored for a crew agent, and a common source of confusion).

It then prints the crew-vs-platform ownership tables below.

Config ownership: crew vs platform

A crew build takes over only the LLM turn. Everything else about the call stays on the platform agent config and is read fresh on each call.

  • Your crew code owns: the system prompt, LLM messages, function tools (@function_tool, including transfer_call), end_call, speak(), and mute/unmute. Change these in code and agent-crew deploy.
  • The platform owns (your crew cannot override at runtime): voice/TTS, STT provider and language, PII redaction, first message, interruption, voicemail detection, timeouts, background sound, and pronunciation. Change these in the agent settings; they take effect on the next call, no redeploy.

Two consequences worth knowing:

  • The dashboard Tools panel (including its transfer_call toggle) is a single-prompt control. For a crew agent it is ignored, so enabling it there does nothing. Define tools in code.
  • New agents created from the dashboard have PII redaction ON by default. Redaction rewrites emails, names, and numbers in the surfaced transcript (and can trim a few leading words around them). If you don’t want it, set redactionConfig.isEnabled to false in the agent settings.
Quickstart Crew CLI

Deploy your own crew code alongside the platform agent.

Build your agent

The ordered guide to configuring an agent from the dashboard.

Agent Versioning

Branches, drafts, and revisions for the agent config.

Versioning lifecycle (SDK)

Publish, restore, and diff revisions programmatically.