agent

Spawn an agent turn through the existing pool. Templated prompt, optional skills + tools whitelist. Reuses subprocesses via --resume when the session matches an existing one.

Source	internal/agents/workflow/nodes/agent.go
When to use	A step needs an actual AI turn — reasoning, tool use, free-form generation. Don't use for routing (use classify) or pure shaping (use transform).
Gate	Participates in Command Gate policy — PermissionMode + AskUserMode apply.

Schema

Field	Type	Required	Notes
prompt	string	✅	Inline prompt rendered as a Go template with .Event, .Node, .Trigger context.
provider	string		Provider name (claude, codex, gemini, …). Optional — falls back to workflow default.
skills	array		Skill names to expose to this turn. Per-provider — see Providers.
tools	array		Tool names to allowlist. Empty = provider default.
max_turns	int		Cap on agentic turns passed as --max-turns to the provider CLI. 0 (default) = unlimited (provider default).
session	string		new = fresh session per run, empty = inherit the run's session.

Output

Whatever the agent emits. The executor merges text_delta chunks into a single result string and exposes typed events (tool_use, tool_result, thinking) on the run timeline for replay.

Example

{
  "id": "bug_report",
  "type": "agent",
  "prompt": "You are a support engineer.\n\nNew bug from {{.Event.User.Name}}:\n> {{.Event.Payload.text}}\n\nUse the `gh` CLI to file the issue. Reply with the issue URL.",
  "provider": "claude",
  "skills": ["shell", "git"],
  "max_turns": 3
}

Pool integration

When the resolved provider can route via the pool, the executor:

1. Subscribes to the session's event stream before dispatching the pool send (no leading event lost).
2. Enqueues the turn through the agent pool — FIFO queue, slot allocation, session reuse, sidebar visibility.
3. Streams events back into the workflow run's events.jsonl.

For non-pool providers (codex / gemini), the executor falls back to the direct provider.AgentCall path.

Pair with

• session_init — inject a first-turn context (project / chat / user / link) before the agent runs.
• classify — cheap routing in front of an expensive agent call.
• channel — post the agent's reply back to the inbound channel.