Agent Spec integration

Import and export workflows using Agent Spec — an open standard for AI agent definitions, originally published by Oracle.

FlowDrop supports Agent Spec — an open standard for defining AI agent workflows, originally published by Oracle as a vendor-neutral specification. You can import Agent Spec documents into FlowDrop for visual editing and export FlowDrop workflows back to Agent Spec format.

What is Agent Spec?

Agent Spec is a JSON format for describing agent workflows with:

Nodes (called "steps") with component types
Control-flow edges for execution order
Data-flow edges for data passing
Agent-level metadata (name, description, version)

Import / export via UI

FlowDrop's toolbar includes import/export options:

Import: Click the import button and select an Agent Spec JSON file. FlowDrop converts it to a visual workflow with auto-layout.
Export: Click the export button and choose "Agent Spec" format. FlowDrop converts the visual workflow to Agent Spec JSON and downloads it.

Programmatic usage

Using the adapter directly

import { AgentSpecAdapter, WorkflowAdapter } from '@flowdrop/flowdrop/core';

const workflowAdapter = new WorkflowAdapter(nodeTypes);
const agentSpecAdapter = new AgentSpecAdapter();

// Import: Agent Spec JSON → FlowDrop Workflow
const standardWorkflow = agentSpecAdapter.importJSON(agentSpecJsonString);
const editorWorkflow = workflowAdapter.toSvelteFlow(standardWorkflow);

// Export: FlowDrop Workflow → Agent Spec JSON
const standardWorkflow = workflowAdapter.fromSvelteFlow(editorWorkflow);
const agentSpecJson = agentSpecAdapter.exportJSON(standardWorkflow);

Using the WorkflowOperationsHelper

import { WorkflowOperationsHelper } from '@flowdrop/flowdrop/editor';

// Export current workflow as Agent Spec
const result = WorkflowOperationsHelper.exportAsAgentSpec(workflow);
if (result.valid) {
  // Downloads .json file automatically
} else {
  console.error('Export errors:', result.errors);
  console.warn('Warnings:', result.warnings);
}

// Import from a File object
const imported = await WorkflowOperationsHelper.importFromAgentSpec(file);

Using the Mount API

The mounted app exposes Agent Spec operations:

const app = await mountFlowDropApp(container, options);

// Export
app.export(); // downloads JSON

// Get the current workflow
const workflow = app.getWorkflow();

Validation

Validate a workflow before exporting to Agent Spec:

import { validateForAgentSpecExport } from '@flowdrop/flowdrop/core';

const result = validateForAgentSpecExport(workflow);
// { valid: boolean, errors: string[], warnings: string[] }

Common validation issues:

Disconnected nodes (no edges)
Missing required port connections
Unsupported node types

Conversion details

What maps cleanly

FlowDrop	Agent Spec
Node ID	Auto-generated stable name
Node type	Component type
Config values	Node attributes
Trigger edges	Control-flow edges
Data edges	Data-flow edges
Gateway branches	`from_branch` mappings
Node position	Preserved in metadata

Known limitations

Loopback edges don't have a direct Agent Spec equivalent and may be dropped
Custom node types (namespaced) may lose type-specific behavior
UISchema layout information is not preserved
Dynamic ports may not convert cleanly
Node visual types (simple, square, etc.) are stored in metadata but not in the Agent Spec standard

Execution events

When running Agent Spec workflows, FlowDrop fires execution events:

eventHandlers: {
  onAgentSpecExecutionStarted: (executionId) => {
    console.log('Execution started:', executionId);
  },
  onAgentSpecNodeStatusUpdate: (nodeId, status) => {
    console.log(`Node ${nodeId}: ${status.status}`);
  },
  onAgentSpecExecutionCompleted: (executionId, results) => {
    console.log('Completed:', results);
  },
  onAgentSpecExecutionFailed: (executionId, error) => {
    console.error('Failed:', error.message);
  }
}

See Event System for the full event reference.

Next steps

Programmatic API — create workflows in code
Event System — all execution events
Workflow Structure — FlowDrop's native JSON format

On this page