> ## Documentation Index
> Fetch the complete documentation index at: https://flowdrop.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://github.com/oracle/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

```typescript theme={null}
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

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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](/guides/advanced/event-system) for the full event reference.

## Next steps

* [Programmatic API](/guides/advanced/programmatic-api) — create workflows in code
* [Event System](/guides/advanced/event-system) — all execution events
* [Workflow Structure](/guides/workflow-json) — FlowDrop's native JSON format