Skip to main content

​
Overview

Every time the main agent is invoked, the runtime compiles a system prompt from up to 16 sections. Most sections are automatic — the runtime builds them from env state, loaded plugins, and live session data. You are only responsible for four fields in config.prompt. Everything else is handled for you.

​
The 16 sections

Sections appear in this fixed order. “Always present” means the section is included on every turn regardless of configuration; “conditional” means the section only appears when a specific condition is met.
#SectionPresent
1Oracle section — identity preambleAlways
2Capabilities note — config.prompt.capabilities textConditional
3Capability block — Tier-1 plugin manifest listConditional
4Operating principles — fixed bullets + optional communication styleAlways
5Custom instructions — config.prompt.customInstructions + loaded operating guidesConditional
6Working with files — file-handling guidanceAlways
7What you know about the user — memory context (6 slots)Conditional
8Current time — {currentTime} ({timezone})Always
9Current entity — {DID}Conditional
10Available user secretsConditional
11User preferencesConditional
12Operational mode — general (default) or editor variantsAlways
13Composio context — Composio tool contextConditional
14Editor section — editor plugin stateConditional
15Slack formatting constraints — Slack output rulesConditional
16Degraded services — failed-init noticesConditional

​
Section details

1. Oracle section The identity preamble. If config.prompt.opening is set, it is used verbatim. Otherwise the runtime generates a fallback from the other top-level fields: "You are {name}, an AI agent operated by {org}. {description}." (shorter variants when org or description are absent). See the createOracleApp config reference for the exact fallback logic. 2. Capabilities note Rendered if config.prompt.capabilities is non-empty. Appears immediately above the plugin capability block. No header is added by the runtime — include your own heading in the field value if you want one. 3. Capability block Auto-generated list of all loaded plugins with visibility='always' (Tier-1). Each entry is more than a one-liner: the plugin name and summary, then up to three sub-bullets pulled from the manifest — When to use: (first two whenToUse triggers), Avoid for: (first whenNotToUse), and Example: (the first examples entry). Manifest quality therefore drives prompt size. You never write this section; the runtime builds it from the loaded plugin set. See the 5,000-token capability-block budget below — it is a warn-only soft budget, not an auto-trim. 4. Operating principles Always present. Contains a fixed set of operating-principle bullets (currently nine) covering discovery-first tool use, clarifying questions, reporting results, surfacing failures, delegating with context, and completing-then-stopping. If config.prompt.communicationStyle is non-empty, it is injected here as an additional paragraph after those bullets. If communicationStyle is absent, the section still appears — just without the custom style block. 5. Custom instructions Conditional. Rendered as a ## Custom Instructions section when there is anything to put in it. Its body is your config.prompt.customInstructions field plus any operating guides contributed by on-demand capabilities the agent has loaded for this thread (e.g. the Flow Builder guide). When nothing contributes, the whole section is omitted and costs zero tokens. 6. Working with files Always present. Hardcoded guidance on how the agent should handle file uploads, attachments, and generated file output. 7. What you know about the user Conditional on the memory plugin being loaded and at least one context slot being populated. Contains up to 6 slots fetched by UserContextFetcher before the agent is compiled: identity, work, goals, interests, relationships, recent. See How memory reaches the prompt for the pre-fetch details. 8. Current time Always present. Stamped at agent-compile time with the user’s wall-clock time and resolved timezone. 9. Current entity Conditional on state.currentEntityDid being set in the agent state. Surfaces the active entity DID so the agent can route entity-aware tool calls correctly. 10. Available user secrets Conditional on the secrets service having entries for the current user. Lists secret names (not values) so the agent can reference them by name in tool calls. 11. User preferences Conditional on the user-preferences plugin being loaded and the user having saved preferences. May include agentName, language, tone, formality, and customInstructions. 12. Operational mode Always present, but content varies. The runtime ships a general default (DEFAULT_OPERATIONAL_MODE) and editor-mode variants supplied by the editor plugin. Any other mode arrives through hooks.operationalMode — a plugin or host override — not a built-in runtime selection. See Model resolution & hooks. 13. Composio context Conditional on the Composio plugin loading successfully. Auto-injected Composio account and connection context so the agent knows which third-party integrations are available for the current user. 14. Editor section Conditional on the editor plugin being active in the current session. Describes the active document, cursor position, and editor affordances. 15. Slack formatting constraints Conditional on the session client being Slack. Appends Slack-specific formatting rules to prevent the agent from using markdown that Slack does not render correctly (e.g. tables). 16. Degraded services Appended after the main prompt when one or more plugins fail their init. Lists the failed services and tells the agent not to attempt their tools for this turn.

​
The 5,000-token capability block budget

Section 3 (the Tier-1 capability block) is the only section with a token budget — and it is a warn-only soft budget, not a cap. If the combined manifest text of all visibility='always' plugins exceeds 5,000 tokens, the runtime logs a warning naming the largest manifests so you can decide what to mark on-demand. Nothing is trimmed automatically: the full block is always emitted with every always plugin in it. Degrading verbosity is an operator decision, not a runtime guess — so keep manifest text (summary, whenToUse, examples) concise to keep the block small.

​
What you actually need to write in config.ts

Only four things — all optional:
FieldWhat to writeWhat happens if you skip it
config.prompt.openingA paragraph describing the oracle’s identity, purpose, and domain expertise.Runtime generates a generic fallback from name, org, description.
config.prompt.communicationStyleOne or two paragraphs on tone, vocabulary, and response style.The operating-principles section appears without a custom style block.
config.prompt.capabilitiesA short section (with your own heading) listing what the oracle can do.The capability-notes section is omitted; only the auto-generated plugin list appears.
config.prompt.customInstructionsStanding guidance that should hold across every turn (house rules, escalation policy, domain constraints).The ## Custom Instructions section is omitted unless a loaded capability contributes a guide.
Time, memory, user preferences, Composio context, entity DID, secrets, editor state, Slack constraints, and degraded-service notices are all injected automatically. You do not need to mention them in config.ts, instruct the agent to fetch them, or account for them in your opening paragraph.
Because memory context is pre-fetched and already in the system prompt by turn 1, you do not need to write instructions like “recall the user’s context before responding” in config.prompt. The agent already has the user’s identity, goals, and recent history before it processes the first message.

​
Minimal config.ts example

// src/config.ts
import type { OracleConfig } from '@ixo/oracle-runtime';

export const config: OracleConfig = {
  name: 'Aria',
  org: 'Acme Climate',
  description: 'Carbon-project advisory oracle for portfolio managers.',
  prompt: {
    opening: `You are Aria, the carbon-project advisory oracle operated by Acme Climate.
You help portfolio managers track project status, assess compliance, and draft
stakeholder communications across Verra VCS, Gold Standard, and REDD+ frameworks.`,
    communicationStyle: `Be precise and data-driven. Lead with numbers and deadlines.
Use plain English — avoid jargon unless the user demonstrates familiarity.
When something is uncertain, say so explicitly.`,
    capabilities: `## What Aria can do
- Retrieve live project status and registry issuance data.
- Draft verification reports, CORSIA letters, and board summaries.
- Search and cite methodology documents from the oracle knowledge base.`,
    customInstructions: `Always cite the registry framework (Verra VCS, Gold Standard, REDD+)
behind any compliance claim. Never approve a credit issuance on the user's behalf —
draft it and ask them to confirm.`,
  },
};
Everything else in the 16-section prompt — plugin tools, current time, user memory, preferences, Composio context — is assembled by the runtime from the loaded plugins and session state.

createOracleApp config

Full reference for config.prompt fields and fallback logic.

Memory plugin

How UserContextFetcher pre-loads memory into section 6.

Visibility tiers

What controls which plugins appear in the capability block.

Plugin anatomy

How plugins declare the manifest text that feeds section 3.