Agent
The dxflow agent turns a natural-language request into a runnable workflow and then operates it. It never runs containers itself — it drives the same workflow engine described in Core Concepts through a small set of tools. Creating, running, and fixing workflows all happen in one conversation, and a single session can create and operate several workflows.
Providers
The agent works with any of these providers — pick the one you have an account with. Set agent-provider to name it, or leave it unset and the agent figures it out from agent-url. The setup is the same three settings for all of them: pick the provider, point it at the url, and paste your key.
| Provider | agent-provider | agent-url contains | Default model |
|---|---|---|---|
| Amazon Bedrock | bedrock | bedrock | amazon.nova-micro-v1:0 |
| Claude | claude | anthropic.com | claude-haiku-4-5 |
| Gemini | gemini | googleapis.com | gemini-2.5-flash-lite |
| OpenAI-compatible | openai | anything else | gpt-5-nano (official only) |
Configure it in a profile or via environment variables — the shape is the same for every provider:
dxflow config set agent-provider bedrock
dxflow config set agent-url https://bedrock-runtime.us-east-1.amazonaws.com
dxflow config set agent-model amazon.nova-pro-v1:0
# paste the API key you created in the AWS Bedrock console
dxflow config set agent-key <bedrock-api-key>
dxflow config set agent-url https://api.anthropic.com
dxflow config set agent-key sk-ant-...
dxflow config set agent-model claude-sonnet-5
dxflow config set agent-url https://generativelanguage.googleapis.com
dxflow config set agent-key AIza...
dxflow config set agent-model gemini-2.5-flash
dxflow config set agent-url https://api.openai.com/v1
dxflow config set agent-key sk-...
dxflow config set agent-model gpt-5
agent-key is your key for the provider you picked, and it can't be left empty. For Claude, Gemini, and OpenAI, paste the API key from that provider. For Amazon Bedrock, paste the API key you create in the AWS Bedrock console — the region is taken from agent-url. Want a different model for one question? Add --model to the command. Leave agent-model unset and the agent uses the default from the table above.What the agent can do
You ask in plain language and the agent decides how to carry it out. Across a conversation it can:
- Find and build — search the hub for a ready-made template, or turn your description into a workflow, and create it.
- Run and control — start a workflow, stop a running one, and check where it stands.
- Watch progress — read a step's logs and its CPU and memory usage, while it runs or after it finishes.
- Work with files — list and read a workflow's files, and upload or replace an input.
- Inspect the setup — read back a workflow's definition and the overrides applied to it, to see exactly what it declares.
- Reconfigure — change ports, passwords, environment variables, resources, or volumes without rewriting the workflow.
It works across every workflow on the engine. When you don't name one, it acts on the workflow you used most recently.
Working with the agent
You interact by prompting in plain language. Each prompt is one turn: the agent replies with a short message, takes one or more of the actions above, and shows you what happened. It remembers the whole conversation, so each prompt builds on the last.
dxflow agent ask <identity> "create an ubuntu desktop with fastqc"
dxflow agent ask <identity> "start"
dxflow agent ask <identity> "show me the logs"
Observing a run
You can ask for progress at any time, even while a workflow is still running. The agent reads the logs and resource usage and hands back a short, readable summary rather than raw output.
Sessions
A session is a single conversation with the agent. It remembers everything said and done — your messages, the agent's replies, and the workflows it has worked on — along with how many tokens it has used and the latest model it ran. You can list your sessions, inspect one, or remove it like any other engine resource.
dxflow agent create --workflow ebc954e7f50e
dxflow agent ask <identity> "start"
dxflow agent inspect <identity>
Prompt caching
Every turn reuses the provider's prompt cache for the repeated prefix (tools, system prompt, then the conversation so far), and inspect reports a session's cache reads and writes. Caching turns on only once that prefix clears the model's minimum cacheable length — roughly 1024 tokens for Claude Sonnet/Opus, 2048 for Haiku — so below the floor the counters stay at zero; this is expected.
claude-sonnet-4-5 (1024) caches where claude-haiku-4-5 (2048) may not. Padding the prompt to reach the floor costs more than it saves.See the CLI reference for every command and the API reference for every endpoint.