Agents

Create a new agent

Changed on

Create a new agent by passing the agent name in the request body.

New agents have versioning enabled by default. To set the prompt, firstMessage, tools, or any runtime config, fork a draft from the auto-created initial version, edit it, publish, and activate — see the Versioning Lifecycle guide for the full flow.

The legacy PATCH /workflow/{workflowId} endpoint writes directly to the underlying workflow document and bypasses the version lifecycle; edits made that way are not captured as a version and may not propagate to live calls. Use the drafts flow above.

post/agent

Request

  • Base URL
    https://api.smallest.ai/atoms/v1
  • URL
    https://api.smallest.ai/atoms/v1/agent
  • Auth
    HTTP bearer

Request body

namestring required
descriptionstring
backgroundSound'' | 'office' | 'cafe' | 'call_center' | 'static'

Ambient background sound during calls. Options: '' (none), 'office', 'cafe', 'call_center', 'static'. Note: this value is currently overridden by the server default on creation; update via PATCH after creation.

globalKnowledgeBaseIdstring

The global knowledge base ID of the agent. You can create a global knowledge base by using the /knowledgebase endpoint and assign it to the agent. The agent will use this knowledge base for its responses.

slmModel'electron' | 'electron-kogta' | 'electron-kogta-v2' | 'gpt-4o' | 'gpt-4.1' | 'gpt-5.2' | 'gpt-5.2-azure' | 'gpt-realtime' | 'gpt-realtime-mini'

The LLM model to use for the agent. Note: gpt-5.2, electron-kogta, and electron-kogta-v2 require org-level access and return 403 if not enabled. workflowType must be single_prompt to use gpt-realtime or gpt-realtime-mini.

defaultVariablesobject

The default variables to use for the agent. These variables will be used if no variables are provided when initiating a conversation with the agent.

globalPromptstring

Set global instructions for your agent's personality, role, and behavior throughout conversations. Note: Only used for workflow_graph agents. Maximum 4000 characters.

telephonyProductIdstring[]

IDs of telephony products (phone numbers) to associate with the agent for inbound/outbound calls.

workflowType'workflow_graph' | 'single_prompt' | 'multi_agents'

The type of workflow configuration.

  • single_prompt — simple prompt-based agent (default).
  • workflow_graph — node-based visual workflow. Restricted: requires the conversational-agents org flag. Requests without that flag receive HTTP 403 "Conversational Flow agents are no longer available for your organization." The Zod validator still accepts this enum value on any org, but the authorization middleware gates it.
  • multi_agents — multi-agent orchestration (restricted; requires slmModel to be one of [electron, gpt-5.2-azure]).
firstMessagestring

The first message the agent sends when a conversation starts.

muteUserUntilFirstBotResponseboolean

When true, the user's audio is muted until the agent has finished its first response.

allowInterruptionsboolean

Whether the user can interrupt the agent while it is speaking.

waitForUserToSpeakFirstboolean

When true, the agent waits for the user to speak before sending the first message.

interruptionBackoffTimernumber

Seconds the agent waits after being interrupted before resuming speech.

callDispositionConfigstring

Configuration string for call disposition tracking.

allowInboundCallboolean

Whether the agent accepts inbound calls.

enableStyleGuideboolean

Whether style guide enforcement is applied to agent responses.

speechFormattingboolean

Whether speech formatting is applied to the agent's responses.

Response

Agent created successfully

statusboolean
datastring

The ID of the created agent

Example response

{
  "status": true,
  "data": "60d0fe4f5311236168a109ca"
}

Changes

  • 49ce8525306eRevision changes
    • info

      added the new gpt-5.2-azure enum value to the request property

    • info

      added the new multi_agents enum value to the request property

  • 04f7dfc02771Revision changes
    • info

      added the new de enum value to the request property /

    • info

      added the new de enum value to the request property //

    • info

      added the new fr enum value to the request property /

    • info

      added the new fr enum value to the request property //

    • info

      added the new it enum value to the request property /

    • info

      added the new it enum value to the request property //

    • info

      added the new kn enum value to the request property /

    • info

      added the new kn enum value to the request property //

    • info

      added the new ml enum value to the request property /

    • info

      added the new ml enum value to the request property //

    • info

      added the new nl enum value to the request property /

    • info

      added the new nl enum value to the request property //

    • info

      added the new pt enum value to the request property /

    • info

      added the new pt enum value to the request property //

    • info

      added the new ru enum value to the request property /

    • info

      added the new ru enum value to the request property //

    • info

      added the new te enum value to the request property /

    • info

      added the new te enum value to the request property //