# How to Configure System Prompts for Needle Agent Behavior

> Configure system prompts for Needle agent behavior. Pass a system string to Needle to supply immutable context facts for resolving relative expressions like time and location.

- Repository: [Cactus Compute, Inc./needle](https://github.com/cactus-compute/needle)
- Tags: how-to-guide
- Published: 2026-08-20

---

**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`](https://github.com/cactus-compute/needle/blob/main/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

```python
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

```python
@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

```python
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:

```python

# 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:

```python

# 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`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py) — Constructor implementation accepting the `system` argument
- [`doc/apis.md`](https://github.com/cactus-compute/needle/blob/main/doc/apis.md) — Complete reference for supported system keys and formatting rules
- [`doc/finetuning.md`](https://github.com/cactus-compute/needle/blob/main/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.