Skills & Sub-Agents

The Rossum Agent includes a skills system and Opus-powered sub-agents for domain-specific workflows and complex iterative tasks.

Skills

Skills are markdown files that provide domain-specific instructions and workflows to the agent. They are loaded on-demand via the load_skill tool and injected into the agent’s context.

Loading Skills

Use the load_skill tool when a task matches one of the available skills:

{
  "name": "rossum-deployment"
}

Returns skill instructions as JSON:

{
  "status": "success",
  "skill_name": "Rossum Deployment",
  "instructions": "# Rossum Deployment Skill\n\n**Goal**: Deploy configuration changes safely..."
}

Available Skills

Skill	Purpose
`rossum-deployment`	Deploy configuration changes safely via sandbox with before/after diff
`hook-debugging`	Identify and fix hook issues using knowledge base and Opus sub-agent
`schema-patching`	Add, update, or remove individual schema fields
`schema-pruning`	Remove unwanted fields from schema in one call
`organization-setup`	Set up Rossum for new customers with correct document types and regional configurations
`ui-settings`	Update queue UI settings (annotation list columns) without corrupting structure

Rossum Deployment Skill

Goal: Deploy configuration changes safely via sandbox with before/after diff.

Key workflow:

Copy workspace to sandbox (deploy_copy_workspace)
Pull BEFORE state (deploy_pull)
Modify sandbox via spawned connection (call_on_connection)
Pull AFTER state (deploy_pull)
Compare and show diff (deploy_compare_workspaces) - wait for user approval
Deploy to production (deploy_to_org)

Critical rule: Direct MCP calls modify production. Use call_on_connection("sandbox", ...) for sandbox modifications.

Hook Debugging Skill

Goal: Identify and fix hook issues.

Tools:

search_knowledge_base - Use first to find Rossum docs, extension configs, known issues
debug_hook(hook_id, annotation_id) - Spawns Opus sub-agent for code analysis, returns verified fix

Schema Patching Skill

Goal: Add, update, or remove individual schema fields.

patch_schema_with_subagent(
    schema_id="12345",
    changes='[{"action": "add", "id": "invoice_number", "parent_section": "header_section", "type": "string", "label": "Invoice Number"}]'
)

Schema Pruning Skill

Goal: Remove unwanted fields from schema in one call.

prune_schema_fields(
    schema_id=12345,
    fields_to_keep=["invoice_number", "invoice_date", "total_amount"]
)

Organization Setup Skill

Goal: Set up Rossum for new customers with correct document types and regional configurations.

Use create_queue_from_template for new customer onboarding with regional templates (EU/US/UK/CZ/CN).

UI Settings Skill

Goal: Update queue UI settings (settings.annotation_list_table.columns) without corrupting structure.

Workflow: Fetch current settings → Modify only columns array → Patch via update_queue.

Dynamic Tool Loading

The agent uses dynamic tool loading to reduce initial context usage from ~8K to ~800 tokens. Instead of loading all MCP tools at startup, tools are loaded on-demand based on task requirements.

How It Works

Discovery: The MCP server provides a list_tool_categories tool that returns all available categories with metadata
Automatic Pre-loading: On the first user message, keywords are matched against category keywords to pre-load relevant tools
On-demand Loading: The agent can explicitly load additional categories using load_tool_category

Loading Tools

Use load_tool_category to load MCP tools from specific categories:

# Load single category
load_tool_category(categories=["schemas"])

# Load multiple categories
load_tool_category(categories=["queues", "schemas", "engines"])

Available Categories

Category	Description	Keywords (for auto-loading)
`annotations`	Document processing: upload, retrieve, update, confirm	annotation, document, upload, extract, confirm, review
`queues`	Queue management: create, configure, list	queue, inbox, connector
`schemas`	Schema management: define, modify field structures	schema, field, datapoint, section, multivalue, tuple
`engines`	AI engine management: extraction/splitting engines	engine, ai, extractor, splitter, training
`hooks`	Extensions/webhooks: automation hooks	hook, extension, webhook, automation, function, serverless
`email_templates`	Email templates: automated email responses	email, template, notification, rejection
`document_relations`	Document relations: export/einvoice links	document relation, export, einvoice
`relations`	Annotation relations: edit/attachment/duplicate links	relation, duplicate, attachment, edit
`rules`	Validation rules: schema validation	rule, validation, constraint
`users`	User management: list users and roles	user, role, permission, token_owner
`workspaces`	Workspace management: organize queues	workspace, organization

Automatic Pre-loading

When the user sends their first message, the agent scans for keywords and automatically loads matching categories. For example:

User says “update the schema” → schemas category is pre-loaded
User says “create a new hook” → hooks category is pre-loaded
User says “list all queues” → queues category is pre-loaded

This ensures relevant tools are available without requiring explicit loading while keeping context usage minimal.

Sub-Agents

Sub-agents are Opus-powered components that handle complex iterative tasks requiring deep reasoning and tool use loops.

Hook Debug Sub-Agent

Invoked via the debug_hook tool. Provides iterative hook debugging with sandboxed code execution.

Capabilities:

Fetches hook code and annotation data via MCP tools
Executes code in sandboxed environment with restricted builtins
Iteratively analyzes errors and fixes issues
Searches Rossum Knowledge Base for documentation
Returns verified, working code

Available in sandbox:

Modules: collections, datetime, decimal, functools, itertools, json, math, re, string
Safe builtins: abs, all, any, bool, dict, enumerate, filter, float, int, len, list, map, max, min, range, set, sorted, str, sum, tuple, zip, and common exceptions

Usage:

debug_hook(hook_id="12345", annotation_id="67890")

Returns JSON with:

Hook ID and annotation ID
Detailed analysis including: - What the hook does - All issues found - Root causes - Fixed, verified code - Successful execution result

Knowledge Base Sub-Agent

Invoked via the search_knowledge_base tool. Searches Rossum documentation and analyzes results with Opus.

Capabilities:

Searches knowledge-base.rossum.ai for documentation
Fetches full page content via Jina Reader
Analyzes results with Opus to extract relevant information
Provides synthesized, actionable responses

Usage:

search_knowledge_base(
    query="document splitting extension",
    user_query="How do I configure document splitting for invoice processing?"
)

Returns JSON with:

Search status
Query used
Analyzed results from Opus
Source URLs

Schema Patching Sub-Agent

Invoked via the patch_schema_with_subagent tool. Handles bulk schema modifications programmatically.

Workflow:

Fetches schema tree structure (lightweight view)
Fetches full schema content
Opus analyzes current vs requested fields
Programmatically filters to keep required fields and adds new ones
Single PUT to update schema

Usage:

patch_schema_with_subagent(
    schema_id="12345",
    changes='[{"action": "add", "id": "po_number", "parent_section": "basic_info_section", "type": "string", "label": "PO Number"}]'
)

Field specification:

Property	Required	Notes
`id`	Yes	Unique field identifier
`label`	Yes	Display name
`parent_section`	Yes	Section ID to add field to
`type`	Yes	`string`, `number`, `date`, `enum`
`table_id`	If table	Multivalue ID for table columns
`multiline`	No	`true` for multiline string fields
`options`	For enum	Array of enum options

Sub-Agent Architecture

All sub-agents share common patterns:

Model: Claude Opus 4.5 via AWS Bedrock
Iteration limit: 5-10 iterations depending on task complexity
Tool access: MCP tools via helper functions
Progress reporting: Real-time progress updates via callback system
Token tracking: Input/output token usage reported per iteration

Sub-agents are designed to be autonomous—they fetch required data, iterate on solutions, and return verified results without requiring user intervention during execution.