Derbee Studio

1. Connect a provider and register a model. Add your OpenAI / Anthropic / Google / Azure credentials under Providers, then register the specific models you want available.
2. Create a knowledge base. Upload documents or paste raw text. Derbee chunks, embeds and indexes them automatically.
3. Write one or more templates. Define persona, task, constraints and output format once — the agent matches the right one per request.
4. Build the agent. Pick a model, attach the knowledge base, bind any MCP or API tools, and choose a grounding policy.
5. Attach a guardrail. Turn on prompt-injection detection, PII handling and topic limits before anyone else uses the agent.
6. Test in Chat. Send real questions, inspect the trace log, and check token and cost figures in Analytics.
7. Deploy. Issue an API key, connect a channel (WhatsApp / Outlook), or put the agent on a schedule.

An Agent is the core unit in Derbee Studio — a self-contained AI entity with a specific purpose. Each agent is configured with a model, prompt templates, a knowledge source, tool bindings and optional guardrails.

What it does: When a request arrives, the agent classifies the intent, matches the most relevant template, retrieves context (knowledge base, MCP tools, registered APIs or a channel), reasons over it, and returns a grounded answer — streaming as it goes.

Why it matters: Agents decouple the "intelligence" from the "plumbing." You define what the agent knows and how it should behave; the platform handles retrieval, tool execution, guardrail checks, logging and response generation automatically.

📖 Deep Dive Guide: For complete anatomy, runtime pipeline state machine schemas and tool bindings, see the dedicated Agents, Workflows & Teams Documentation ↗.

Knowledge source types

• rag — vector search over a knowledge base
• mcp — tools from an MCP server
• api_registry — registered REST endpoints
• channel — WhatsApp / Outlook actions
• none — pure model reasoning

Configuration

• Grounding & internet policy (strict / open)
• Attach one or more workflows
• Daily rate limit per agent
• Trace-log level multi-select
• Guardrail binding for input & output
• Deploy via API key, channel or chat
• Soft delete — deactivate without losing history
• Share with specific users and roles

A Workflow is a sequence of processing steps an agent runs after it retrieves context and before it produces a final response. Think of it as the agent's action plan. Workflows are standalone entities, so the same plan can be reused by several agents.

What it does: Each step is one discrete action. Steps can depend on each other, branch conditionally, or run in parallel — and each step has its own error policy.

Three authoring modes

• Linear — steps run top to bottom
• DAG — drag-and-drop canvas with dependency edges
• Dynamic — the model plans the steps at runtime

Available action types

• extract_keys — pull fields from text
• embed_fields — embed values for search
• rag_search — query a knowledge base
• llm_generate — generate text
• image_generate — local Ollama image model
• score — grade against a rubric
• transform_json — reshape to a schema
• conditional — branch on a condition
• mcp — call an MCP tool
• api_registry — call a registered API

Why it matters: Workflows let non-developers compose complex data pipelines visually, with per-step error handling (stop / skip / retry), parallel execution, and the full canvas layout persisted so the diagram is always the source of truth.

A Team is a graph of cooperating agents and control-flow blocks. Instead of one agent handling everything, each node is a specialist and the platform orchestrates their interaction. Agent nodes either reference an existing agent or carry their own inline model, instruction and tool bindings.

Three orchestration strategies

• Supervisor — one agent delegates and synthesises
• Sequential — a fixed chain, one after another
• Group — round-robin, every agent takes a turn

Block types on the canvas

• Supervisor & Worker agents
• LLM, Extract, Transform, Template
• Condition (true / false branches)
• Loop containers with nested blocks
• Tool, Variable, Aggregator, Code
• Human-in-the-loop approval (HITL)
• Start, End and Note blocks

Human-in-the-loop: a HITL block pauses the run before or after a step, shows the reviewer a prompt, and waits for approval — with an optional timeout and auto-approve fallback.

Why it matters: Problems that overwhelm a single agent (research → analysis → report) become manageable when split into roles. The graph runs on LangGraph, so the wiring owns control flow while a shared run context owns the data, and every node logs its request and response for deep execution tracing. A hard max steps ceiling and an explicit stop condition guarantee a run can never loop forever, and a team-level guardrail protects the perimeter.

📘 Full Architecture Guide: Explore all 17 LangGraph block definitions, flow examples and supervisor topologies in the Agents, Workflows & Multi-Agent Teams Manual ↗.

A Template is a structured prompt blueprint. Rather than writing raw prompts, you define the template once with clear sections — Persona, Context, Task, Reasoning, Constraints, Examples and Output Format — and agents reuse it.

What it does: When a message arrives, the agent's classifier matches it to the most relevant template using semantic (vector) similarity. The matched template shapes the agent's behaviour for that request, and its task and output-format sections can feed workflow steps directly.

Why it matters: Templates make agent behaviour predictable, auditable and easy to update. Non-technical team members can change what the agent says by editing a template — without touching any configuration or code.

• Dynamic variables (text, number, select)
• Semantic matching via embeddings
• Per-template skip flags (RAG, MCP, API, Web)
• Instruction mode for team agent nodes
• Share with specific users and roles
• Prompt enhancement assistant

📖 Deep Dive Guide: For complete anatomy of the 8 template fields, semantic selection algorithms, variable interpolation and prompt enhancement, see the dedicated Prompt Templates Documentation ↗.

Planner Steps are reusable, ordered instruction lists that steer a dynamic workflow. Instead of letting the model invent a plan from scratch on every run, you hand it the sequence you want it to follow.

What it does: Each step is one instruction line, optionally containing {{variable}} placeholders. Variables carry a description and a default, so the same planner works across agents and callers. Steps have stable ids, so reordering the list never breaks a reference.

Why it matters: You get the flexibility of dynamic planning with the repeatability of a fixed pipeline — the model still adapts to the input, but the shape of the work is yours.

The Knowledge Base is where your agent's domain knowledge lives. Upload documents (PDF, DOCX, TXT, CSV and more) or paste raw text, and Derbee Studio chunks, embeds and indexes them for fast vector search.

What it does: When an agent receives a question, it converts the question into an embedding, searches for the most relevant chunks, and injects them into the model's context — this is Retrieval-Augmented Generation (RAG).

Vector stores

• MongoDB Atlas Vector Search — managed, with index readiness checks
• Chroma — self-hosted collections, chosen per knowledge base

Ingestion

• Per-file chunk strategy, size and overlap
• Per-file status: pending → embedding → embedded
• File tagging for filtered retrieval
• PDF image extraction with a vision model
• Raw-text entries alongside uploads
• Web crawling with SPA fallback and redirect resolution
• Multiple embedding models
• Score thresholds and top-K capping

Why it matters: RAG lets agents answer from your data with sourced, accurate responses instead of relying on the model's general training data, which may be outdated or irrelevant to your domain.

📖 Deep Dive Guide: For document chunking schemas, vector indexing, hybrid search, and web crawling architecture, see the dedicated Knowledge Base & RAG Architecture Manual ↗.

The MCP Registry connects agents to external tool servers using the Model Context Protocol — an open standard for model-to-tool communication.

What it does: Register an MCP server (SSE, HTTP, Stdio or WebSocket), and its tools become available to any agent bound to it. The agent's model decides when and how to call these tools during reasoning, within a configurable ceiling on tool-call iterations per run.

Why it matters: MCP turns agents into actors that can query databases, interact with SaaS products, run code, or reach any service exposing an MCP interface — without custom integration code.

• SSE, HTTP, Stdio, WebSocket transports
• OAuth 2.0 flow with automatic token refresh
• Auth: Bearer, API Key, Basic, None
• Per-tool enable / disable
• Custom database tool configuration
• Dynamic tool discovery at bind time

📖 Deep Dive Guide: For SSE and stdio transport setup, OAuth token flows, and custom PostgreSQL/MySQL database tool creation, see the dedicated MCP Registry Technical Manual ↗.

The API Registry lets you register external REST APIs as callable tools. Define the endpoint URL, method, headers, query parameters and payload template — agents can invoke them during workflows or as part of their reasoning.

Why it matters: When your data or actions live behind a REST API (CRM lookups, payment status checks, notification triggers), the API Registry bridges the gap without any MCP server setup — just point and configure.

• GET, POST, PUT, DELETE, PATCH
• HTTPS-only enforcement
• Custom headers & query params
• Response structure preview
• Bindable to agents and team nodes
• Usable as a workflow action step

📖 Deep Dive Guide: For REST endpoint payload templating, auth headers, and workflow execution step integration, see the dedicated API Registry Reference ↗.

Channels connect an agent to the places your users already are. A channel registration binds a platform account to one or more agents; inbound messages arrive over a webhook and are answered by the tagged agent, and outbound actions are exposed to the agent as tools.

WhatsApp Meta Cloud API

• Provision a business number and webhook
• Approved message templates with variables
• send_whatsapp_message tool
• send_whatsapp_template tool

Outlook / Microsoft 365 OAuth

• Browser OAuth consent with a secured callback
• Token storage with automatic refresh
• send_outlook_message tool
• read_outlook_messages tool
• create_calendar_event tool
• Connection status & disconnect controls

Why it matters: Deployment stops being an engineering project. Tag an agent to a channel and it starts answering on that surface, with the same guardrails, analytics and rate limits as every other entry point. The available platforms are managed centrally in App Configuration.

📖 Deep Dive Guide: For WhatsApp Cloud API webhooks, Outlook Graph API mail polling, signature verification, and channel isolation, see the dedicated Channels & Messaging Guide ↗.

The Scheduler runs an agent or a team unattended — on a repeating cadence or once at a future instant. One schedule targets exactly one agent or one team, and carries the query, variables and session behaviour the run should use.

Recurrence

• Minutes (5–60), hours, days, weeks, months
• Time of day in a chosen IANA timezone
• Specific weekdays or day of month
• Last-day-of-month, with clamp or skip policy
• Daylight-saving shifts absorbed automatically
• Preview the next N run times before saving

Reliability

• Start / end window and max-run count
• Retries with backoff, plus a per-run timeout
• Misfire policy after downtime: fire once or skip
• Overlapping runs skip rather than pile up
• Safe across multiple app instances
• Pause, resume and Run now

Run history

• Status: running, success, failed, skipped, timeout
• Scheduled-for vs started-at (dispatcher drift)
• Duration, token usage and error detail
• Deep link into the trace log for the run
• Response preview per run
• Retention follows the analytics window

Why it matters: Daily digests, overnight batch scoring, recurring report generation and periodic data syncs stop being cron jobs someone has to maintain. Scheduled spend is tagged separately in Analytics, so automation cost is always visible on its own.

Guardrails enforce safety policies on the user's input and the agent's output. They run automatically at the boundaries of every agent and team interaction, and each guardrail declares its scope — input, output, or both.

Input security

• Prompt-injection detection, with optional model verification
• Custom injection patterns
• Blocked topics (keyword or semantic)
• PII detection — email, phone, SSN, card, IP, passport
• Language filtering by ISO code
• Maximum input length

Output filters

• Topic adherence with a fallback message
• PII redaction by type
• Toxicity detection with a severity threshold
• Format validation (text / markdown / JSON / XML)
• Required disclaimers appended verbatim
• Max output length with truncate option
• Low-confidence disclaimer on uncertainty
• Hallucination grounding checks

Content safety

• Severity thresholds for hate speech, harassment, sexual and dangerous content
• Profanity blocklist matched before any model call
• Blocked domains, exact and suffix

PII redaction and restoration: detected values are replaced with indexed placeholders such as [EMAIL_REDACTED_1] before the prompt reaches the model. The mapping is held per session, used to restore the original values in the reply to the user, and cleared as soon as the response is sent — so the model never sees the raw value, and the user never sees a mask.

Why it matters: Guardrails make agents enterprise-safe. They prevent data leaks, block prompt-injection attacks and keep responses within approved topics — all auditable through a violations log and configurable per agent or per team.

📖 Deep Dive Guide: For the global safety baseline, injection heuristics, regex and GLiNER PII masking/restoration, fail-closed safety, and violation audit records, see the dedicated Guardrails & Governance Manual ↗.

Providers are your model vendor connections (OpenAI, Anthropic, Google, Azure and others). Models are the specific configurations registered under a provider, including chat, embedding and vision models.

Why it matters: You can swap models per agent without changing anything else — a cheap model for simple Q&A, a powerful one for complex reasoning — or A/B test two models against the same agent configuration.

• Chat, embedding and vision model roles
• Per-model pricing for accurate cost reporting
• Credentials encrypted at rest
• Per-node model override inside teams

📖 Deep Dive Guide: For vendor connection setups (OpenAI, Claude, Gemini, Ollama, Azure), parameter overrides (temperature, top_p, max_tokens), per-million token pricing, live connection diagnostics, and credential encryption, see the dedicated Models & Providers Manual ↗.

Everything in Derbee Studio is governed by role-based access control. A role holds a list of permissions, each one a resource plus the actions allowed on it — create, read, update, delete, manage.

Roles

• System, generic and client-scoped roles
• Built-in roles that cannot be deleted
• Per-resource action matrix
• Applied uniformly across every module

Sharing

• Share an object with named users
• Share with entire roles
• Applies to templates, channels and more
• Creator and last-modifier tracked on every record

Keys

• Agent API keys — scoped to one agent or one team
• Prefix shown, full value stored encrypted
• Expiry date and last-used timestamp
• Revoke without deleting the audit trail
• Authorization keys for client connections
• Client Connect for bearer-token integrations

Why it matters: Agents can be exposed to your own applications and partners without ever handing out user credentials, and every invocation is attributed to the real end user rather than the key owner.

Track token usage, cost, latency and execution traces across every agent, workflow, team and scheduled run.

Every run records

• Trigger: user, API, channel or schedule
• Run kind: agent or team, plus team strategy
• The real end-user identity and email
• Status: success, error, blocked or stopped
• Which features fired — RAG, MCP, web, API, channel, cache
• Input / output tokens and resolved model cost
• Thumbs-up / thumbs-down feedback per turn
• Partial output when generation was stopped

Views

• Per-agent and per-team dashboards
• Workflow step-level traces
• Token and cost breakdowns, sortable
• Log viewer with level filtering
• Scheduled-run spend isolated from interactive
• Retention window set in App Configuration

Why it matters: Knowing what each agent costs per conversation, which workflow steps are slowest and where token budget goes lets teams optimise both performance and spend — essential before scaling to production.

📖 Deep Dive Guide: For the three layers of observability (structured database run records, step-by-step trace logs, process-wide application logs), execution detail, token cost tracking, secret redaction, and TTL retention policies, see the dedicated Analytics & Logs Manual ↗.

The Chat interface is how people interact with agents in real time. It supports conversational sessions with memory, file attachments and streamed responses.

• Token-by-token streaming
• Stop generation mid-stream
• Thumbs-up / thumbs-down feedback
• File attachments per message
• Session list, resume, end and delete
• Per-turn summaries for long conversations
• Semantic response cache, purged on negative feedback
• Configurable chat-history retention

Why it matters: Chat is the testing ground during development and the end-user interface in production. Every agent can be exercised directly in the studio and then deployed unchanged via API key, channel or schedule.

📖 Deep Dive Guide: For the full session state machine, multi-turn memory buffers, rolling turn summaries, semantic cache fingerprinting, streaming, stop requests, and human-in-the-loop approval gates, see the dedicated Chat, Sessions & Memory Manual ↗.

App Configuration holds the tenant-wide settings that used to live in config files. Operators can tune them in the UI without a redeploy.

• Data retention windows for chat history, analytics, checkpoints and cache — including a Lifetime option
• Global trace-logging toggle and level selection
• Per-user rate limits: invocations per minute, model calls per day
• Ceiling on tool-call iterations per run
• PDF vision image limit for knowledge-base ingestion
• Catalog of available channel platforms

Why it matters: Retention, cost ceilings and logging verbosity are compliance and budget decisions. Keeping them in one place, changeable by an administrator, means those decisions do not require an engineer.