Skip to main content

Xircuits & Visual Programming

Xircuits is the visual programming system that lets you define agent workflows by wiring together nodes on a canvas instead of writing code. It sits alongside the conversational agent definition (system prompts and tools) as a complementary way to express what an agent should do -- particularly useful for structured, repeatable processes where you want the workflow to be visible at a glance.

What Xircuits Is​

At its core, Xircuits is a graph editor. You place component nodes on a canvas, connect their input and output ports, and the resulting graph defines a data flow. When compiled, the graph becomes executable Python code that the platform can run as a job or deploy as a long-running service.

Think of it as a visual alternative to writing Python scripts for agent workflows. The visual representation makes it easier to understand what a workflow does, especially for non-developers or when reviewing complex multi-step processes.

Three Workflow Types​

Xircuits workflows come in three flavors, each suited to different use cases:

TypePurposeHow It Runs
AGENTConversational workflows with LLM interactionDeployed as a Knative service, responds to messages
SERVICELong-running background processesDeployed as a Knative service, runs continuously
OTHEROne-off or scheduled batch jobsRuns as a Kubernetes Job (one-shot or cron-scheduled)
info

The workflow type determines both the deployment target and the available component nodes. AGENT workflows have access to conversation and messaging components, while SERVICE workflows have access to event listeners and polling components.

The Studio IDE​

Xircuits Studio is a browser-based IDE for creating and editing workflows. It runs as a Knative service in the user's Kubernetes namespace and provides:

  • A drag-and-drop canvas for placing and connecting nodes
  • A component library browser
  • Real-time compilation and validation
  • File management for .xircuits files

Studio shares the same container image as the agent runtime, which means it has access to the same Python environment, packages, and NFS file mount. This is intentional -- it ensures that what you build in Studio runs identically when deployed.

Component Model​

Components are the building blocks of Xircuits workflows. Each component is a Python class that defines:

  • Input ports: The data the component receives
  • Output ports: The data the component produces
  • Execute logic: What happens when the component runs

The platform ships with pre-built components for common tasks:

  • LLM calls: Send prompts to language models, handle responses
  • File operations: Read, write, and transform files on the NFS mount
  • Data transforms: Parse JSON, filter lists, format strings
  • API calls: Make HTTP requests to external services
  • Platform operations: Send messages, create tasks, query conversations

You can also create custom components by writing a Python class that follows the component protocol.

Wiring and Data Flow​

The visual graph defines data flow, not control flow. When you connect an output port of Component A to an input port of Component B, you are saying "the output of A becomes the input of B." Rather than writing imperative control logic (if/else, loops, sequencing), you define what data goes where, and the runtime resolves the execution order from the graph topology -- components still execute in dependency order, but the order is determined automatically from the connections you draw, not from the position of lines in a script.

In this example, the LLM call cannot execute until the prompt is formatted, and the CRM update cannot execute until the response is parsed. But the CRM update and the notification can potentially execute in parallel since they depend on different outputs of the same component.

Compilation​

When you compile a Xircuits workflow, the visual graph is converted to executable Python code. The compiler:

  1. Resolves the execution order from the graph topology
  2. Generates a Python script that instantiates each component
  3. Wires the data flow between components
  4. Wraps the whole thing in an entry point that the platform's job runner or Knative service can invoke

The compiled output is a standard Python file that can be inspected, debugged, and even modified (though changes to the compiled file will be overwritten on the next compilation).

Run Options​

Once compiled, a workflow can be executed in three ways:

Run ModeMechanismUse Case
One-off jobKubernetes JobAd-hoc tasks, data processing, one-time operations
ScheduledQuartz scheduler creates K8s Jobs on a cron scheduleRecurring reports, periodic data syncs
Deployed serviceKnative ServiceAlways-on agents, event-driven workflows
note

Scheduled workflows use the Quartz scheduler (described in the platform architecture docs) to create Kubernetes Jobs at the specified intervals. This means scheduled workflows benefit from K8s Job guarantees -- they will be retried if they fail, and they leave behind logs you can inspect.

Auto-Discovered Tools​

One of the more powerful features of the Xircuits integration is automatic tool discovery. When a Xircuits workflow is compiled and present in an agent's directory, the platform discovers it and makes it available as a tool. This discovery happens at deploy time when the agent's directory is scanned for compiled workflows. This means:

  1. You create a workflow that, say, generates a weekly report
  2. You compile it and save it to the agent's directory
  3. The agent can now call this workflow as a tool during conversations
  4. No manual tool registration needed -- the platform scans for compiled .xircuits files and makes them available

This bridges the visual programming world and the conversational agent world: you define complex, multi-step processes visually, and agents can invoke them as tools when they need to.

Filesystem Storage​

Xircuits files (.xircuits) are stored on the NFS mount under the user's or project's directory, following the standard platform directory resolution pattern:

  • Personal projects: /data/home/xai_components/ (resolved via user ID)
  • Team projects: /data/home/xai_components/ (resolved via project ID)

Workflows are stored as .xircuits files on the NFS mount and are accessible from both Studio and the agent runtime.

See Also​