Skip to main content

Tools and Permissions

Agent definitions control what tools an agent can use. You can grant access to built-in sandbox tools, credentialed integrations, and custom workflow tools. The model only sees the tools you explicitly provide.

Permission model​

Permissions are configured on the primary agent using the top-level permissions field. Each tool or operation is assigned a SandboxToolPermission value:

  • 'approve': The tool executes automatically.
  • 'ask': Suspends the agent run until a user approves or rejects the execution in the Console.
  • 'deny': Hides the tool from the model. Unlisted tools are also unavailable.
import { type AgentPermissions, type SandboxToolPermission } from '@culvii/kit';

const permissions: AgentPermissions = {
default: {
web_fetch: 'approve',
exec_process: 'ask',
},
integrations: [],
};

Built-in sandbox tools​

Grant built-in sandbox tools through permissions.default.

import { SANDBOX_TOOL_NAMES, type SandboxToolName } from '@culvii/kit';

permissions: {
default: {
'*': 'ask', // Wildcard fallback
read_file: 'approve', // Exact names override the wildcard
write_file: 'approve',
}
}

The 11 supported SANDBOX_TOOL_NAMES are:

  • list_files
  • read_file
  • search_text
  • write_file
  • apply_patch
  • move_file
  • delete_file
  • attach_output_file
  • exec_process
  • web_fetch
  • git

Binary staging rules​

Workflow binary inputs are staged read-only in the sandbox workspace under .culvii/inputs/workflow/<fileId>/<fileName>, and user message uploads under .culvii/inputs/uploads/<fileId>/<fileName>. Reading staged inputs requires list_files and read_file in permissions.default. Writing and attaching outputs back requires write_file and attach_output_file.

Note: The generic git argv fallback always requires approval even when git: 'approve'.

Credentialed integrations​

Grant access to external services through permissions.integrations. Each entry specifies the integration name, the credential ID to use, and a permission map for its operations.

permissions: {
integrations: [
{
name: 'github',
credentialId: 'my-github-credential',
permissions: {
'*': 'ask',
'issue': 'ask',
'issue.create': 'approve',
},
},
],
}
  • name: Must be an approved integration.
  • credentialId: The stored credential ID from the Console's Integrations tab.
  • permissions: Maps relative operation paths to 'approve' | 'ask' | 'deny'.

Permission rules work by matching the longest path:

  • '*': matches all resources and operations on that integration.
  • '<resource>': matches all operations under that resource (e.g., 'issue').
  • '<resource>.<operation>': matches one specific operation (e.g., 'issue.create').

Longest matching path wins: <resource>.<operation> → <resource> → *.

Each permitted operation is exposed to the model as <integration>_<resource>_<operation> (e.g. github_issue_create), with its JSON schema derived from that operation's properties on the connector node. These execute in the platform without exposing credentials to the sandbox. Additionally, a github integration automatically authenticates HTTPS github.com Git operations in the sandbox.

Supported integrations and permission keys​

IntegrationResource keys (<resource>)Operation keys (<resource>.<operation>)
argocd (ArgoCD)application, projectapplication.getApplication, application.syncApplication, application.listApplications, application.getResourceTree, project.listProjects
clickupDoc (ClickUp Doc)docdoc.create, doc.read
clickupTicket (ClickUp Ticket)ticketticket.create, ticket.update, ticket.updateStatus, ticket.updateDescription
github (GitHub)pullRequest, branch, issue, repo, org, gitBlob, gitTree, gitCommit, commitStatus, file, action, searchpullRequest.list, pullRequest.get, pullRequest.create, pullRequest.close, pullRequest.merge, pullRequest.listComments, pullRequest.createComment, pullRequest.createInlineComment, pullRequest.createReview, pullRequest.requestReviewers, branch.list, branch.get, branch.delete, issue.create, issue.list, issue.get, issue.update, issue.close, issue.addLabels, issue.createComment, repo.getContents, repo.create, org.list, gitBlob.create, gitBlob.get, gitTree.create, gitTree.get, gitCommit.create, commitStatus.create, commitStatus.list, commitStatus.getCombined, file.createOrUpdate, action.dispatch, search.issuesAndPRs
gmail (Gmail)messagemessage.send, message.readAll
googleCalendar (Google Calendar)eventevent.create, event.readAll
googleDocs (Google Docs)documentdocument.create, document.get, document.replaceText, document.appendText
grafanaDashboard (Grafana Dashboard)dashboarddashboard.createUpdate, dashboard.get, dashboard.list
grafanaDataSource (Grafana Data Source)datasourcedatasource.configure, datasource.healthCheck, datasource.list
grafanaQuery (Grafana Query)queryquery.queryDataSource
microsoftOutlook (Microsoft Outlook)messagemessage.send, message.readAll
prometheus (Prometheus)query, metadataquery.instantQuery, query.rangeQuery, metadata.getTargets, metadata.getAlerts
slack (Slack)message, reaction, user, channel, file, search, interactionmessage.send, message.sendByEmail, message.update, message.delete, message.getReplies, message.getPermalink, message.schedule, message.listScheduled, message.cancelScheduled, message.sendEphemeral, reaction.add, reaction.remove, user.getByEmail, user.getMany, user.getProfile, user.updateProfile, channel.getMany, channel.create, channel.archive, channel.setTopic, channel.invite, channel.remove, file.upload, file.getInfo, file.download, search.messages, search.files, interaction.respond
supabase (Supabase)database, storagedatabase.getRows, database.insertRow, database.updateRows, database.upsertRow, database.deleteRows, database.callFunction, storage.uploadFile, storage.downloadFile, storage.listFiles, storage.deleteFile

Note: Workflow-only connectors (s3, costExplorer, microsoftSharepoint, elasticsearch, twilio, kubernetes, hibp.listDomains, hibp.stealerLogs, onionsearch) are workflow-only connectors and cannot be passed in permissions.integrations. To use them, wrap them in a workflow with defineWorkflowTool() instead.

Permission boundaries​

Governed sandbox tools, integration tools, and workflow tools belong exclusively to the primary agent. This ensures durable continuation has a single model transcript. Secondary agents cannot configure permissions or tools; they receive tasks from the primary agent and return their analysis.

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',
});

workflowId has to match the target Workflow's own id field exactly. That's the only link between the two; there's no separate lookup or reference resolution, just a string match against the id you gave the Workflow you're wrapping.

triggerNodeName is the name of the manualTrigger step inside that workflow that the tool call starts from. Target workflows cannot contain any non-manual triggers. When the target workflow has a single manualTrigger step, triggerNodeName is optional and the platform selects that trigger automatically; when a workflow has multiple manualTrigger steps, triggerNodeName is required to disambiguate which entry point to run.

Attach the tool to the primary agent definition:

tools: {
runSupportWorkflow,
}

Write clear descriptions, since the model reads the description to decide when to use the tool. A workflow invoked as a tool by a root agent (agent → workflow → agent) can contain a core.agent step as long as that nested agent does not itself define workflow tools; a workflow invoked as a tool by a workflow-invoked agent (workflow → agent → workflow) cannot contain a core.agent step (maximum resource reference depth is 3).

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',
triggerNodeName: 'Manual Trigger',
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.

Durable workflow tool execution​

When the primary agent calls a workflow tool, the agent execution suspends durably, checkpoints its state and sandbox snapshot, and launches the target workflow execution. Once the child workflow completes — including after any human-in-the-loop (wait surface or pauseAfterExecution) pause — the platform resolves the tool wait with the workflow's output (or failure) and resumes the agent turn from its saved transcript.

Combining permissions and workflow tools​

An agent can hold built-in permissions, integrations, and workflow tools at the same time. This one can fetch web pages on its own, and can call runSupportWorkflow when it needs to:

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

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

const supportAgent = new MultiAgentEngine({
id: 'support-agent',
name: 'Support Agent',
role: 'primary',
systemPrompt: 'Answer customer questions. Escalate to the support workflow when a case needs human review.',
model: { provider: 'anthropic', modelId: 'claude-sonnet-4-5', credentialId: 'my-anthropic-credential' },
tools: {
runSupportWorkflow,
},
permissions: {
default: {
web_fetch: 'approve',
},
integrations: [
{
name: 'slack',
credentialId: 'my-slack-credential',
permissions: {
'*': 'ask',
'message.send': 'approve',
},
},
],
},
secondaryAgents: [],
});