DocsWorkflowsComponentsMachinemachine:agent:session:create

machine:agent:session:create

Runs one turn of a coding agent session against a working directory and returns the session it ran, the agent's final message, the tools it called and what the turn spent. The agent runs headless through its own CLI, which has to be installed on the machine the run happens on, and reports what it does as it does it on step.progress events, each carrying a type of session, message or tool on IO.Partial. A coding agent runs commands of its own, so the step is behind the same host permission as machine:shell:exec.

Options

Name	Type	Description
`agent`	`string`	The coding agent to run, one of claude-code, codex, gemini or opencode
`agent_path`	`string`	The agent's executable, a bare name or a path, found on PATH by its usual name when empty
`prompt`	`string`	The task handed to the agent as its first turn, or as the next turn of a resumed session
`dir`	`string`	Working directory the agent runs in; defaults to the pipeline cwd
`session_id`	`string`	The session to resume, as an earlier step returned it; empty starts a new session
`model`	`string`	The model the agent runs on, as the agent names it (provider/model for opencode); empty keeps the agent's default
`effort`	`string`	The reasoning effort the agent runs at, as the agent names its levels; empty keeps the agent's default
`args`	`[]string`	Extra command-line arguments handed to the agent's CLI, such as a permission mode or sandbox flag

Outputs

Name	Type	Description
`session_id`	`string`	The session the agent ran, which a later step passes back to resume it
`message`	`string`	The agent's final message of the turn
`model`	`string`	The model that answered, where the agent reported it or the step named it
`tools`	`[]ToolUse`	How many times the agent called each tool, one entry per tool
↳ `name`	`string`	The tool the agent called, as the agent names it
↳ `calls`	`int`	How many times the agent called it
`usage`	`Usage`	The tokens the turn spent and what they cost, the agent's subagents included where its stream reports them
↳ `input_tokens`	`int64`	Prompt tokens the provider did not serve from its cache
↳ `output_tokens`	`int64`	Completion tokens, reasoning included
↳ `cache_read_tokens`	`int64`	Prompt tokens served from the provider's prompt cache
↳ `cache_write_tokens`	`int64`	Prompt tokens written into the provider's prompt cache
↳ `reasoning_tokens`	`int64`	The part of the output tokens the model spent thinking
↳ `cost_usd`	`float64`	What the tokens cost in US dollars, zero where nothing recorded or priced it
`duration_ms`	`int64`	How long the agent ran

Example

name: Fix the failing test
actions:
  - name: fix
    component: machine:agent:session:create
    vars:
      agent: claude-code
      dir: ./project
      prompt: Run the test suite and fix whatever fails.
      args: ["--permission-mode", "acceptEdits"]

  - name: review
    component: machine:agent:session:create
    vars:
      agent: claude-code
      dir: ./project
      session_id: "{{ fix.session_id }}"
      prompt: Add a regression test for the fix.
      args: ["--permission-mode", "acceptEdits"]

outputs:
  session: "{{ review.session_id }}"
  summary: "{{ review.message }}"
  cost_usd: "{{ review.usage.cost_usd }}"

Edit or read the source on GitHub