Skip to main content

Agent Recipes

Practical, copy-paste workflows you can run from your coding agent. Each recipe shows the natural language prompt, the workflow JSON, and what to expect.

tip

These recipes assume you have a Jetty token and collection set up. See Setup or the Claude Code Plugin for onboarding.

Recipe 1: Create and Run a Workflow from Your Editor​

Ask your agent:

"Create a Jetty task called 'summarizer' that takes a topic and generates a summary using GPT-4o-mini, then run it with topic 'quantum computing'"

The workflow JSON:

{
  "init_params": {
    "topic": "quantum computing"
  },
  "step_configs": {
    "summarize": {
      "activity": "litellm_chat",
      "model": "gpt-4o-mini",
      "prompt_path": "init_params.topic",
      "system_prompt": "Write a concise 2-paragraph summary of the given topic."
    }
  },
  "steps": ["summarize"]
}

What happens:

  1. Agent calls create-task to save the workflow definition
  2. Agent calls run-workflow (or run-workflow-sync) with init_params
  3. Agent calls get-trajectory to fetch results
  4. Result is at steps.summarize.outputs.content

Recipe 2: Compare Two Models and Pick the Best​

Ask your agent:

"Create a workflow that asks both GPT-4o and Claude to write a haiku about rain, then uses a judge to pick the better one"

The workflow JSON:

{
  "init_params": {
    "topic": "rain"
  },
  "step_configs": {
    "gpt_haiku": {
      "activity": "litellm_chat",
      "model": "gpt-4o",
      "prompt": "Write a haiku about {{ init_params.topic }}"
    },
    "claude_haiku": {
      "activity": "litellm_chat",
      "model": "claude-sonnet-4-20250514",
      "prompt": "Write a haiku about {{ init_params.topic }}"
    },
    "judge": {
      "activity": "simple_judge",
      "model": "gpt-4o",
      "items": [
        "{{ gpt_haiku.outputs.content }}",
        "{{ claude_haiku.outputs.content }}"
      ],
      "instruction": "Which haiku is more evocative and follows the 5-7-5 syllable structure better? Pick the best one.",
      "score_range": ["gpt-4o", "claude"]
    }
  },
  "steps": ["gpt_haiku", "claude_haiku", "judge"]
}

Key output paths:

  • GPT haiku: steps.gpt_haiku.outputs.content
  • Claude haiku: steps.claude_haiku.outputs.content
  • Judgment: steps.judge.outputs.results[0].judgment
  • Explanation: steps.judge.outputs.results[0].explanation

Recipe 3: Generate an Image and Auto-Evaluate Quality​

Ask your agent:

"Create a workflow that generates a cat image with Flux, then judges whether it's cute"

The workflow JSON:

{
  "init_params": {
    "prompt": "a fluffy orange tabby cat sitting in a sunbeam"
  },
  "step_configs": {
    "generate_image": {
      "activity": "replicate_text2image",
      "model": "black-forest-labs/flux-schnell",
      "prompt_path": "init_params.prompt",
      "output_format": "webp"
    },
    "judge_cuteness": {
      "activity": "simple_judge",
      "model": "gpt-4o",
      "item_path": "generate_image.outputs.images[0].path",
      "instruction": "Rate the cuteness of this cat image.",
      "score_range": ["not cute", "somewhat cute", "very cute", "extremely cute"]
    }
  },
  "steps": ["generate_image", "judge_cuteness"]
}

Notes:

  • simple_judge supports images — pass a storage path (.webp, .png, .jpg) as item_path and it auto-converts for vision
  • The generated image is at steps.generate_image.outputs.images[0].path
  • Download it via https://flows-api.jetty.io/api/v1/file/{path}

Recipe 4: Batch Process Items in Parallel​

Ask your agent:

"Create a workflow that takes a list of topics and summarizes each one in parallel using GPT-4o-mini"

This uses the fan-out pattern with list_emit_await:

Parent workflow (batch-summarizer):

{
  "init_params": {
    "topics": ["quantum computing", "gene editing", "fusion energy"]
  },
  "step_configs": {
    "fan_out": {
      "activity": "list_emit_await",
      "items_path": "init_params.topics",
      "child_workflow_name": "summarize-one",
      "item_param_name": "topic",
      "max_concurrency": 3
    },
    "gather": {
      "activity": "extract_from_trajectories",
      "trajectory_ids_path": "fan_out.outputs.trajectory_ids",
      "extract_paths": {
        "summary": "steps.summarize.outputs.content"
      }
    }
  },
  "steps": ["fan_out", "gather"]
}

Child workflow (summarize-one):

{
  "init_params": {
    "topic": ""
  },
  "step_configs": {
    "summarize": {
      "activity": "litellm_chat",
      "model": "gpt-4o-mini",
      "prompt": "Write a 2-sentence summary of: {{ init_params.topic }}"
    }
  },
  "steps": ["summarize"]
}

What happens:

  1. list_emit_await spawns one child workflow per topic, running up to 3 in parallel
  2. extract_from_trajectories gathers the summary field from each child's trajectory
  3. Final results are at steps.gather.outputs.results

Recipe 5: Monitor and Debug a Failing Workflow​

Ask your agent:

"Show me the last 5 runs of my summarizer task and label any failures"

What the agent does (MCP tools):

  1. list-trajectories with collection and task=summarizer, limit=5
  2. For each trajectory, checks status — if failed, calls get-trajectory for full details
  3. Examines steps.{step_name}.error to find which step failed and why
  4. Calls add-label with key=review-status, value=needs-fix on failed trajectories

Useful debugging patterns:

# Ask your agent:
"What's the error in the last failed run of cute-feline-detector?"
"Show me the init_params for trajectory abc123"
"Get the stats for my summarizer task — what's the success rate?"
"Download the image from the last successful run of cute-feline-detector"

Key data locations in a trajectory:

  • Input parameters: .init_params
  • Step outputs: .steps.{step_name}.outputs
  • Step errors: .steps.{step_name}.error
  • Generated files: .steps.{step_name}.outputs.files[].path or .outputs.images[].path

Next Steps​

  • Common Gotchas — Known parameter mismatches and API quirks
  • Step Library — Full reference for all available activities
  • Guides — Deeper tutorials on specific use cases