Workspace API

The Workspace API lets a plugin work with the Workspace it is installed in: list and edit Agents and Pipelines, look up bots, manage models and knowledge bases, read monitoring data, and so on. It exposes the same operations as LangBot's HTTP API, MCP server and Workspace assistant, so a plugin can automate anything a member could do through those interfaces, within the limits the member grants.

Every operation has a stable ID, such as pipeline.list or knowledge.base.retrieve. A plugin can only call operations it declares in its manifest and a member has granted to its installation.

Calling an operation

From any component, use self.plugin.workspace. Each operation has a typed method named after its ID:

from langbot_plugin.api.definition.components.tool.tool import Tool


class WorkspaceSummary(Tool):
    async def call(self, params, session, query_id):
        result = await self.plugin.workspace.pipeline.list()
        if not result["ok"]:
            return f"Could not list pipelines: {result['error']['message']}"

        names = [pipeline["name"] for pipeline in result["result"]]
        return "Pipelines: " + ", ".join(names)

Methods take keyword arguments that match the operation's input schema, and editors show their types and documentation. A few names are adjusted to be valid Python: a segment that is a Python keyword gets a trailing underscore (for example import_), and other invalid characters become underscores. The arguments are still sent under their original names.

If you prefer to choose the operation at runtime, call it by ID. Both forms behave identically:

result = await self.plugin.workspace.call("knowledge.base.retrieve", kb_uuid=kb_uuid, query="refund policy")

await self.plugin.workspace.list() returns the operations granted to the installation, with their input schemas, grouped into domains. It is useful for building a dynamic tool list or checking a grant before offering a feature.

Inside a Runner

A Runner receives a run-bound proxy as ctx.api.workspace. It offers the same methods and is authorized by the same installation grants; the difference is that LangBot records each call against the current run.

The Agent or Pipeline that started the run may restrict which workspace operations the model should see. That selection is delivered in ctx.resources.workspace_operations. A Runner that exposes workspace operations to a model as tools should offer only those, and offer none when the list is empty. LangBot's built-in LocalAgent does exactly this.

Results and errors

Workspace calls never raise for business errors. They always return a dictionary:

# Success
{"ok": True, "result": ..., "operation": {"id": "pipeline.list", ...}}

# Failure
{"ok": False, "error": {"code": "permission_denied", "message": "...", "details": {...}}}

Check ok before reading result. Common error codes:

A denied operation is an expected outcome, because members may grant only part of what a plugin declares. Handle it by explaining what is missing rather than failing the whole command or run.

Choosing operations to declare

Operations carry a risk level that the member sees when confirming:

• Read operations only return data, such as pipeline.list or stats.basic.
• Write operations change Workspace configuration, such as pipeline.update or knowledge.file.store.
• High-risk operations delete resources, reach outside LangBot, or consume significant resources, such as bot.delete or pipeline.chat.broadcast. The confirmation dialog highlights them.

The member who grants an operation must hold its permission themselves (the last column below). Ask only for what your plugin needs; a request for many high-risk operations is likely to be declined or trimmed.

Wildcards such as knowledge.* request every operation under a prefix. Not every prefix can be used this way; see Wildcards.

Operation reference

This reference covers every operation a plugin can request in the current LangBot version, grouped by domain. Methods are shown on workspace, which is self.plugin.workspace in components and ctx.api.workspace in a Runner. The SDK's typed methods are generated from this catalog, so every operation listed here is available as a method.

Adapter (adapter)

Agent (agent)

Bot (bot)

Extension (extension)

Knowledge Base (knowledge)

MCP (mcp)

Model (model)

Monitoring (monitoring)

Pipeline (pipeline)

Plugin (plugin)

Model Provider (provider)

Requester (requester)

Skill (skill)

Statistics (stats)

Tool (tool)