Run Configuration

This page explains the runtime config you pass into agents such as ReactiveAgent. The goal is not only to list fields, but to make it clear which fields are required, which are policy, and which affect runtime behavior versus tool execution.

1. Two Inputs Go Into a Run

Every run has two distinct inputs:

This distinction matters because the SDK separates per-invocation message state from runtime policy and dependencies.

It also matters because some low-level runtime fields are intentionally not exposed on ReactiveAgentConfig today. If you need verificationGate, sandboxProvider, pluginManager, taskRouter, agentBus, or compactionConfig, use Low-Level Runtime.

2. Minimal ReactiveAgent.run() Shape

// Assume `provider`, `tools`, `projectId`, `sessionId`, and `tenantId`
// have already been prepared by your app-level runtime bootstrap.
const result = await agent.run(
  {
    messages: [{ role: 'user', content: 'Hello' }],
    workingDirectory: process.cwd(),
  },
  {
    provider,
    tools,
    model: 'gpt-4o-mini',
    tokenBudget: 8_192,
    timeoutMs: 60_000,
    projectId,
    sessionId,
    tenantId,
  },
)

At minimum, a practical run needs:

• provider
• tools
• model
• tokenBudget
• timeoutMs
• projectId
• sessionId
• tenantId
• messages
• workingDirectory

3. Core Runtime Fields

4. Limit and Budget Fields

These settings shape the runtime loop, not only the provider call.

5. Permission and Environment Fields

permissionMode is especially important:

• auto is the normal runtime mode
• plan blocks non-read-only tools at execution time in the tool registry

env is useful when tools need controlled environment data such as:

• API base URLs
• feature flags
• CLI-specific runtime variables

6. Prompt and Behavior Fields

ReactiveAgentConfig also supports higher-level prompt and reasoning inputs:

These fields change how the runtime assembles prompt context before it calls the provider.

7. Hierarchy and Advanced Fields

These are more relevant for supervisors, orchestration layers, or manager-driven spawning than for the first quickstart.

8. AgentInput Fields

AgentInput includes these runtime-time fields:

workingDirectory affects several built-in tools directly:

• read_file
• write_file
• edit
• ls
• glob
• grep
• bash

9. Runtime Defaults at the SDK Level

The SDK also exports RuntimeConfigSchema and RUNTIME_DEFAULTS for higher-level application config assembly.

Important defaults include:

Those defaults are useful for application-level config objects, but most production apps should still set explicit values for the runs they actually care about.

10. Recommended App Pattern

Use one app-level runtime config object and derive agent configs from it:

import {
  RUNTIME_DEFAULTS,
  generateProjectId,
  generateSessionId,
  generateTenantId,
} from '@namzu/sdk'
 
const runtime = {
  ...RUNTIME_DEFAULTS,
  model: 'gpt-4o-mini',
  tokenBudget: 16_384,
  timeoutMs: 120_000,
}
 
// Assume `provider` and `tools` were created during runtime bootstrap.
const agentConfig = {
  provider,
  tools,
  model: runtime.model,
  tokenBudget: runtime.tokenBudget,
  timeoutMs: runtime.timeoutMs,
  maxIterations: runtime.maxIterations,
  temperature: runtime.temperature,
  projectId: generateProjectId(),
  sessionId: generateSessionId(),
  tenantId: generateTenantId(),
}

11. Common Mistakes

Related

• SDK Quickstart
• Run Identities
• Low-Level Runtime
• Tool Safety
• SDK Runtime
• RuntimeConfigSchema Source