rossum-agent 1.1.3

AI agent toolkit for Rossum: document workflows conversationally, debug pipelines automatically, and enable agentic configuration of intelligent document processing.

Rossum Agent

AI agent for Rossum document processing. Debug hooks, deploy configs, and automate workflows conversationally.

[!NOTE] This is not an official Rossum project. It is a community-developed integration built on top of the Rossum API, not a product (yet).

Features

Capability	Description
Rossum MCP Integration	Full access to 63 MCP tools for document processing
Hook Debugging	Sandboxed execution with Opus sub-agent analysis
Deployment Tools	Pull, push, diff, copy configs across environments
Knowledge Base Search	AI-powered Rossum documentation search
Multi-Environment	Spawn connections to different Rossum environments
Skills System	Load domain-specific workflows on demand
Prompt Caching	Automatic cache_control on system prompt, tools, and conversation history for up to 90% input token cost reduction

Interfaces: REST API, Python SDK

Quick Start

# Set environment variables
export ROSSUM_API_TOKEN="your-api-token"
export ROSSUM_API_BASE_URL="https://api.elis.rossum.ai/v1"
export AWS_PROFILE="default"  # For Bedrock

# Run the agent API
uv pip install rossum-agent[api]
rossum-agent-api

Installation

git clone https://github.com/stancld/rossum-agents.git
cd rossum-agents/rossum-agent
uv sync

With extras:

uv sync --extra all        # All extras (api, docs, tests)
uv sync --extra api        # REST API (FastAPI, Redis)

Environment Variables

Variable	Required	Description
ROSSUM_API_TOKEN	Yes	Rossum API authentication token
ROSSUM_API_BASE_URL	Yes	Base URL (e.g., https://api.elis.rossum.ai/v1)
AWS_PROFILE	Yes	AWS profile for Bedrock access
AWS_DEFAULT_REGION	No	AWS region (default: us-east-1)
REDIS_HOST	No	Redis host for chat persistence
REDIS_PORT	No	Redis port (default: 6379)
ROSSUM_MCP_MODE	No	MCP mode: read-only (default) or read-write

Usage

REST API

# Development (uvicorn)
rossum-agent-api --host 0.0.0.0 --port 8000 --reload

# Production (gunicorn)
rossum-agent-api --server gunicorn --host 0.0.0.0 --port 8000 --workers 4

Option	Server	Description
--server	both	Backend: uvicorn (default) or gunicorn
--host	both	Host to bind to (default: 127.0.0.1)
--port	both	Port to listen on (default: 8000)
--workers	both	Number of worker processes (default: 1)
--reload	uvicorn	Enable auto-reload for development

Python SDK

import asyncio
from rossum_agent.agent import create_agent
from rossum_agent.rossum_mcp_integration import create_mcp_connection

async def main():
    mcp_connection = await create_mcp_connection()
    agent = await create_agent(mcp_connection=mcp_connection)

    async for step in agent.run("List all queues"):
        if step.final_answer:
            print(step.final_answer)

asyncio.run(main())

Available Tools

The agent provides internal tools and access to 66 MCP tools via dynamic loading.

Internal Tools

File & Knowledge:

• write_file - Save reports, documentation, analysis results
• search_knowledge_base - Search Rossum docs with AI analysis (sub-agent)
• kb_grep - Regex search across Knowledge Base article titles and content
• kb_get_article - Retrieve full Knowledge Base article by slug

API Reference:

• elis_openapi_jq - Query Rossum API OpenAPI spec with jq
• elis_openapi_grep - Free-text search in API spec
• search_elis_docs - AI-powered search of API documentation

Formula:

• suggest_formula_field - Suggest formula field expressions via Rossum Local Copilot

Hook Analysis:

• evaluate_python_hook - Execute hooks in sandboxed environment
• debug_hook - Expert debugging with Opus sub-agent

Schema:

• create_schema_with_subagent - Create new schemas via Opus sub-agent
• patch_schema_with_subagent - Safe schema modifications via Opus

Deployment:

• deploy_pull - Pull configs from organization
• deploy_diff - Compare local vs remote
• deploy_push - Push local changes
• deploy_copy_org - Copy entire organization
• deploy_copy_workspace - Copy single workspace
• deploy_compare_workspaces - Compare two workspaces
• deploy_to_org - Deploy to target organization

Multi-Environment:

• spawn_mcp_connection - Connect to different Rossum environment
• call_on_connection - Call tools on spawned connection
• close_connection - Close spawned connection

Skills:

• load_skill - Load domain-specific workflows (rossum-deployment, hook-debugging, schema-patching, schema-pruning, organization-setup, schema-creation, ui-settings, rules-and-actions, formula-fields, reasoning-fields)

Task Tracking:

• create_task - Create a task to track progress on multi-step operations
• update_task - Update a task's status (pending, in_progress, completed) or subject
• list_tasks - List all tracked tasks with current status

Dynamic MCP Tool Loading

Tools are loaded on-demand to reduce context usage. Use load_tool_category to load tools by category:

Category	Description
annotations	Upload, retrieve, update, confirm documents
queues	Create, configure, list queues
schemas	Define, modify field structures
engines	Extraction and splitting engines
hooks	Extensions and webhooks
email_templates	Automated email responses
document_relations	Export/einvoice links
relations	Annotation relations
rules	Schema validation rules
users	User and role management
workspaces	Workspace management

Categories are auto-loaded based on keywords in the user's message.

Architecture

flowchart TB
    subgraph UI["User Interface"]
        A[REST API]
    end

    subgraph Agent["Rossum Agent (Claude Bedrock)"]
        IT[Internal Tools]
        DT[Deploy Tools]
        MT[Spawn MCP Tools]
        SK[Skills System]
    end

    subgraph MCP["Rossum MCP Server"]
        Tools[63 MCP Tools]
    end

    API[Rossum API]

    UI --> Agent
    Agent --> MCP
    MCP --> API

REST API Endpoints

Endpoint	Description
GET /api/v1/health	Health check
GET /api/v1/chats	List all chats
POST /api/v1/chats	Create new chat
GET /api/v1/chats/{id}	Get chat details
DELETE /api/v1/chats/{id}	Delete chat
POST /api/v1/chats/{id}/messages	Send message (SSE)
GET /api/v1/chats/{id}/files	List files
GET /api/v1/chats/{id}/files/{name}	Download file

API docs: /api/docs (Swagger) or /api/redoc

SSE Events: The message endpoint streams these SSE event types:

SSE event:	Description
step	Agent steps (thinking, tool calls, final answer)
sub_agent_progress	Sub-agent iteration updates
sub_agent_text	Sub-agent text streaming
task_snapshot	Task tracker state after each task mutation
file_created	Output file notification
done	Final event with token usage
error	Agent execution error

MCP Mode: Chat sessions support mode switching via the mcp_mode parameter:

• Set at chat creation: POST /api/v1/chats with {"mcp_mode": "read-write"}
• Override per message: POST /api/v1/chats/{id}/messages with {"content": "...", "mcp_mode": "read-write"}

License

MIT License - see LICENSE for details.

Resources

• Full Documentation
• MCP Server README
• Rossum API Documentation
• Main Repository