Agents

toothfairyai@latest…

Manager for agent operations.

This manager provides methods to create, update, and manage AI agents.

Example:

>>> client = ToothFairyClient(api_key="...", workspace_id="...")
>>> agent = client.agents.create(
...     label="Customer Support",
...     mode="retriever",
...     interpolation_string="You are a helpful assistant...",
...     goals="Help customers with their questions",
...     temperature=0.7,
...     max_tokens=2000,
...     max_history=10,
...     top_k=10,
...     doc_top_k=5
... )

Accessed via client.agents.

Methods

Method	HTTP	Endpoint
`create`	POST	`POST /agent/create`
`get`	GET	`GET /agent/get/{agent_id}`
`update`	POST	`POST /agent/update`
`delete`	DELETE	`DELETE /agent/delete/{agent_id}`
`list`	GET	`GET /agent/list`
`get_by_mode`	—	derived
`search`	—	derived

create

Create a new agent.

def create(
    label: str,
    mode: AgentMode,
    interpolation_string: str,
    goals: str,
    temperature: float,
    max_tokens: int,
    max_history: int,
    top_k: int,
    doc_top_k: int,
    description: Optional[str] = None,
    pertinence_passage: Optional[str] = None,
    inhibition_passage: Optional[str] = None,
    default_answer: Optional[str] = None,
    no_knowledge_default_answer: Optional[str] = None,
    subject: Optional[str] = None,
    max_topics: Optional[int] = None,
    min_retrieval_score: Optional[float] = None,
    allowed_topics: Optional[List[str]] = None,
    static_docs: Optional[List[str]] = None,
    has_topics_context: Optional[bool] = None,
    topic_enhancer: Optional[bool] = None,
    key_words_for_knowledge_base: Optional[bool] = None,
    summarisation: Optional[bool] = None,
    compressor: Optional[bool] = None,
    has_memory: Optional[bool] = None,
    is_long_term_memory_enabled: Optional[bool] = None,
    has_functions: Optional[bool] = None,
    agent_functions: Optional[List[str]] = None,
    llm_provider: Optional[str] = None,
    llm_base_model: Optional[str] = None,
    function_calling_provider: Optional[str] = None,
    function_calling_model: Optional[str] = None,
    has_moderation: Optional[bool] = None,
    moderation_message: Optional[str] = None,
    has_ner: Optional[bool] = None,
    show_agent_name: Optional[bool] = None,
    hide_reasoning: Optional[bool] = None,
    plain_text_output: Optional[bool] = None,
    extended_output: Optional[bool] = None,
    show_citations: Optional[bool] = None,
    icon: Optional[str] = None,
    color: Optional[str] = None,
    placeholder_input_message: Optional[str] = None,
    message_on_launch: Optional[str] = None,
    disclaimer: Optional[str] = None,
    quick_questions: Optional[str] = None,
    prevent_widget_usage: Optional[bool] = None,
    allow_feedback: Optional[bool] = None,
    restricted_access: Optional[bool] = None,
    restricted_access_users: Optional[List[str]] = None,
    is_multi_language_enabled: Optional[bool] = None,
    advanced_language_detection: Optional[bool] = None,
    allow_email_to_agent: Optional[bool] = None,
    communication_services: Optional[List[str]] = None,
    charting: Optional[bool] = None,
    allow_images_upload: Optional[bool] = None,
    allow_audios_upload: Optional[bool] = None,
    allow_docs_upload: Optional[bool] = None,
    has_images: Optional[bool] = None,
    prompt_top_keywords: Optional[int] = None,
    agentic_rag: Optional[bool] = None,
    re_rank: Optional[bool] = None,
    blender: Optional[bool] = None,
    allow_internet_search: Optional[bool] = None,
    allow_deep_internet_search: Optional[bool] = None,
    has_code: Optional[bool] = None,
    allow_external_api: Optional[bool] = None,
    allow_images_generation: Optional[bool] = None,
    allow_videos_generation: Optional[bool] = None,
    chain_of_thoughts: Optional[bool] = None,
    agents_pool: Optional[List[str]] = None,
    max_planning_steps: Optional[int] = None,
    planning_instructions: Optional[str] = None,
    voice_name: Optional[str] = None,
    voice_instructions: Optional[str] = None,
    reasoning_budget: Optional[int] = None,
    reasoning_effort: Optional[str] = None,
    use_interleaved_reasoning: Optional[bool] = None,
    interleaved_preset: Optional[str] = None,
    max_total_tool_calls: Optional[int] = None,
    max_consecutive_same_tool: Optional[int] = None,
    max_consecutive_failures: Optional[int] = None,
    enable_json_output: Optional[bool] = None,
    json_output_structure: Optional[Dict[str, Any]] = None,
    custom_code_execution_environments: Optional[List[str]] = None
) -> Agent

Endpoint: POST /agent/create · API service

Request fields

Field	Type	Required	Description
`id`	`string`	no	Unique identifier
`workspaceid`	`string`	yes	Unique workspace identifier (UUID v4)
`label`	`string`	yes	Human-readable display name
`description`	`string`	no	Detailed description of purpose and capabilities
`interpolationString`	`string`	yes	The prompt text/template (with interpolation variables)
`customToolingInstructions`	`string`	no	Custom instructions for tool/function usage
`goals`	`string`	yes	Primary objectives the agent should achieve
`pertinencePassage`	`string`	no	Text passage used to improve response relevance
`inhibitionPassage`	`string`	no	Text passage defining prohibited behaviors or content
`defaultAnswer`	`string`	no	Default response when the agent cannot answer
`noKnowledgeDefaultAnswer`	`string`	no	Response shown when no relevant knowledge is found
`subject`	`string`	no	Subject matter expertise area
`qaUrl`	`string`	no	URL for Q&A/knowledge source
`mode`	`string`	yes	Operating mode of the agent: retriever (knowledge retrieval), coder (code execution), chatter (conversational), planner (multi-agent orchestration), computer (browser/desktop automation), or voice (voice interaction)

The Python SDK accepts snake_case keyword arguments and converts them to the camelCase wire fields shown above.

Response fields

Field	Type	Description
`id`	`string`	Unique identifier for the agent
`type`	`string`	Type classification of the agent (free-form string)
`label`	`string`	Human-readable name of the agent
`description`	`string`	Detailed description of the agent's purpose and capabilities
`interpolationString`	`string`	System prompt template for the agent
`emoji`	`string`	Emoji character representing the agent
`color`	`string`	Hex color code for agent display (light theme)
`darkColor`	`string`	Hex color code for agent display (dark theme)
`icon`	`string`	Icon identifier for the agent
`largeLogo`	`string`	URL to large logo image
`icoUrl`	`string`	URL to favicon/ico file
`logoBackground`	`string`	Background color for logo area (light theme)
`darkLogoBackground`	`string`	Background color for logo area (dark theme)
`messageOnLaunch`	`string`	Welcome message displayed on chat start
`messagesOnLaunch`	`array<string>`	List of welcome messages to rotate through
`rotateMessagesOnLaunch`	`boolean`	Whether to rotate welcome messages
`rotateMessagesOnLaunchInterval`	`integer`	Interval in seconds between message rotations
`placeholderMessageOnLoading`	`string`	Placeholder text shown while loading
`dynamicPlaceholderMessageOnLoading`	`boolean`	Whether to dynamically generate loading messages
`customGreetingInstructions`	`string`	Custom instructions for greeting generation
`customConclusionInstructions`	`string`	Custom instructions for conclusion generation
`customChartingInstructions`	`string`	Custom instructions for chart generation
`customSummarisationInstructions`	`string`	Custom instructions for summarization
`customImagesInstructions`	`string`	Custom instructions for image processing
`customToolingInstructions`	`string`	Custom instructions for tool/function usage
`placeholderInputMessage`	`string`	Placeholder text in input field
`openByDefault`	`boolean`	Whether agent is open by default in UI
`agenticCodingModel`	`string`	Model used for agentic coding tasks
`disclaimer`	`string`	Disclaimer text displayed to users
`showDocumentsReferences`	`boolean`	Whether to show document references in responses
`isDefault`	`boolean`	Whether this agent is the default for the workspace
`hasMemory`	`boolean`	Whether the agent maintains conversation memory
`hasImages`	`boolean`	Whether the agent can process images
`promptTopKeywords`	`integer`	Number of top keywords to extract from prompts
`keyWordsForKnowledgeBase`	`boolean`	Whether to use keywords for knowledge base queries
`hasTopicsContext`	`boolean`	Whether the agent considers topic context
`hasFunctions`	`boolean`	Whether the agent can execute functions
`advancedLanguageDetection`	`boolean`	Whether to use advanced language detection
`allowedTopics`	`object`	List of topic IDs the agent is restricted to
`staticDocs`	`object`	List of document IDs always included in context
`defaultAnswer`	`string`	Default response when agent cannot provide an answer
`noKnowledgeDefaultAnswer`	`string`	Response when no relevant knowledge is found
`quickQuestions`	`string`	Semicolon-separated quick question suggestions
`recencyImportance`	`number`	Importance weight for recency in retrieval
`maxRecencyIncrease`	`number`	Maximum recency boost factor
`recencyTopKIncreaseFactor`	`integer`	Factor to increase topK based on recency
`stopSequence`	`string`	Sequence that stops text generation
`examples`	`array<object>`	Example conversations for agent training
`enhancementPassage`	`string`	Text to enhance agent responses
`inhibitionPassage`	`string`	Text to prevent certain agent behaviors
`pertinencePassage`	`string`	Text to improve response relevance
`goals`	`string`	Primary objectives of the agent
`qaUrl`	`string`	URL for quality assurance endpoint
`topK`	`integer`	Number of top results to consider for retrieval
`mode`	`string`	Operating mode of the agent

Allowed: ready, notReady, dismissed, unknown, swapping | | llmUrlType | string | Type of LLM deployment

Allowed: auto, dynamic, always, never | | reasoningEffort | string | Level of reasoning effort

Allowed: none, low, medium, high | | fnReasoningEffort | string | Reasoning effort for function calls

Example

client.agents.create(label="…", mode=…, interpolation_string="…", goals="…", temperature=0.0, max_tokens=0 ...)

get

Get an agent by ID.

def get(agent_id: str) -> Agent

Endpoint: GET /agent/get/{agent_id} · API service

Response

Returns the Agent object — fields documented in the create section above.

Example

client.agents.get(agent_id="agent-id")

update

Update an agent.

def update(
    agent_id: str,
    label: Optional[str] = None,
    description: Optional[str] = None,
    temperature: Optional[float] = None,
    max_tokens: Optional[int] = None,
    max_history: Optional[int] = None,
    top_k: Optional[int] = None,
    doc_top_k: Optional[int] = None,
    charting: Optional[bool] = None,
    custom_code_execution_environments: Optional[List[str]] = None
) -> Agent

Endpoint: POST /agent/update · API service

Request fields

Field	Type	Required	Description
`id`	`string`	yes	Unique identifier
`workspaceid`	`string`	no	Unique workspace identifier (UUID v4)
`label`	`string`	no	Human-readable display name
`description`	`string`	no	Detailed description of purpose and capabilities
`interpolationString`	`string`	no	The prompt text/template (with interpolation variables)
`customToolingInstructions`	`string`	no	Custom instructions for tool/function usage
`goals`	`string`	no	Primary objectives the agent should achieve
`pertinencePassage`	`string`	no	Text passage used to improve response relevance
`inhibitionPassage`	`string`	no	Text passage defining prohibited behaviors or content
`defaultAnswer`	`string`	no	Default response when the agent cannot answer
`noKnowledgeDefaultAnswer`	`string`	no	Response shown when no relevant knowledge is found
`subject`	`string`	no	Subject matter expertise area
`qaUrl`	`string`	no	URL for Q&A/knowledge source
`mode`	`string`	no	Operating mode of the agent: retriever (knowledge retrieval), coder (code execution), chatter (conversational), planner (multi-agent orchestration), computer (browser/desktop automation), or voice (voice interaction)

The Python SDK accepts snake_case keyword arguments and converts them to the camelCase wire fields shown above.

Response

Returns the Agent object — fields documented in the create section above.

Example

client.agents.update(agent_id="agent-id")

delete

Delete an agent.

def delete(agent_id: str) -> Dict[str, bool]

Endpoint: DELETE /agent/delete/{agent_id} · API service

Response fields

Field	Type	Description
`success`	`boolean`	Operation success status
`data`	`object`	Response data
`message`	`string`	Optional success message

Example

client.agents.delete(agent_id="agent-id")

list

List all agents.

def list(
    limit: Optional[int] = None,
    offset: Optional[int] = None
) -> ListResponse

Endpoint: GET /agent/list · API service

Example

client.agents.list()

get_by_mode

Get agents by mode.

def get_by_mode(mode: AgentMode, limit: Optional[int] = None) -> List[Agent]

Derived method — delegates to another SDK call and performs no direct HTTP request.

Example

client.agents.get_by_mode(mode=…)

search

Search agents by label.

def search(search_term: str) -> List[Agent]

Derived method — delegates to another SDK call and performs no direct HTTP request.

Example

client.agents.search(search_term="…")

Agents​

Methods​

create​

Request fields​

Response fields​

Example​

get​

Response​

Example​

update​

Request fields​

Response​

Example​

delete​

Response fields​

Example​

list​

Example​

get_by_mode​

Example​

search​

Example​

Agents

Methods

create

Request fields

Response fields

Example

get

Response

Example

update

Request fields

Response

Example

delete

Response fields

Example

list

Example

get_by_mode

Example

search

Example