Agent Decision ExecModule

Overview

AgentDecisionModule is the model boundary in ValkyrAI's durable decide-act-observe loop. Version 2.0 declares the fourteen workflow-state inputs it can consume, all eight outputs it can emit, its server-configured outbound network boundary, and the exact failure modes that prevent unvalidated model text from becoming an action.

The module asks one ACL-visible LlmDetails model for the next provider-neutral decision. It projects bounded task, project, observation, artifact, approval, failure, tool-catalog, and GrayMatter retrieval context into the shared LLM gateway. The response must satisfy the typed AgentDecision protocol before AgentLoopModule or AgentToolModule can use it.

Agent Decision does not execute a tool, grant approval, create an object, deploy anything, or treat free-form model text as authority.

Usage

1. Put the current task in agentTask, or configure taskField to name the workflow-state field that contains it.
2. Supply the latest user message, observation, artifact references, and exact pending approval context that apply to this decision.
3. Select an ACL-visible model with llmDetailsId, or use the bounded modelSelection policy.
4. Run Agent Decision once.
5. Pass agentDecision to AgentLoopModule; only a governed AgentToolModule may execute a validated tool_calls decision.

Use the durable loop for retries. A repeated model call can produce a different response and can incur additional provider usage.

Inputs

All inputs are workflow-state values. None may contain raw provider credentials.

Input	Type	Required	Description
llmDetailsId	UUID	No	ACL-visible model UUID. Overrides configured model selection.
sessionId	string	No	SageChat session identifier used by the shared gateway. sessionField can select another state field.
agentTask	any JSON-safe value	No	Canonical task or structured task context. taskField can select another state field.
agentUserMessage	string	No	Latest user instruction used as ephemeral request context.
agentProjectContext	object	No	Tenant-authorized project, attachment, and recent-history context.
agentObservation	any JSON-safe value	No	Latest safe tool observation.
agentArtifactRefs	array	No	Durable content-free artifact references from prior steps.
agentToolCatalog	object	No	Server-authorized tool names and bounded descriptions. The built-in governed catalog is used when absent.
securityContextualToolVisibility	boolean	No	When true, require server policy to filter the tool catalog for this task. Defaults to false.
agentApprovalGranted	boolean	No	One-decision approval flag bound only to agentApprovalRequest. Defaults to false.
agentApprovalRequest	object	No	Exact pending approval request authorized for the current decision.
agentStep	integer	No	Current bounded loop step. Defaults to 0.
agentPreviousFailure	string	No	Bounded prior failure supplied for recovery planning.
agentFailureAttempts	integer	No	Consecutive recoverable decision failures. Defaults to 0.

Tenant context is projected to at most eight nested levels, 64 items per collection, and 16,000 characters per text value. The complete serialized decision state is capped at 600,000 characters. Cycles and excess depth are replaced with content-free omission markers.

Outputs

Output	Type	Condition	Description
agentDecision	object	Success	Validated provider-neutral decision.
agentDecisionOutcome	string	Success	Normalized outcome such as tool_calls, final_answer, ask_user, wait_approval, continue, or failed.
agentRetrievalEvidence	array	Valid retrieval metadata	Up to four content-free GrayMatter receipt/policy projections. Raw retrieved content and tenant identifiers are not copied.
retrievalReceiptRef	string	Valid retrieval metadata	Primary authenticated retrieval receipt ID.
costTokens	integer	Success	Non-negative provider-reported token count, or zero when unavailable.
costCredits	number	Success	Non-negative provider-reported credit use, or zero when unavailable.
agentToolCatalog	object	Success	Exact server-computed tool catalog supplied to the model.
agentApprovalGranted	boolean	Success	Always reset to false so approval cannot leak into a later decision.

The output map is cleared before every attempt. A failed rerun cannot leave a prior decision or approval flag available to downstream modules.

IntegrationAccount Requirements

No workflow-supplied IntegrationAccount is read by this module, and raw API keys, tokens, endpoints, or provider credentials are not accepted as inputs or configuration.

The selected LlmDetails record must be visible to the authenticated workflow session. Provider authentication and allowed destinations are owned by the shared LLMController deployment. If no model UUID is supplied, LlmDetailsService discovers only models visible under the current ACL.

Configuration

Field	Type	Default	Description
llmDetailsId	UUID	none	Optional pinned ACL-visible model. Workflow input can override it.
modelSelection	string	session-default-valor	Fallback policy: session-default-valor, first-visible, or name:<visible model name>.
taskField	string	agentTask	Workflow-state field containing the project task.
sessionField	string	sessionId	Workflow-state field containing the SageChat session identifier.

Unsupported selection policies and unavailable named models fail closed. Model discovery never scans or returns models outside the caller's generated ACL visibility.

Operations

Agent Decision exposes one outbound operation:

1. Clear prior output.
2. Resolve an ACL-visible LlmDetails UUID.
3. Project bounded control state and the server-authorized tool catalog.
4. Call the shared LLM compatibility gateway once.
5. Reject non-success responses and malformed protocol output.
6. Emit one typed decision, safe usage values, the exact tool catalog, and optional content-free retrieval lineage.
7. Reset agentApprovalGranted to false.

The module never invokes a proposed tool. A tool_calls outcome remains inert until AgentToolModule validates and brokers it.

Errors and Failure Modes

Failure	Cause	Retryable	Recovery
IllegalArgumentException	Invalid model UUID/policy, no ACL-visible model, unserializable state, or state above the 600,000-character cap.	No until corrected	Correct the named state or model selection.
SecurityException	Contextual tool filtering was requested but the server-owned visibility policy is unavailable.	No until service recovery	Restore the shared policy; never fall back to an unfiltered catalog.
AgentDecisionCallException	The shared gateway failed or returned a non-success response.	Bounded loop policy only	Verify model/provider readiness and retry through the durable loop.
AgentDecisionProtocolException	Provider output failed typed AgentDecision parsing.	Bounded loop policy only	Let the next bounded attempt use the recorded protocol correction. Never execute the rejected text.

Errors do not include credentials or the complete control envelope. The module does not automatically retry provider calls because a repeated request can consume credits and produce a different decision.

Example

Configuration:

{
  "modelSelection": "session-default-valor",
  "taskField": "agentTask",
  "sessionField": "sessionId"
}

Input workflow state:

{
  "agentTask": "Inspect the release evidence and continue until deployment is verified",
  "sessionId": "session-42",
  "agentStep": 3,
  "agentArtifactRefs": ["deployment:release-42"],
  "agentApprovalGranted": false
}

Representative expected result after the provider returns a valid tool decision:

{
  "agentDecisionOutcome": "tool_calls",
  "agentDecision": {
    "outcome": "TOOL_CALLS",
    "toolCalls": [
      {
        "name": "workflow.execution.inspect",
        "arguments": {
          "executionId": "release-42"
        }
      }
    ]
  },
  "costTokens": 128,
  "costCredits": 0,
  "agentApprovalGranted": false
}

This output is a validated proposal. It does not prove that the tool ran or that deployment is complete.

Notes

• Pagination: not applicable. Retrieval evidence is capped at four projections and each projected string/list is bounded.
• Limits: control context is depth/item/text bounded and the complete serialized state is capped at 600,000 characters.
• Idempotency: provider inference is not idempotent. Do not replay a request outside the durable loop or assume identical output or cost.
• Rate limits: provider-specific limits apply through the shared LLM gateway. The module performs one gateway request per execution and no internal retry.
• API constraints: model UUIDs and discovery are ACL-filtered; provider hosts are deployment-owned server configuration, never workflow input.
• Destructive behavior: none. The module cannot execute tools, mutate infrastructure, grant approval, or delete data.
• External data: the bounded control envelope is sent to the selected model provider and is classified confidential.
• Approval: agentApprovalGranted authorizes only the exact supplied agentApprovalRequest for this decision and is reset in every successful output.
• GrayMatter: only bounded content-free receipt and policy lineage is emitted; raw retrieval content is not copied into outputs.
• Runtime boundary: source merge updates the catalog contract, but production Workflow Studio does not expose v2 until the backend serving /v1/modules/metadata is deployed.

Related Documentation

• ExecModule catalog
• Agent Completion ExecModule
• Workflow Studio production guide
• Module authoring and testing