Plugins and tools

When the AI in a room calls a tool, it's calling a plugin. Plugins are how ScaiWave extends an AI's capabilities beyond what it can do with just words.

The standard set#

Plugin id	What it does
`scaiwave.web_search`	Query the live web (SearXNG-backed). Supports parallel multi-query fan-out.
`scaiwave.web`	Fetch a specific URL as cleaned markdown.
`scaiwave.notes`	Find, read, create, update notes.
`scaiwave.todos`	List, check, set due dates, assign todos.
`scaiwave.drive`	Search and fetch files from ScaiDrive (storage).
`scaiwave.knowledge`	Tenant-private RAG retrieval.
`scaiwave.calendar`	Calendar lookups (events, attendees, free/busy).
`scaiwave.calculator`	Exact arithmetic (no float drift).
`scaiwave.memory`	Long-term memory across conversations.
`scaiwave.skills`	Invoke skills from the ScaiSkills library.
`scaiwave.scailink`	Delegate to specialist tools registered by other ScaiLabs services.
`scaiwave.workspace_bridge`	Write into a workspace-bridged external service.
`scaiwave.files`	Access files attached in the current room.
`scaiwave.artifacts`	Create / edit canvas artifacts (collaborative documents within a chat).

Each plugin contributes one or more tools the AI can call. A tool has a name (web_search, find_note, drive_rag_context, …), a parameter schema, and a callable. The AI's prompt includes the full schema in OpenAI function-calling format.

When the AI uses a tool#

The model decides. The framework provides three things to steer that decision:

Tool descriptions in the schema (one-paragraph "what / when to use" for each).
Plugin-injected system context — each plugin can prepend a line to the AI's system prompt summarising its surface ("You can search ScaiDrive with drive_search…").
Tool-etiquette rules in the global system prompt: how to format calls, how to summarise results, what to do on errors.

Failure handling — the fallback chain#

When a tool errors, plugins return a structured failure that includes fallback suggestions — sibling tools the model should try instead. For example, a ScaiDrive RAG failure suggests web_search (for public info) or find_note (for tenant-private notes).

The AI sees the fallback list in the tool result. Tool-etiquette rule #4 explicitly instructs:

If a tool errors, look at the fallback suggestions and try the one that best fits the user's intent. When you use a fallback, tell the user in one sentence what failed and what you tried instead.

This is what prevents the "give up at the first 401" failure mode. See Planner § Failure recovery for the harness's contribution.

Tenant-level toggles#

Admins enable / disable each plugin per tenant under Admin → Plugins. Disabled plugins don't appear in any AI's toolbox in that tenant.

Room-level toggles#

You can disable a plugin for just one room with POST /v1/rooms/{room_id}/plugins/{plugin_id}/toggle. Useful when you want a tightly-scoped AI for a customer-facing chat that shouldn't be able to call drive_search.

Per-AI toggles#

Each AI participant has a plugins field that lists which plugins it can use. Set under Admin → AI → Helpers or with PUT /v1/admin/participants/{participant_id}/helper.

Writing your own plugin#

Plugins are Python classes implementing the BasePlugin protocol. See Tutorial: Write a plugin and Reference: Plugin protocol.

Permissions and side effects#

Plugins declare two things in their manifest:

Required permissions — READ_MESSAGES, WRITE_NOTES, EXTERNAL_HTTP, etc. The framework checks these before each invocation.
Side effect flag — true if the call mutates anything. Side-effect calls in multi-user rooms can be configured to require human approval before executing (the approval flow is exposed in the chat as a card with Approve / Reject buttons).

Where to go next#

Tutorial: Write a plugin.
Reference: Plugin protocol.
API: AI.