Configuration Reference

Configuration Reference

Every field of a kind: agent step. All string fields are template-rendered before the step runs.

- step: <name>
  tool:
    kind: agent
    framework: claude | claude-code
    model: <model id>
    prompt: <text>
    # ...fields below

Common fields

Field	Type	Required	Default	Meaning
framework	claude | claude-code	yes	—	Which backend runs the agent. Any other value is rejected.
model	string	yes	—	Model id, e.g. claude-sonnet-5-5. Passed to the API or to claude --model.
prompt	string	yes	—	The user message that starts the run.
system	string	no	—	claude: system prompt. claude-code: appended to Claude Code's own (--append-system-prompt).

framework: claude fields

Field	Type	Required	Default	Meaning
auth	object	yes	—	{type: api_key, credential: <alias>}. No auth: → the step fails.
tools	list	no	[]	Tools the model may call; see below.
max_turns	int ≥ 1	no	8	Maximum model calls; the step fails past it.
max_tokens	int	no	4096	max_tokens per model call.
temperature	number	no	API default	Sampling temperature.
endpoint	URL	no	https://api.anthropic.com	Base URL. For tests and API-compatible gateways; requests go to <endpoint>/v1/messages.
thinking	disabled | adaptive	no	model default	Sent as thinking: {type}. Some models (e.g. Haiku) think adaptively on hard turns, which can spend all of max_tokens on reasoning; disabled for summaries. Needs noetl 5.3.0.
effort	low | medium | high	no	model default	Sent as output_config.effort. Needs noetl 5.3.0.
prompt_cache	bool	no	true	Anthropic prompt caching: each turn re-reads earlier turns at the cached rate. Needs noetl 5.3.0.

tools entries

Field	Required	Default	Sent to the model	Meaning
name	yes	—	✓	Name the model calls. Must be non-empty.
description	no	""	✓	When and why to use the tool.
input_schema	no	{type: object, properties: {}}	✓	JSON Schema of the input object.
playbook	yes, in the CLI	—	✗	Tool playbook path, relative to the agent playbook.

Inside the tool playbook, each top-level key of the model's input is {{ workload.<key> }} (non-string values arrive JSON-encoded; {{ arrives as { {). The tool's answer is the sub-playbook's final_result; if it fails, the model gets the error with is_error: true.

Credential aliases (local mode)

credential: <alias> resolves, in order:

1. the environment variable NOETL_CREDENTIAL_<ALIAS> (alias upper-cased, every non-alphanumeric character as _), when non-blank;
2. the file ~/.config/noetl/credentials/<alias>, which must be mode 600. Create it with noetl credential set <alias> or noetl credential google <alias> …. Needs noetl 5.2.0 (noetl/cli#96); 5.1.0 reads the environment variable only.

alias	variable	file
anthropic	NOETL_CREDENTIAL_ANTHROPIC	~/.config/noetl/credentials/anthropic
gmail-work	NOETL_CREDENTIAL_GMAIL_WORK	~/.config/noetl/credentials/gmail-work

Aliases may contain only letters, digits, -, _, . (not leading). A value found nowhere, or a blank one, stops the step before any network call. A file readable by group or others is refused.

framework: claude-code fields

Field	Type	Default	Meaning
claude_bin	path	claude on PATH	The Claude Code CLI. Under systemd, set it or include ~/.local/bin in the unit's PATH.
allowed_tools	list of strings	none	Tools Claude Code may use (--allowed-tools): built-ins like Read, or MCP tools as mcp__<server>__<tool>. Empty means no tools.
mcp_config	list of paths	none	MCP config files (--mcp-config). Always passed with --strict-mcp-config, so only these servers load.
workdir	path	the noetl process's	Working directory for Claude Code (file tools resolve against it).

Refused for claude-code: auth (the CLI signs in itself) and tools (use allowed_tools / mcp_config). Ignored: max_turns, max_tokens, temperature, endpoint.

http steps: credential aliases

Requires noetl 5.2.0 (noetl/cli#96). type: is accepted as an alias of provider:. The credential alias may be templated, e.g. credential: "gmail-{{ workload.account }}".

- step: list
  tool:
    kind: http
    method: GET
    url: https://gmail.googleapis.com/gmail/v1/users/me/messages
    auth:
      type: google_oauth
      credential: gmail-work

type	header sent	credential
gcp / google / adc	Authorization: Bearer <ADC token>	none (Application Default Credentials)
bearer	Authorization: Bearer <value>	required
api_key	<header>: <value>; header: defaults to X-API-Key	required
google_oauth	Authorization: Bearer <access token>	required; created by noetl credential google

A google_oauth credential (a refresh-token document) is refused for bearer / api_key, so a refresh token is never sent as-is to the step's URL.

noetl credential

command	does
noetl credential set <alias>	store a secret from a hidden prompt, or stdin when piped
noetl credential google <alias> --client-secret-file <f> [--scope s]… [--login-hint email] [--no-open] [--port p]	browser OAuth for a Google account; stores its refresh token (default scope gmail.readonly)
noetl credential list	alias, type (secret / google_oauth) and file mode, never values
noetl credential path	print the credentials directory

Step-level fields that apply

Field	Applies to	Meaning
timeout	both	claude: per-HTTP-request timeout. claude-code: whole run; the child is killed. Default 300 s.
executor.requires.tools: [agent] (playbook level)	both	Makes a noetl without kind: agent refuse the playbook instead of skipping the step.

Step result

The step result is a JSON string; parse it in later steps or read it from noetl run --json (final_result / step_results.<step>).

{
  "text": "…",
  "turns": 2,
  "usage": { "input_tokens": 1073, "output_tokens": 167 },
  "stop_reason": "end_turn",
  "model": "claude-sonnet-5-5"
}

With noetl 5.3.0, usage also has cache_read_input_tokens and cache_creation_input_tokens, and a text answer cut off at max_tokens carries "truncated": true. claude-code adds "framework": "claude-code" and "permission_denials": [...]. See Architecture § The step result for where each field comes from.