@lowdefy/docs-content 0.0.0-experimental-20260710073520

package/content/agents/agent-endpoint-tools.md

@@ -0,0 +1,190 @@
+# Endpoint Tools
+
+Endpoint tools connect your agent to your app's [API endpoints](/lowdefy-api). The model can call these tools during a conversation to query databases, call external APIs, create records, or any other server-side operation your endpoints support.
+
+If you are not familiar with the Lowdefy API system, see the [APIs](/lowdefy-api) concept page first.
+
+## Defining a Tool Endpoint
+
+Any endpoint defined in the `api` section can be used as a tool, as long as it has a `description` and a `payloadSchema`. The description tells the model what the tool does, and the payload schema defines the input format.
+
+> Well-written `description` and `payloadSchema.properties.*.description` fields are critical — they are all the model has to decide when to call the tool and what arguments to pass.
+
+###### Search endpoint:
+```yaml
+api:
+  - id: search-articles
+    type: Api
+    description: >
+      Search knowledge base articles by topic. Returns matching
+      articles with title, summary, and content.
+    payloadSchema:
+      type: object
+      properties:
+        query:
+          type: string
+          description: Search term — can be a topic, keyword, or question.
+        limit:
+          type: integer
+          description: Maximum number of articles to return.
+          default: 5
+      required:
+        - query
+    routine:
+      - id: search
+        type: MongoDBFind
+        connectionId: kb_db
+        properties:
+          collection: articles
+          query:
+            $text:
+              $search:
+                _payload: query
+          options:
+            projection:
+              title: 1
+              summary: 1
+              content: 1
+              score:
+                $meta: textScore
+            sort:
+              score:
+                $meta: textScore
+            limit:
+              _payload: limit
+      - :return:
+          _step: search
+```
+
+###### Create endpoint:
+```yaml
+api:
+  - id: create-support-ticket
+    type: Api
+    description: >
+      Create a support ticket for issues that need human follow-up.
+      Returns the ticket number.
+    payloadSchema:
+      type: object
+      properties:
+        subject:
+          type: string
+          description: Short summary of the issue.
+        description:
+          type: string
+          description: Detailed description of the problem.
+        priority:
+          type: string
+          enum:
+            - low
+            - medium
+            - high
+          description: Ticket priority level.
+      required:
+        - subject
+        - description
+    routine:
+      - id: insert
+        type: MongoDBInsertOne
+        connectionId: tickets_db
+        properties:
+          doc:
+            subject:
+              _payload: subject
+            description:
+              _payload: description
+            priority:
+              _payload: priority
+            status: open
+            createdAt:
+              _date: now
+            userId:
+              _user: id
+      - :return:
+          ticketId:
+            _step: insert.insertedId
+```
+
+###### HTTP API call:
+```yaml
+api:
+  - id: get-weather
+    type: Api
+    description: >
+      Get current weather for a city. Returns temperature,
+      conditions, and forecast.
+    payloadSchema:
+      type: object
+      properties:
+        city:
+          type: string
+          description: City name (e.g. "London", "New York").
+      required:
+        - city
+    routine:
+      - id: fetch
+        type: AxiosHttp
+        connectionId: weather_api
+        properties:
+          url:
+            _string.concat:
+              - /current?city=
+              - _payload: city
+      - :return:
+          _step: fetch.data
+```
+
+## Referencing Tools in an Agent
+
+Reference tools in the agent's `tools` array using a string shorthand or an object:
+
+- `tools: array`: Each item is either:
+  - `string` — The endpoint `id`.
+  - `object`:
+    - `endpointId: string`: __Required__ - The endpoint `id`.
+    - `confirm: boolean`: When `true`, the user must approve the call before it executes.
+
+```yaml
+agents:
+  - id: support_agent
+    type: ClaudeAgent
+    connectionId: anthropic
+    properties:
+      model: claude-sonnet-4-20250514
+      instructions: |
+        You are a support agent. Search the knowledge base before
+        answering. If you can't resolve the issue, create a ticket.
+    tools:
+      # String shorthand
+      - search-articles
+      # Object form with confirmation
+      - endpointId: create-support-ticket
+        confirm: true
+```
+
+## Reserved Tool Names
+
+Lowdefy registers a small set of platform tools automatically (for example, `update-page-state`, which the [`AgentChat`](/AgentChat#shared-state) block wires up when `sharedState` is set). The following tool names are reserved and cannot be used as endpoint ids or sub-agent ids — the build will fail if one is encountered:
+
+- `update-page-state`
+- `read-file`
+- `list-files`
+- `search-files`
+- `stat-file`
+
+## Tool Confirmation
+
+Setting `confirm: true` pauses the agent loop and shows approve/reject buttons in the [`AgentChat`](/AgentChat) block. The agent waits until the user responds before continuing.
+
+Use confirmation for destructive or sensitive operations — deleting records, sending emails, making payments, etc.
+
+```yaml
+tools:
+  - search-articles
+  - endpointId: create-support-ticket
+    confirm: true
+  - endpointId: send-email
+    confirm: true
+  - endpointId: delete-record
+    confirm: true
+```

package/content/agents/agent-mcp-tools.md

@@ -0,0 +1,124 @@
+# MCP Tools
+
+[Model Context Protocol (MCP)](https://modelcontextprotocol.io/) is an open standard for connecting AI models to external tools and data sources. Lowdefy agents can connect to any MCP server, giving the agent access to all the tools that server provides.
+
+MCP tools can be configured by referencing an [`Mcp` connection](/Mcp) or by defining the server inline on the agent.
+
+## Using an Mcp Connection
+
+Define an [`Mcp` connection](/Mcp), then reference it in the agent's `mcp` array:
+
+```yaml
+connections:
+  - id: mcp_github
+    type: Mcp
+    properties:
+      transport: stdio
+      command: npx
+      args:
+        - '-y'
+        - '@modelcontextprotocol/server-github'
+      env:
+        GITHUB_TOKEN:
+          _secret: GITHUB_TOKEN
+
+agents:
+  - id: dev_assistant
+    type: ClaudeAgent
+    connectionId: anthropic
+    properties:
+      model: claude-sonnet-4-20250514
+      instructions: You help developers manage GitHub issues and PRs.
+    mcp:
+      # String shorthand — just the connection id
+      - mcp_github
+      # Object form (equivalent)
+      - connectionId: mcp_github
+```
+
+The agent automatically discovers all tools the MCP server provides.
+
+## Inline MCP Configuration
+
+Define MCP servers directly on the agent without creating a separate connection:
+
+###### Remote HTTP server:
+```yaml
+mcp:
+  - url: https://mcp.example.com/tools
+    transport: http
+    headers:
+      Authorization:
+        _string.concat:
+          - 'Bearer '
+          - _secret: MCP_API_KEY
+```
+
+###### Local stdio server:
+```yaml
+mcp:
+  - command: node
+    args:
+      - ./mcp-server/index.js
+    transport: stdio
+    env:
+      DATABASE_URL:
+        _secret: DATABASE_URL
+```
+
+###### Multiple servers on one agent:
+```yaml
+agents:
+  - id: assistant
+    type: ClaudeAgent
+    connectionId: anthropic
+    properties:
+      model: claude-sonnet-4-20250514
+    mcp:
+      - mcp_github
+      - url: https://mcp.example.com/tools
+        transport: http
+      - command: npx
+        args:
+          - '-y'
+          - '@modelcontextprotocol/server-filesystem'
+          - '/data/documents'
+        transport: stdio
+```
+
+## MCP Properties
+
+- `mcp: array`: Each item is either:
+  - `string` — The [`Mcp` connection](/Mcp) `id`.
+  - `object`:
+    - `connectionId: string`: Reference an [`Mcp` connection](/Mcp) by `id`.
+    - `url: string`: URL for HTTP or SSE transport.
+    - `transport: string`: Default: `'http'` - `'http'`, `'sse'`, or `'stdio'`.
+    - `headers: object`: HTTP headers (for `http`/`sse`). __Operators are evaluated__.
+    - `command: string`: Command to run (for `stdio`).
+    - `args: string[]`: Command arguments (for `stdio`).
+    - `env: object`: Environment variables (for `stdio`). __Operators are evaluated__.
+    - `confirm: boolean`: Require user approval for all tools from this server.
+
+## Transports
+
+| Transport | Use case | Required properties |
+| --- | --- | --- |
+| `http` (default) | Remote MCP servers | `url` |
+| `sse` | Servers using Server-Sent Events | `url` |
+| `stdio` | Local processes, npm packages | `command` |
+
+For HTTP and SSE transports, use `headers` to pass authentication. For stdio, use `command`, `args`, and `env` to configure the process.
+
+See the [`Mcp` connection](/Mcp) page for more details on configuring MCP servers as reusable connections.
+
+## Tool Confirmation
+
+Setting `confirm: true` on an MCP source requires user approval for **all** tools from that server:
+
+```yaml
+mcp:
+  - url: https://mcp.example.com/admin-tools
+    transport: http
+    confirm: true
+```

package/content/agents/agent-multi-agent.md

@@ -0,0 +1,136 @@
+# Multi-Agent
+
+An agent can delegate tasks to other agents defined in your app. Sub-agents are presented to the parent agent as tools — the parent sends a task description, the sub-agent processes it using its own instructions and tools, and returns a text response.
+
+This lets you build systems where a general-purpose agent routes requests to specialized agents, each with their own instructions, tools, and model settings.
+
+## Defining Sub-Agents
+
+Define the sub-agent as a regular agent, then reference it in the parent agent's `agents` array:
+
+```yaml
+agents:
+  - id: researcher
+    type: ClaudeAgent
+    connectionId: anthropic
+    properties:
+      model: claude-sonnet-4-20250514
+      instructions: You research and summarize information about products.
+    tools:
+      - search-products
+      - get-product-details
+
+  - id: assistant
+    type: ClaudeAgent
+    connectionId: anthropic
+    properties:
+      model: claude-sonnet-4-20250514
+      instructions: |
+        You are a helpful assistant. When users ask about products,
+        delegate the research to the researcher agent.
+    agents:
+      - agentId: researcher
+        description: Research and summarize product information.
+```
+
+The `description` tells the parent model when to delegate. Write it clearly — it's the only thing the parent sees about the sub-agent's capabilities.
+
+## Sub-Agent Options
+
+- `agents: array`: Each item is either:
+  - `string` — The sub-agent `id`. Uses the sub-agent's instructions as the tool description.
+  - `object`:
+    - `agentId: string`: __Required__ - The sub-agent `id`.
+    - `description: string`: Description sent to the parent model.
+    - `inputSchema: object`: JSON Schema for structured input. When provided, the parent generates structured input matching this schema instead of freeform text.
+
+###### String shorthand:
+```yaml
+agents:
+  - researcher
+```
+
+###### With structured input:
+```yaml
+agents:
+  - agentId: report_generator
+    description: Generate formatted reports from data.
+    inputSchema:
+      type: object
+      properties:
+        reportType:
+          type: string
+          enum:
+            - summary
+            - detailed
+            - executive
+          description: The type of report to generate.
+        dateRange:
+          type: string
+          description: Date range for the report (e.g. "last 30 days").
+        metrics:
+          type: array
+          items:
+            type: string
+          description: Metrics to include in the report.
+      required:
+        - reportType
+```
+
+## Routing Pattern
+
+A common pattern is a router agent that delegates to specialized agents based on the user's intent:
+
+```yaml
+agents:
+  - id: billing_agent
+    type: ClaudeAgent
+    connectionId: anthropic
+    properties:
+      model: claude-sonnet-4-20250514
+      instructions: |
+        You handle billing questions. Look up invoices, explain
+        charges, and process refund requests.
+    tools:
+      - get-invoices
+      - get-payment-history
+      - endpointId: process-refund
+        confirm: true
+
+  - id: technical_agent
+    type: ClaudeAgent
+    connectionId: anthropic
+    properties:
+      model: claude-sonnet-4-20250514
+      instructions: |
+        You handle technical support. Diagnose issues, search
+        the knowledge base, and escalate if needed.
+    tools:
+      - search-articles
+      - check-service-status
+
+  - id: router
+    type: ClaudeAgent
+    connectionId: anthropic
+    properties:
+      model: claude-sonnet-4-20250514
+      instructions: |
+        You are the main support agent. Route billing questions
+        to the billing agent and technical issues to the
+        technical agent. Handle general questions yourself.
+    agents:
+      - agentId: billing_agent
+        description: Handles billing, invoices, payments, and refund requests.
+      - agentId: technical_agent
+        description: Handles technical issues, troubleshooting, and bug reports.
+```
+
+The user chats with the `router` agent via [`AgentChat`](/AgentChat). When the router delegates, the sub-agent runs server-side and returns its response to the router, which can then relay or build on it.
+
+## Nesting and Limits
+
+Sub-agents can themselves have sub-agents, up to **5 levels deep**. Circular references (agent A delegates to agent B, which delegates back to agent A) are detected at build time and cause a build error.
+
+Sub-agents can use any combination of [endpoint tools](/agent-endpoint-tools), [MCP tools](/agent-mcp-tools), and [file system access](/agent-properties) — they are full agents with their own configuration.
+
+> Tools with `confirm: true` are not supported on sub-agents, since sub-agents run server-side without direct user interaction. A build warning is shown if this is configured.

package/content/agents/agent-properties.md

@@ -0,0 +1,174 @@
+# Agent Properties
+
+Agent properties configure the model and its behavior. They are set in the `properties` object of the [agent definition](/agents-introduction). All properties support [operators](/operators), so you can use [`_secret`](/_secret), [`_user`](/_user), and other operators to set values dynamically.
+
+## Model and Instructions
+
+- `model: string`: __Required__ - The model identifier (e.g. `claude-sonnet-4-20250514`, `gpt-4o`, `gemini-2.5-pro`).
+- `instructions: string`: System instructions that guide the agent's behavior. This is the system prompt sent to the model with every request. The string passes through the operator parser at request time, so `_t:` works for locale-aware prompts (see [i18n](/i18n)). Note: tool descriptions stay English — translating them can degrade tool-call accuracy on English-trained models.
+- `pageContext: boolean`: Default: `false` - When `true`, prepend context about the current page, user, conversation, URL query, and shared state to the instructions. URL query and shared state are only included when the [`AgentChat`](/AgentChat) block sends them as `urlQuery` and `sharedState`. Useful when the agent needs to know who it's talking to or what the user has typed into form fields.
+- `generateTitle: boolean`: Default: `false` - When `true`, generate a short title from the first user message on the first turn of a conversation. Emits a `data-chat-title` data part that fires the [`AgentChat`](/AgentChat) block's `onTitleGenerated` event. Runs concurrently with the response and is non-fatal — a failed title generation logs a warning and does not break the turn.
+
+###### Instructions with user context:
+```yaml
+properties:
+  model: claude-sonnet-4-20250514
+  pageContext: true
+  instructions: |
+    You are a support agent for Acme Corp. You have access to the
+    current user's details via the page context. Use their name
+    when greeting them and tailor responses to their account.
+```
+
+## Generation Settings
+
+- `maxOutputTokens: integer`: Maximum tokens the model can generate per step.
+- `temperature: number`: Sampling temperature between `0` and `2`. Lower values are more deterministic, higher values more creative. Default depends on the provider.
+- `topP: number`: Nucleus sampling probability between `0` and `1`. Alternative to temperature — use one or the other.
+- `topK: integer`: Only sample from the top K token options (not supported by all providers).
+- `frequencyPenalty: number`: Penalty between `-1` and `1` for repeating tokens. `0` means no penalty.
+- `presencePenalty: number`: Penalty between `-1` and `1` for using tokens that have appeared. `0` means no penalty.
+- `seed: integer`: Seed for deterministic sampling (provider support varies).
+- `stopSequences: string[]`: Stop sequences. Generation stops when any sequence is produced.
+
+## Tool Loop Control
+
+- `maxSteps: integer`: Default: `10` - Maximum number of tool loop iterations. Each step is one model call plus any tool executions. Set lower to limit cost, higher for complex multi-step tasks.
+- `toolChoice`: Default: `'auto'` - Controls how the model uses tools:
+  - `'auto'` — The model decides whether to use a tool.
+  - `'required'` — The model must use a tool.
+  - `'none'` — The model cannot use tools.
+  - `{ type: 'tool', toolName: 'name' }` — Force a specific tool.
+- `activeTools: string[]`: Restrict which tools are available to the model. Only tools in this list are offered.
+- `stopOnToolCall: string | string[]`: Stop the tool loop when a specific tool is called. The tool result goes to the client, not back to the model. Useful for tools that return structured data to the UI.
+- `repairToolCall: boolean`: Default: `false` - When `true`, invalid tool inputs are sent back to the model for self-correction instead of failing.
+
+###### Return structured data to the UI:
+```yaml
+properties:
+  model: claude-sonnet-4-20250514
+  stopOnToolCall: get-product-recommendations
+  instructions: |
+    When the user asks for recommendations, call the
+    get-product-recommendations tool. The results will
+    be displayed as a product grid in the UI.
+```
+
+## Context Pruning
+
+Long conversations can exceed a model's context window. The `prune` property strips older messages to reduce context size while keeping recent messages intact.
+
+- `prune: object`:
+  - `reasoning: string`: How to handle reasoning/thinking content from the model:
+    - `'all'` — Remove all reasoning content.
+    - `'before-last-message'` — Keep only the last message's reasoning.
+    - `'none'` — Keep all reasoning.
+  - `toolCalls: string | array`: How to handle tool call and result content.
+    - As a string: `'all'`, `'before-last-message'`, `'before-last-N-messages'`, or `'none'`.
+    - As an array of per-tool rules. Each rule: `{ type: string, tools?: string[] }`. Rules without `tools` apply to all unmatched tools.
+  - `emptyMessages: string`: Default: `'keep'` - Whether to `'keep'` or `'remove'` messages that become empty after pruning.
+
+###### Strip all old reasoning and tool results:
+```yaml
+properties:
+  model: claude-sonnet-4-20250514
+  prune:
+    reasoning: before-last-message
+    toolCalls: all
+    emptyMessages: remove
+```
+
+###### Keep search results but prune other tool calls:
+```yaml
+properties:
+  model: claude-sonnet-4-20250514
+  prune:
+    toolCalls:
+      - type: before-last-message
+        tools:
+          - search-products
+      - type: all
+    emptyMessages: remove
+```
+
+## Per-Step Configuration
+
+The `prepareStep` property overrides agent settings for specific steps in the tool loop. Each rule specifies which steps it applies to and what to override. The first matching rule wins.
+
+- `prepareStep: array`: Array of step rules. Each rule:
+  - `steps: integer[]`: Specific step numbers this rule applies to.
+  - `from: integer`: Start of step range (inclusive).
+  - `to: integer`: End of step range (inclusive). Omit for open-ended.
+  - `activeTools: string[]`: Override available tools.
+  - `toolChoice`: Override tool choice.
+  - `maxOutputTokens: integer`: Override max output tokens.
+  - `temperature: number`: Override temperature.
+
+Use either `steps` for specific steps or `from`/`to` for ranges — not both on the same rule.
+
+###### Force an initial search, then let the model decide:
+```yaml
+properties:
+  model: claude-sonnet-4-20250514
+  prepareStep:
+    - steps: [1]
+      toolChoice: required
+      activeTools:
+        - search-knowledge-base
+    - from: 2
+      toolChoice: auto
+```
+
+###### Structured first step, creative follow-up:
+```yaml
+properties:
+  model: claude-sonnet-4-20250514
+  temperature: 0.7
+  prepareStep:
+    - steps: [1]
+      toolChoice: required
+      temperature: 0
+      activeTools:
+        - classify-intent
+    - from: 2
+      toolChoice: auto
+```
+
+## File System Access
+
+The `fileSystem` property gives the agent scoped, read-only file access. This automatically adds four tools: `read-file`, `list-files`, `search-files`, and `stat-file`. The agent cannot read files outside the specified directory.
+
+- `fileSystem: object`:
+  - `basePath: string`: __Required__ - Directory to expose. Relative paths are resolved from the app root.
+
+###### Documentation assistant with file access:
+```yaml
+properties:
+  model: claude-sonnet-4-20250514
+  fileSystem:
+    basePath: ./docs
+  instructions: |
+    You are a documentation assistant. Use the file system tools
+    to search and read documentation files, then answer the
+    user's question based on what you find.
+```
+
+## Timeouts and Retries
+
+- `maxRetries: integer`: Default: `2` - Maximum retries on provider errors. Set to `0` to disable.
+- `timeout: number | object`: Timeout configuration.
+  - As a number: total timeout in milliseconds.
+  - As an object with granular control:
+    - `totalMs: number`: Total timeout across all steps.
+    - `stepMs: number`: Timeout per step.
+    - `chunkMs: number`: Timeout between stream chunks.
+
+## Provider-Specific Properties
+
+- `providerOptions: object`: Pass provider-specific options directly to the AI SDK. Use this for options not covered by the properties above.
+
+Each agent type also has its own properties. See the connection pages for details:
+
+- [Anthropic](/Anthropic) — `ClaudeAgent` with `thinking` and `effort`
+- [OpenAI](/OpenAI-connection) — `OpenAIAgent` with `reasoningEffort` and `reasoningSummary`
+- [Google](/Google) — `GeminiAgent` with `thinkingConfig` and `safetySettings`