Chains

Build and execute multi-step AI workflows with the SDK

Chains allow you to build complex multi-step AI workflows where outputs from one step feed into the next. Perfect for content pipelines, data processing, and complex reasoning tasks.

List Chains

const chains = await client.chains.list({
  mine: true,
  limit: 100
})

chains.forEach(chain => {
  console.log(`${chain.name} - ${chain.steps.length} steps`)
  console.log(`  Intent tags: ${chain.intentTags.join(', ')}`)
  console.log(`  Active: ${chain.isActive}`)
})

Get a Chain

const chain = await client.chains.get('chain-id')

console.log(chain.name)
console.log('Required inputs:', chain.requiredInputs)
console.log(`Steps: ${chain.steps.length}`)

chain.steps.forEach(step => {
  console.log(`  Step ${step.order}: ${step.type}`)
  console.log(`    Output key: ${step.outputKey}`)
})

Create a Chain

Create a new chain with required inputs defined as a JSON Schema.

const chain = await client.chains.create({
  name: 'content-pipeline',
  description: 'Generate, refine, and optimize content',

  // Intent tags for routing (required, minimum 1)
  intentTags: ['content', 'blog', 'writing'],

  // Define what inputs this chain needs
  requiredInputs: {
    type: 'object',
    properties: {
      topic: {
        type: 'string',
        description: 'Content topic'
      },
      audience: {
        type: 'string',
        description: 'Target audience'
      }
    },
    required: ['topic']
  },

  isActive: true  // Enable for routing
})

console.log(`Created chain: ${chain.id}`)

Intent tags are required and used by the routing system to match user queries to the right chain.

Add Steps to Chain

Build your workflow by adding steps. Each step can reference previous step outputs or the chain's initial input.

// Step 1: Generate outline
await client.chains.createStep(chain.id, {
  order: 0,
  type: 'PROMPT',
  promptId: 'outline-generator-id',

  // Map inputs using template syntax
  inputMapping: {
    topic: '{{input.topic}}',        // From chain input
    audience: '{{input.audience}}'    // From chain input
  },

  outputKey: 'outline'  // This step's output variable name
})

// Step 2: Write content based on outline
await client.chains.createStep(chain.id, {
  order: 1,
  type: 'PROMPT',
  promptId: 'content-writer-id',

  inputMapping: {
    outline: '{{outline}}',          // From step 1
    topic: '{{input.topic}}',        // From chain input
    audience: '{{input.audience}}'   // From chain input
  },

  outputKey: 'draft'
})

// Step 3: Polish and refine
await client.chains.createStep(chain.id, {
  order: 2,
  type: 'PROMPT',
  promptId: 'editor-id',

  inputMapping: {
    content: '{{draft}}'             // From step 2
  },

  outputKey: 'final_content'
})

Template Syntax

Use double curly braces to reference variables:

{{input.field_name}} - From chain's initial input
{{output_key}} - From previous step's output

The SDK automatically populates inputMapping based on prompt input schemas when you create steps through the UI.

Execute a Chain

Execute a chain with input data. The chain will run all steps in order and return the final output.

const result = await client.chains.execute('chain-id', {
  topic: 'The Future of AI in Healthcare',
  audience: 'Healthcare Professionals'
})

console.log('Final Output:')
console.log(result.output)
console.log()
console.log('Execution Metrics:')
console.log(`  Status: ${result.status}`)
console.log(`  Total Latency: ${result.latencyMs}ms`)
console.log(`  Total Cost: $${result.costUsd}`)
console.log()
console.log('Step-by-Step Results:')
result.steps.forEach(step => {
  console.log(`  Step ${step.order + 1}:`)
  console.log(`    Latency: ${step.latencyMs}ms`)
  console.log(`    Output: ${step.output.substring(0, 100)}...`)

  if (step.error) {
    console.log(`    Error: ${step.error}`)
  }
})

Update a Chain

const updated = await client.chains.update('chain-id', {
  name: 'improved-content-pipeline',
  description: 'Updated description',
  intentTags: ['content', 'blog', 'writing', 'marketing'],
  isActive: true,

  // Update required inputs schema
  requiredInputs: {
    type: 'object',
    properties: {
      topic: { type: 'string' },
      audience: { type: 'string' },
      tone: {
        type: 'string',
        enum: ['professional', 'casual', 'technical']
      }
    },
    required: ['topic']
  }
})

Delete a Chain

await client.chains.delete('chain-id')
console.log('Chain deleted')

Complete Example: Content Pipeline

import Prompt Forge from '@promptforge/sdk'

const client = new Prompt Forge({
  apiKey: process.env.PROMPTFORGE_API_KEY
})

async function createAndExecutePipeline() {
  // Create chain
  const chain = await client.chains.create({
    name: 'blog-post-pipeline',
    description: 'Complete blog post generation workflow',
    intentTags: ['blog', 'content', 'writing'],
    requiredInputs: {
      type: 'object',
      properties: {
        topic: { type: 'string' },
        keywords: { type: 'string' }
      },
      required: ['topic']
    }
  })

  // Add steps
  await client.chains.createStep(chain.id, {
    order: 0,
    type: 'PROMPT',
    promptId: 'research-prompt-id',
    inputMapping: {
      topic: '{{input.topic}}'
    },
    outputKey: 'research'
  })

  await client.chains.createStep(chain.id, {
    order: 1,
    type: 'PROMPT',
    promptId: 'outline-prompt-id',
    inputMapping: {
      topic: '{{input.topic}}',
      research: '{{research}}'
    },
    outputKey: 'outline'
  })

  await client.chains.createStep(chain.id, {
    order: 2,
    type: 'PROMPT',
    promptId: 'writer-prompt-id',
    inputMapping: {
      outline: '{{outline}}',
      keywords: '{{input.keywords}}'
    },
    outputKey: 'final'
  })

  // Execute chain
  const result = await client.chains.execute(chain.id, {
    topic: 'Best Practices for API Design',
    keywords: 'REST, GraphQL, versioning, documentation'
  })

  console.log('Generated Blog Post:')
  console.log(result.output)
  console.log(`\nTotal cost: $${result.costUsd}`)
  console.log(`Total time: ${result.latencyMs}ms`)
}

createAndExecutePipeline()

Next Steps

→ Learn about intelligent routing to chains → View execution history and analytics