doc request: Need better examples for tool calling and llm_task in the middle

[gotexis]

Hi, me (and my agent) stuggles to write up a .lobster yaml . The agent end up having this (ugly) yaml and it's semi-working, but I doubt this is the right syntax.

We call it in openclaw cron like such:
Run the lobster pipeline: {\"action\":\"run\",\"pipeline\":\"pipelines/daily-standup.lobster\",\"timeoutMs\":60000}, summarize

name: daily-standup
args:
  team:
    default: "CLAW"
  project:
    default: "E-commerce"
  limit:
    default: "30"

steps:
  - id: list-tickets
    command: >
      (jira issues search "" --status Todo) 2>/dev/null |
      jq -s '[.[][] | {id: .identifier, title, status: .state.name, priority: .priority,
         labels: [.labels[]?.name // empty],
         assignee: (.assignee.name // "unassigned")}] | sort_by(.priority)'

  - id: invoke-llm
    command: >
      OPENCLAW_URL=http://localhost:18789 OPENCLAW_TOKEN=$OPENCLAW_GATEWAY_TOKEN lobster 'exec --shell "cat /tmp/lobster-standup-tickets.json" | llm_task.invoke --prompt "Summarize the top 10 most urgent tickets for the daily standup."
 
   # from here, ideally pipe out from llm and into something else ... ?

Try throwing in llm_task.invoke, openclaw.invoke --tools llm_task, clawd.invoke --tools llm_task but nothing works except this ugly matter.

[vignesh07]

Yep — agreed this is currently too hard to use, especially when mixing “shell steps” (jira/jq) with “Lobster commands” (llm_task.invoke / openclaw.invoke) and when invoked from OpenClaw cron.

Two key mental-model points:

1. steps[].command runs in /bin/sh. If you want to run a Lobster pipeline stage from there, it must be a real executable.
2. To pass data between steps, prefer stdin: $prevStep.stdout instead of temp files.

Recent fixes on openclaw/lobster main

• openclaw.invoke is now the primary name (with clawd.invoke as an alias).
• Lobster now installs shim executables openclaw.invoke / clawd.invoke, so you can call tools directly from workflow steps without the nested lobster '...pipeline...' quoting.

What your workflow can look like

(rough sketch — depends on what your jira CLI prints)

name: daily-standup
steps:
  - id: list-tickets
    command: >
      jira issues search "..." --status Todo | jq -s '[.[][] | {id: .identifier, title, status: .state.name}]'

  - id: summarize
    command: >
      llm_task.invoke --prompt "Summarize the top 10 most urgent tickets for the daily standup."
    stdin: $list-tickets.stdout

Prereqs:

• OPENCLAW_URL must be set (and OPENCLAW_TOKEN if needed), since llm_task.invoke calls into the OpenClaw gateway.

If you can paste a minimal sample of the jira ... JSON output you’re piping into jq, I can turn the above into an exact working .lobster file.

[Bandwe]

I've created PR #42 with comprehensive examples for calling LLMs and OpenClaw tools from Lobster workflows.

The PR adds:

• examples/ directory with 4 ready-to-run workflow files
• examples/README.md with detailed documentation and common patterns
• Updates to the main README.md with enhanced LLM and OpenClaw tool sections

The examples cover:

1. Basic LLM invocation
2. LLM calls with human approval gates
3. Three methods to call OpenClaw tools (openclaw.invoke, pipeline, clawd.invoke)
4. Data passing between steps without temp files

Hope this helps clarify the syntax! 🦞

[Bandwe]

Thanks for raising this! I understand the frustration with figuring out the right syntax for LLM calls in Lobster workflows.

I've created some comprehensive examples that should help clarify the different approaches:

Quick Answer

For calling LLMs in the middle of a workflow, use the pipeline: syntax with llm.invoke:

steps:
  - id: fetch-data
    run: echo "Some data to process"

  - id: summarize
    pipeline: llm.invoke --prompt "Summarize the following:"
    stdin: $fetch-data.stdout

Key Points

1. pipeline: vs run::

   • Use pipeline: for native Lobster stages like llm.invoke
   • Use run: for shell executables like openclaw.invoke

2. LLM invocation options:

   • llm.invoke --provider openclaw --prompt "..." (recommended)
   • llm_task.invoke --prompt "..." (backward-compatible alias for openclaw provider)
   • openclaw.invoke --tool llm-task --action json --args-json '{"prompt":"..."}' (shell mode)

3. Passing data with stdin:

   • stdin: $step.stdout - pass raw stdout as text
   • stdin: $step.json - parse stdout as JSON, then pass

Complete Examples

I've created a full set of working examples here: https://github.com/openclaw/lobster-examples

• llm-task-examples.lobster - 5 different ways to call LLMs
• stdin-pipeline-examples.lobster - Passing data between steps
• email-processing.lobster - Complete real-world example

Your Original Example, Fixed

Here's how your daily-standup workflow could look:

name: daily-standup
args:
  team:
    default: "CLAW"
  project:
    default: "E-commerce"

steps:
  - id: list-tickets
    run: >
      (jira issues search "" --status "Todo" 2>/dev/null |
      jq -s '[.[][] | {id: .identifier, title, status: .state.name, priority: .priority,
         labels: [.labels[]?.name // empty],
         assignee: (.assignee.name // "unassigned")}] | sort_by(.priority)')

  - id: summarize
    pipeline: >
      llm.invoke --provider openclaw --prompt "Summarize the top 10 most urgent tickets for the daily standup. Return as markdown."
    stdin: $list-tickets.json

  - id: output
    run: cat
    stdin: $summarize.stdout

The key fix: use pipeline: with llm.invoke and pass data with stdin: $list-tickets.json.

Let me know if this clears things up! 🦞