System Prompt

The system prompt is what turns a general model into your agent. It decides tone, priorities, and which rules the agent treats as non-negotiable. Qoder Agent SDK gives you three layers, and they compose. Start at the least invasive layer and move down only when you need to:

Layer	Mechanism	Use it when
Append to the preset	`systemPrompt` / `system_prompt` preset form	You want qodercli's agent behavior plus your own rules
Load instruction files	`settingSources` / `setting_sources`	The rules live in the repository and should apply to humans too
Replace entirely	`systemPrompt` / `system_prompt` string	You are building a non-coding agent with its own behavior contract

Both SDKs support all three layers. Python additionally accepts a file form that TypeScript does not — see Load the prompt from a file.

Append to the preset

This is the recommended default. The Qoder CLI preset carries the tool-use discipline, planning behavior, and output conventions that make the agent converge on long tasks. Appending keeps all of it and adds your rules at the end.

options: {
  systemPrompt: {
    type: 'preset',
    preset: 'qodercli',
    append: [
      'Always write tests before implementation.',
      'Never edit files under vendor/.',
      'Reply in Simplified Chinese.',
    ].join('\n'),
  },
}

Prefer this form for anything that reads like a house rule. Rewriting the whole prompt to add three rules discards behavior you did not intend to change.

Replace the prompt entirely

Passing a string overrides the preset. The agent keeps its tools and its loop, but nothing else is assumed about how it should behave.

options: {
  systemPrompt: `You are a release auditor.

Inspect the repository and report findings. You may read files and run
read-only commands. Never modify the working tree. Answer with a numbered
list of findings, each tagged CRITICAL, WARNING, or INFO.`,
}

This is the layer that makes the SDK usable beyond coding assistants. A triage agent, a data-analysis agent, and a documentation agent can each replace the prompt while reusing the same harness — the agent loop, tool execution, permission enforcement, and session management stay in place.

A full override removes the preset's guardrails along with its style. If the replacement prompt says nothing about verifying changes or staying inside the working directory, the agent has no instruction to do so. Pair a full override with explicit permissions.

Load the prompt from a file

The Python SDK accepts a third form that reads the prompt from disk. This keeps a long prompt out of application code and lets it be versioned and reviewed on its own.

options = QoderAgentOptions(
    system_prompt={"type": "file", "path": "./prompts/release-auditor.md"},
)

Language availability: Python only.The file form has no TypeScript equivalent. In TypeScript, read the file yourself and pass the contents as a string.

Load instructions from the filesystem

Instruction files let rules live next to the code they govern, so the same guidance applies whether a human or an agent is working. settingSources decides which of them the session reads.

// Load user, project, and local instruction files (CLI default behavior)
options: { settingSources: ['user', 'project', 'local'] }

// Load nothing from disk — the application is the only source of truth
options: { settingSources: [] }

Use settingSources: [] for multi-tenant or hosted deployments. Otherwise the agent's behavior depends on whatever files happen to exist on the machine running Qoder CLI, which makes runs non-reproducible across hosts.

Observe what actually loaded

A prompt problem is usually an "I didn't know that file was in there" problem. The InstructionsLoaded hook fires once per instruction file, so you can log the real composition instead of guessing.

options: {
  hooks: {
    InstructionsLoaded: [
      {
        hooks: [
          async (input) => {
            console.log(`[instructions] ${input.memory_type} ${input.file_path} (${input.load_reason})`);
            return {};
          },
        ],
      },
    ],
  },
}

Field	Values	Meaning
`memory_type`	`User`, `Project`, `Local`, `Managed`	Which scope the file came from
`load_reason`	`session_start`, `nested_traversal`, `path_glob_match`, `include`, `compact`	Why it was pulled in
`file_path`	path	The file that was loaded

nested_traversal and include are the two that surprise people: instruction files can pull in other files, so the effective prompt may be larger than the one file you wrote.

Adjust output style separately

Output style shapes how the agent presents results without touching its behavioral rules. It is a settings-level value, not a query option:

options: {
  settings: { outputStyle: 'concise' },
}

Read the active style and the available set from the session initialization message:

const init = await q.initializationResult();
console.log(init.output_style, init.available_output_styles);

Reach for output style when the complaint is "too verbose" or "wrong format". Reach for systemPrompt when the complaint is "did the wrong thing".

Next steps

Custom Tools — extend what the agent can do, not just how it behaves
Skills — package repeatable instructions the agent invokes by name
Subagents — give delegated tasks their own prompts and tool sets
Hooks — inspect and intercept the session at each lifecycle point

​Append to the preset

​Replace the prompt entirely

​Load the prompt from a file

​Load instructions from the filesystem

​Observe what actually loaded

​Adjust output style separately

​Next steps

Append to the preset

Replace the prompt entirely

Load the prompt from a file

Load instructions from the filesystem

Observe what actually loaded

Adjust output style separately

Next steps