Tools and Permissions

Agent definitions control what tools an agent can use. You can grant access to built-in tools or define custom workflow tools.

The model only sees the tools you explicitly provide.

Built-in permissions

Grant built-in permissions through metadata.runtimeDetails.permissions.

metadata: {
  runtimeDetails: {
    permissions: {
      'workflow:pdf:read': true,
      'workflow:docx:read': true,
      'web:fetch': true,
    },
  },
}

Permission map

Permission	Tool names
*	All built-in tools
web:fetch	webFetch
web:crawl	webCrawl
workflow:binary:read	listWorkflowBinaryFiles, readWorkflowBinaryFile
workflow:binary:write	createWorkflowBinaryOutput
workflow:pdf:read	extractPdfText
workflow:docx:read	extractDocxText, extractDocxTables
workflow:docx:write	replaceDocxText, updateDocxTableCells
workflow:docx:append	appendDocxText

Start narrow. Avoid * unless the agent runs in a tightly controlled environment.

The supported keys are a closed contract. TypeScript rejects unknown keys, and Kit, dev sync, deploy, and the platform API validate them at runtime.

Import the public catalog when you need to render the available choices in your own UI or CLI:

import { BUILTIN_AGENT_PERMISSIONS, type AgentPermissions } from '@culvii/kit';

const availablePermissions = Object.entries(BUILTIN_AGENT_PERMISSIONS);
const permissions: AgentPermissions = { 'workflow:pdf:read': true };

Each catalog entry contains its label, description, and granted tool names. Shell execution is deliberately unavailable to agents.

Permissions prefixed with workflow: depend on the current workflow execution's binary context. Grant them only to agents that run as workflow steps; they are not general filesystem or standalone document permissions.

Permission boundaries

Permissions are scoped to the agent. A primary agent cannot use a tool granted only to a secondary agent, and vice versa.

If the primary agent needs to read workflow files, it must delegate to a secondary agent that has the workflow:binary:read permission, or you must grant that permission to the primary agent directly.

Workflow tools

Use defineWorkflowTool() to connect an agent to a workflow.

import { defineWorkflowTool } from '@culvii/kit';

const runSupportWorkflow = defineWorkflowTool({
  name: 'runSupportWorkflow',
  description: 'Run the approved support workflow for a customer request.',
  workflowId: 'workflow-id',
  triggerNodeName: 'Manual Trigger',
});

Attach the tool to an agent definition.

tools: {
  runSupportWorkflow,
}

Write clear descriptions. The model reads the description to decide when to use the tool.

Input schema

Add an inputSchema when the workflow expects structured data. Keep schemas small so the model can easily fill them.

const runSupportWorkflow = defineWorkflowTool({
  name: 'runSupportWorkflow',
  description: 'Run the approved support workflow for a customer request.',
  workflowId: 'workflow-id',
  inputSchema: {
    type: 'object',
    required: ['customerId', 'priority'],
    properties: {
      customerId: {
        type: 'string',
        description: 'The customer id from the request.',
      },
      priority: {
        type: 'string',
        enum: ['low', 'normal', 'high'],
      },
    },
    additionalProperties: false,
  },
});

Use serializable workflow tool declarations for shared agent definitions. This allows the definitions to cross process and service boundaries.

Tool call timeout

A workflow tool call has 5 minutes to resolve. If the workflow it runs doesn't complete in that time, the platform treats the call as failed and the agent gets an error result rather than waiting indefinitely.

This matters most for workflows that pause on a human-in-the-loop step. If a runSupportWorkflow-style tool triggers a workflow that waits on approval, make sure that approval can realistically happen within 5 minutes, or design the workflow to resolve the tool call immediately and handle the wait asynchronously (e.g. notify back via a separate channel) instead of blocking on it.