How to Configure System Prompts for Needle Agent Behavior

Pass a system string when constructing a Needle instance to supply immutable context facts that the model uses to resolve relative expressions like time and location.

Needle agents rely on system facts—declarative statements about the execution environment—to ground the model's interpretation of user queries. Unlike instructions, these facts provide static context that the model references when resolving ambiguous references. This guide explains how to configure system prompts in the cactus-compute/needle library, including supported keys, proper formatting, and practical code patterns.

Understanding System Facts vs. Instructions

System prompts in Needle serve a specific architectural purpose. They are declarative, not imperative—meaning they state facts about the environment rather than telling the model what to do.

According to the needle source code, anything placed in the system prompt that is not a recognized key is ignored. No hidden instructions execute, and no behavioral steering occurs. This design keeps agent operation deterministic and safe.

The model only uses system facts to resolve relative expressions into absolute values when the relevant fact is provided. Without a date fact, "tomorrow at 7" remains a verbatim string.

Supported System Fact Keys

The Needle engine recognizes the following keys in system prompts:

Key	Purpose	Example Value
date	Current date and time	2026-07-21 Tue 14:30
locale	Language and region	en-US, fr-FR
device	Device category	phone, laptop, desktop
battery	Battery charge level	62%
network	Connectivity status	wifi, cellular, offline
location	Physical or logical location	NYC, Berlin
user	End-user identifier	user_12345
assistant	AI assistant identity	HomeAgent

Only these keys are interpreted. Arbitrary text has no effect on model behavior.

Constructing a Needle Agent with System Facts

In needle/__init__.py, the Needle class constructor accepts a system argument. This argument is forwarded to the inference engine and remains immutable for the agent's lifetime.

Basic Configuration

import needle

@needle.tool
def set_thermostat(temp: int, mode: str = "auto"):
    """Set the thermostat to a target temperature."""
    return {"temperature": temp, "mode": mode}

agent = needle.Needle(
    tools=[set_thermostat],
    system="date: 2026-07-21 Tue 14:30; locale: en-US; device: phone; battery: 62%"
)

# The model resolves "tomorrow morning" using the provided date

response = agent.run("Set the thermostat to 21°C tomorrow morning")
print(response["results"])

Location-Aware Queries

@needle.tool
def get_weather(lat: float, lon: float, date: str):
    """Fetch weather forecast for coordinates."""
    return {"forecast": "sunny", "temp": 24}

agent = needle.Needle(
    tools=[get_weather],
    system="location: Berlin; date: 2026-08-20 Sat 12:00"
)

# "tomorrow" resolves to 2026-08-21 based on system date

agent.run("What's the weather tomorrow?")

Multi-Fact Configuration

agent = needle.Needle(
    tools=[email_tool, calendar_tool],
    system=(
        "date: 2026-08-20 Sat 12:00; locale: en-US; "
        "device: laptop; battery: 85%; network: wifi"
    )
)

Key Constraints and Behaviors

Immutability

The system prompt cannot be changed after constructing a Needle instance. To use different facts, create a new agent:

# This pattern is required for dynamic context

morning_agent = needle.Needle(tools=tools, system="date: 2026-08-20 Sat 08:00")
evening_agent = needle.Needle(tools=tools, system="date: 2026-08-20 Sat 20:00")

Graceful Degradation

When system facts are omitted, the model falls back to literal interpretation:

Query	With date fact	Without date fact
"tomorrow at 7"	Resolved to absolute timestamp	Passed as string "tomorrow at 7"
"next Tuesday"	Calculated from current date	Passed verbatim to tools

No Instruction Injection

Attempting to add instructions to the system prompt has no effect:

# This does NOT make the agent more polite

system="date: 2026-01-01; Be helpful and friendly"  # "Be helpful..." is ignored

# Only recognized keys are processed

system="date: 2026-01-01; locale: en-US"  # Valid configuration

Reference Documentation

The cactus-compute/needle repository provides authoritative documentation for system prompt configuration:

• needle/__init__.py — Constructor implementation accepting the system argument
• doc/apis.md — Complete reference for supported system keys and formatting rules
• doc/finetuning.md — Guidance on including system facts in training data (optional)

Summary

• System prompts in Needle are immutable facts, not instructions.
• Pass the system argument to needle.Needle() using semicolon-separated key-value pairs.
• Recognized keys: date, locale, device, battery, network, location, user, assistant.
• Facts enable relative expression resolution; missing facts result in verbatim string passing.
• Arbitrary text in system prompts is silently ignored—no security risk from injection, but also no behavioral modification.

Frequently Asked Questions

Can I update the system prompt after creating a Needle agent?

No. The system prompt is immutable for the life of the agent. According to the needle implementation, you must construct a new Needle instance with updated facts. This design ensures deterministic behavior within a single session.

What happens if I include custom keys or instructions in the system prompt?

Unrecognized keys and freeform text are ignored by the model. The engine parses only the eight documented keys. This prevents prompt injection attacks but also means you cannot use system prompts to modify agent personality or capabilities.

How should I format the date value in system facts?

Use the format YYYY-MM-DD Ddd HH:MM where Ddd is the three-letter day abbreviation. Example: 2026-07-21 Tue 14:30. The engine uses this for time arithmetic when resolving relative expressions like "tomorrow" or "next week."

Can I use system prompts without any date for stateless operations?

Yes. System facts are optional. An agent with no system argument, or with only non-date facts, operates without temporal grounding. Time-related queries pass through as literal strings to your tools, which may implement their own resolution logic.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}