Skip to main content
An assistant is a core component of the Kodexa platform that responds to events within a project. Assistants listen for events (such as document creation, updates, or custom triggers) and execute configured actions in response.

​
Assistant Roles

Assistants operate in one of two roles, which determines how they process events:

​
Robotic Assistant

The Robotic Assistant executes a curated sequence of modules you configure. When triggered, it runs each module in order as a deterministic pipeline. This is the default role and is ideal for well-defined, repeatable document processing workflows. Key characteristics:
  • Deterministic — Modules run in a fixed, configured order
  • Pipeline-based — Each step receives the output of the previous step
  • Configurable — Module options and conditional execution per step

​
Agentic Assistant

The Agentic Assistant delegates event processing to an AI agent that autonomously decides how to handle documents. Instead of a fixed pipeline, the agent uses configured modules as tools and follows a prompt to determine the best processing approach. Key characteristics:
  • Autonomous — The AI agent decides which modules to invoke and in what order
  • Prompt-driven — Behavior is guided by a natural language prompt
  • Adaptive — Can vary its approach based on document content and context

​
Configuring an Agentic Assistant

Agentic assistants require three configuration elements:
SettingDescription
Agent RuntimeThe agent runtime environment that will execute the agent
Module ReferencesModules available as tools for the agent to use
PromptNatural language instructions guiding the agent’s behavior
# Example agentic assistant configuration
role: AGENTIC
options:
  agentRuntimeId: "runtime-uuid"
  moduleRefs:
    - "module://kodexa/pdf-parser"
    - "module://kodexa/invoice-extractor"
  prompt: |
    Process incoming documents by first parsing them,
    then extracting invoice data if the document appears
    to be an invoice.
  taxonomies:
    - "acme-corp/invoice-taxonomy"
When an event triggers an agentic assistant, the platform:
  1. Provisions an authentication token for the agent
  2. Gathers document context from the event
  3. Invokes the agent runtime asynchronously with the prompt, module references, and document context
  4. The agent processes documents and reports results back to the platform

​
What is Event Processing in an Assistant?

An assistant is a collection of event handlers that are triggered when certain events occur in the Kodexa platform. For example, when a document is created, updated, or deleted, the assistant can be triggered to perform specific actions on the document.

​
Custom Events

Custom events can also be triggered by the assistant, which can be used for testing, training, etc. When a use case requires processing to occur at certain times, the assistant can be triggered based on a schedule to perform the processing.

​
Assistants in Data Flow

Assistants appear in the project’s Data Flow view, showing how they connect to document stores and other project resources. The data flow view displays:
  • Which stores the assistant listens to for events
  • The assistant’s role (robotic or agentic)
  • For robotic assistants, the configured module pipeline
  • For agentic assistants, the agent runtime and available modules

​
Working with Assistants in Python

Assistants are based on an Assistant Definition, and you create an instance of the assistant on a specific project. Here’s how you can work with assistants using the Kodexa Python client:
  1. Connect to the Kodexa platform:
from kodexa.platform import KodexaClient

client = KodexaClient()
  1. Find your organization and project:
org = client.organizations.find_by_slug('acme-corp')
project = org.projects.find_by_name('Invoice Processing')
  1. List assistants in the project:
assistants = project.assistants.list()
for a in assistants:
    print(f"{a.name} ({a.role})")

​
Assistant Resource URI

Assistants are project-scoped resources and can be referenced using the assistant scheme: 
assistant://orgSlug/projectSlug/assistantSlug
See Components and Structure for details on resource URIs and the resolver API.