Profile

A profile configures an Agent node's provider, model, reasoning effort, and additional provider arguments. The node selects it independently of its session, which controls conversation continuity. One profile may serve several independent sessions.

Scope

A profile ID denotes a role, such as decrementer or planner. The selected provider and options belong to the concrete profile configuration, so a caller can bind the same parameter to different configurations.

The options object holds model, reasoning_effort, and extra_args. Provider-specific settings belong in extra_args, with one list item per command-line argument. For example:

Provider	extra_args	Effect
Codex	["-c", "web_search=\"live\""]	Request live web search.
Codex	["-c", "web_search=\"disabled\""]	Disable the web search tool.
Claude	["--tools", "Read,Glob,Grep,WebSearch,WebFetch"]	Select file-reading and web tools.

See the Codex configuration reference and Claude CLI reference for provider options. Codex uses its configured defaults when no override is supplied. Read-only Claude requests default to Read,Glob,Grep; an explicit --tools list may select those tools and WebSearch,WebFetch. Editing and command-execution tools remain unavailable in read-only requests. Additional arguments cannot override runtime-managed flags for workspace access, output collection, or session handling.

Profiles are either local or parameters:

Kind	Configuration
Local profile	The subroutine owns a generated invoker configured by its profile declaration.
Profile parameter	A workflow entry or subroutine call maps the parameter to a profile in the caller's resource scope.

Generated interface

The Agent node's generated declaration selects a profile ID. Its authored visit calls context.invoke() through that binding; it need not construct an agent provider or choose a model. Selecting a profile does not select a conversation: the node's session binding controls that separately.

Local profiles

A local subroutine profile module exports INVOKER, the AgentInvoker constructed from its provider configuration. Codex profiles construct CodexInvoker; Claude profiles construct ClaudeInvoker.

The generated configure(input: Input, params: Params, /) -> AgentInvoker accepts the subroutine's boundary types and returns that same INVOKER. PROFILE, an AgentProfileDefinition[Input, Params], records the profile's ID, name, and implementation=configure. This initializer is generated, not an authored callback.

Profile parameters

A caller-supplied slot exports PROFILE_PARAMETER, an AgentProfileParameter containing its ID and name. Its module also exports RESOLVED_INVOKERS, a tuple of the concrete invokers that the parameter resolves to through call paths inside the project:

• A workflow entry's profile_arguments maps the parameter to a workflow-owned profile.
• A subroutine call's profile_arguments maps it to the caller's local profile or to another profile parameter. In the latter case, resolution follows that parameter's callers until it reaches concrete profiles.

Generated import aliases begin with WORKFLOW_ or SUBROUTINE_ and include the binding definition's canonical ID and the concrete profile ID. If a parameter is bound only by callers outside this project, RESOLVED_INVOKERS is empty. The tuple supports source navigation; the runtime binds the parameter at the call independently of it.

Workflow profiles

A workflow-owned profile module exports its configured INVOKER directly. The workflow collects these invokers by profile ID and maps them to its entry subroutine's parameters; see Workflow: Profile declarations and registry.

Authored files

Profiles have no authored files. Configure the provider, options, and resource mappings in project.json; generation maintains the Python interface. Prompts and response handling belong to the authored Agent visit.

Files

General profile structure

profiles/
├── ◆ __init__.py
├── <local-profile>/
│   └── ◆ __init__.py
└── <profile-parameter>/
    └── ◆ __init__.py

File	Role
◆ profiles/__init__.py	Collects local profiles in PROFILES and profile parameters in PROFILE_PARAMETERS.
◆ profiles/<profile>/__init__.py	Declares either a local PROFILE or a caller-supplied PROFILE_PARAMETER.

These paths are relative to a subroutine. A workflow owns concrete profiles in the corresponding directories, with its declarations and registry described under Workflow: Profile declarations and registry.

Countdown example

Countdown separates its subroutine's profile parameter from the workflow's concrete agent provider configuration.

Source: project.json

{
  "id": "decrementer",
  "name": "Decrementer",
  "provider": "codex",
  "options": {
    "model": null,
    "reasoning_effort": null,
    "extra_args": []
  }
}

This entry in workflow.profiles configures the concrete decrementer profile with Codex, no model or reasoning-effort override, and no extra arguments.

Source: ◆ subroutines/main/profiles/decrementer/__init__.py

from typing import Final
from verdog_runtime.declarations import AgentProfileParameter
from demo.countdown.subroutines.main import PROFILE_IDS
from demo.countdown.workflows.main.profiles.decrementer import (
    INVOKER as WORKFLOW_MAIN__DECREMENTER_INVOKER,
)

PROFILE_PARAMETER: Final[AgentProfileParameter] = AgentProfileParameter(
    id=PROFILE_IDS.decrementer,
    name='Decrementer',
)
RESOLVED_INVOKERS: Final = (WORKFLOW_MAIN__DECREMENTER_INVOKER,)

PROFILE_PARAMETER declares the subroutine's caller-supplied resource. RESOLVED_INVOKERS exposes the workflow's concrete invoker for source navigation; the runtime binds the parameter when the subroutine is called. The decrement node selects this parameter independently of its session.

Source: ◆ workflows/main/profiles/decrementer/__init__.py

from typing import Final
from verdog_runtime.agents.codex import CodexInvoker
from verdog_runtime.declarations import AgentInvoker

INVOKER: Final[AgentInvoker] = CodexInvoker(
    model=None,
    reasoning_effort=None,
    extra_args=(),
)

The generated invoker uses Codex's configured defaults. The Agent visit invokes it through context.invoke(); changing this profile's configuration does not change the visit's task logic. The separately selected countdown session determines whether later decrements continue the conversation.