Agent commands. Your AI agent uses this node in workflows. You don’t configure it directly.
Parameters
| Parameter | Type | Required | Default | Description |
|---|
prompt | str | Yes | - | Text prompt, or path to an external file (e.g., ./prompts/system.md) |
model | str | No | See below | Model identifier |
system | str | No | - | System prompt for behavior guidance |
temperature | float | No | 1.0 | Sampling temperature (0.0-2.0) |
max_tokens | int | No | - | Maximum response tokens |
images | list | No | [] | Image URLs or file paths for vision models |
output_schema | dict | No | - | JSON Schema for structured output |
Model resolution
If model is not specified in workflow params, pflow auto-detects based on your configured API keys.
Most users just need an API key:
pflow settings set-env OPENAI_API_KEY "sk-..."
Output
| Key | Type | Description |
|---|
response | str or dict | Text response (str), or parsed JSON (dict) when output_schema is set |
llm_usage | dict | Token usage metrics |
error | str | Error message (only present on failure) |
Token usage structure
{
"model": "gpt-5.2",
"input_tokens": 150,
"output_tokens": 89,
"total_tokens": 239,
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 0
}
Model support
These providers are included with pflow - just set your API key:
| Provider | Example models |
|---|
| OpenAI | gpt-5.2, gpt-5.1, gpt-4o |
| Anthropic | claude-opus-4-5, claude-sonnet-4-5, claude-haiku-4-5 |
| Google | gemini-3.0-pro, gemini-2.5-flash |
# Set API keys (stored in ~/.pflow/settings.json)
pflow settings set-env OPENAI_API_KEY "sk-..."
pflow settings set-env ANTHROPIC_API_KEY "sk-ant-..."
pflow settings set-env GEMINI_API_KEY "..."
Run llm models to see all available models on your system.
Extending with plugins
pflow uses Simon Willison’s llm library, which supports plugins for additional providers and local models.
Installing plugins
If you installed pflow with uv tool, include plugins during installation:
uv tool install --with llm-openrouter pflow-cli
pipx, use inject to add plugins:
pipx inject pflow-cli llm-openrouter
Plugins must be installed in pflow’s environment. Running llm install separately won’t work with isolated installations.
Popular plugins
| Plugin | Install flag | Use case |
|---|
llm-openrouter | --with llm-openrouter | Access Claude, GPT, Llama, Mistral via OpenRouter |
llm-ollama | --with llm-ollama | Run models locally with Ollama |
# OpenRouter - get key from https://openrouter.ai/keys
llm keys set openrouter
# Ollama - no API key needed
brew install ollama
ollama serve
ollama pull llama3.2
Using plugin models
OpenRouter models use the openrouter/provider/model format:
### summarize
Summarize content using OpenRouter.
- type: llm
- model: openrouter/anthropic/claude-sonnet-4-5
- prompt: Summarize this
### summarize
Summarize content using a local model.
- type: llm
- model: llama3.2
- prompt: Summarize this
Image support
For vision-capable models, pass image URLs or local file paths:
### describe
Describe the contents of a photo.
- type: llm
- prompt: What's in this image?
- model: gpt-5.2
- images: ["photo.jpg"]
- Local file paths:
photo.jpg, /path/to/image.png
- URLs:
https://example.com/image.jpg
Examples
Basic prompt
### summarize
Summarize the content from the previous step.
- type: llm
- prompt: Summarize: ${read.content}
- model: gpt-4o-mini
With system prompt
### translate
Translate the input text to Spanish.
- type: llm
- system: You are a translator. Respond only with the translation.
- prompt: Translate to Spanish: ${input.text}
- temperature: 0.3
Structured output
Use output_schema to get guaranteed JSON matching a schema. The schema is passed to the model’s constrained decoding API — the model literally cannot produce non-conforming output.
### extract
Extract named entities from the document.
- type: llm
- prompt: Extract entities from: ${document.content}
- temperature: 0
```yaml output_schema
type: object
properties:
people:
type: array
items:
type: string
places:
type: array
items:
type: string
required:
- people
- places
```
output_schema is set, response is a dict — downstream templates access fields directly: ${extract.response.people}.
Without output_schema, you can still get JSON by prompting for it. The template system auto-parses JSON strings when you use dot notation: ${extract.response.people}. But the model may not always comply — output_schema is the reliable approach.
Image analysis
### analyze
Analyze the contents of a user-provided image.
- type: llm
- prompt: Describe the main elements in this image
- model: gpt-5.2
- images: ["${file_path}"]
External prompt file
For long or reusable prompts, reference an external file instead of inlining. The file path is relative to the workflow file. Template variables (${var}) inside the file are resolved normally.
### analyze
Analyze source code for issues.
- type: llm
- prompt: ./prompts/code-review.md
Error handling
| Error | Cause | Solution |
|---|
| Unknown model | Model ID not recognized | Run llm models to see available models |
| API key required | Missing credentials | Set up with llm keys set <provider> or env var |
| Rate limit | Too many requests | Wait and retry automatically (built-in retry) |
