Workflow Management

Visualize and manage multi-agent workflow executions

Workflow Management

Visualize and manage multi-agent workflow executions

Agentfield automatically constructs workflow DAGs (Directed Acyclic Graphs) from execution traces, enabling you to visualize how agents coordinate across distributed systems. No manual instrumentation required—just use workflow headers.

Note: The current release only exposes the DAG retrieval endpoint. Session listings, cleanup APIs, and workflow event streams are not yet available.

Quick Start

Visualize a workflow's execution graph:

curl http://localhost:8080/api/v1/workflows/wf_customer_support_001/dag

Response:

{
  "workflow_id": "wf_customer_support_001",
  "nodes": [
    {
      "execution_id": "exec_abc123",
      "node_id": "support-agent",
      "target": "analyze_sentiment",
      "status": "succeeded",
      "duration_ms": 1247
    },
    {
      "execution_id": "exec_def456",
      "node_id": "escalation-agent",
      "target": "create_ticket",
      "status": "succeeded",
      "duration_ms": 892
    }
  ],
  "edges": [
    {
      "from": "exec_abc123",
      "to": "exec_def456"
    }
  ]
}

How Workflows Work

When agents execute with the same X-Workflow-ID header, Agentfield automatically:

  1. Links executions using parent-child relationships
  2. Constructs DAGs showing execution flow
  3. Tracks timing for each step
  4. Preserves context across agent boundaries
// Step 1: Sentiment analysis
const sentiment = await fetch(
  'http://localhost:8080/api/v1/execute/support-agent.analyze_sentiment',
  {
    headers: { 'X-Workflow-ID': 'wf_123' },
    // ...
  }
);

// Step 2: Automatic escalation (Agentfield links these)
const ticket = await fetch(
  'http://localhost:8080/api/v1/execute/escalation-agent.create_ticket',
  {
    headers: { 'X-Workflow-ID': 'wf_123' },
    // ...
  }
);

Agentfield automatically creates: sentiment → escalation in the workflow DAG.

Get Workflow DAG

Examples

curl http://localhost:8080/api/v1/workflows/wf_customer_support_001/dag

Workflow Patterns

Linear Workflow

Sequential agent execution:

const workflowId = 'wf_linear_001';

// Step 1
await fetch('http://localhost:8080/api/v1/execute/agent-a.process', {
  headers: { 'X-Workflow-ID': workflowId },
  // ...
});

// Step 2
await fetch('http://localhost:8080/api/v1/execute/agent-b.analyze', {
  headers: { 'X-Workflow-ID': workflowId },
  // ...
});

// Step 3
await fetch('http://localhost:8080/api/v1/execute/agent-c.finalize', {
  headers: { 'X-Workflow-ID': workflowId },
  // ...
});

DAG: A → B → C

Parallel Workflow

Multiple agents execute concurrently:

const workflowId = 'wf_parallel_001';

// Execute in parallel
await Promise.all([
  fetch('http://localhost:8080/api/v1/execute/sentiment-agent.analyze', {
    headers: { 'X-Workflow-ID': workflowId },
    // ...
  }),
  fetch('http://localhost:8080/api/v1/execute/topic-agent.extract', {
    headers: { 'X-Workflow-ID': workflowId },
    // ...
  }),
  fetch('http://localhost:8080/api/v1/execute/intent-agent.classify', {
    headers: { 'X-Workflow-ID': workflowId },
    // ...
  })
]);

DAG: Three parallel branches from root

Conditional Workflow

AI-driven routing based on results:

const workflowId = 'wf_conditional_001';

// Step 1: Analyze
const analysis = await fetch(
  'http://localhost:8080/api/v1/execute/analysis-agent.evaluate',
  {
    headers: { 'X-Workflow-ID': workflowId },
    // ...
  }
).then(r => r.json());

// Step 2: Route based on AI decision
if (analysis.result.priority === 'high') {
  await fetch('http://localhost:8080/api/v1/execute/urgent-agent.handle', {
    headers: { 'X-Workflow-ID': workflowId },
    // ...
  });
} else {
  await fetch('http://localhost:8080/api/v1/execute/standard-agent.handle', {
    headers: { 'X-Workflow-ID': workflowId },
    // ...
  });
}

DAG: analysis → (urgent OR standard) based on AI decision

Best Practices

1. Use Meaningful Workflow IDs

Generate descriptive workflow identifiers:

// Good
const workflowId = `wf_customer_support_${customerId}_${Date.now()}`;

// Avoid
const workflowId = 'wf_123';

2. Combine with Session IDs

Link workflows to user sessions for better tracking:

curl -X POST http://localhost:8080/api/v1/execute/agent.reasoner \
  -H "X-Workflow-ID: wf_support_001" \
  -H "X-Session-ID: session_user_456" \
  -H "X-Actor-ID: user_456"

3. Monitor Workflow Depth

Keep workflows focused—deeply nested workflows can be hard to debug:

// Good: 2-4 levels deep
A → B → C → D

// Avoid: Excessive nesting
A → B → C → D → E → F → G → H

4. Clean Up Completed Workflows

Regularly clean up old workflow data:

import requests
from datetime import datetime, timedelta

# Clean up workflows older than 30 days
cutoff = datetime.now() - timedelta(days=30)

# Get workflows and clean up old ones
# (Implementation depends on your workflow tracking)

Visualizing Workflows

The workflow DAG can be visualized using graph libraries:

// Using D3.js or similar
const dag = await fetch(
  'http://localhost:8080/api/v1/workflows/wf_001/dag'
).then(r => r.json());

// Create graph visualization
const graph = {
  nodes: dag.nodes.map(n => ({
    id: n.execution_id,
    label: n.target,
    status: n.status
  })),
  edges: dag.edges.map(e => ({
    source: e.from,
    target: e.to
  }))
};

// Render with your preferred graph library
renderGraph(graph);
PreviousMemory Operations
NextWebhooks