# How to Provide System Facts to the Needle 2 Agent

> Learn how to provide system facts to the Needle 2 agent. Inject contextual data like date locale and device state into generation steps using the system parameter.

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

---

**Pass a formatted environment string to the `system` parameter when initializing `needle.Needle` to inject contextual data like date, locale, and device state into every generation step.**

Needle 2, the lightweight agent runtime maintained in the `cactus-compute/needle` repository, supports a dedicated *system turn* for describing the external world. Learning how to provide system facts to the Needle 2 agent unlocks time-aware reasoning, locale-specific responses, and device-state reactions without polluting user prompts. This article breaks down the implementation in the Python bindings and demonstrates authoritative usage patterns drawn from the source.

## Understanding System Facts in Needle 2

### What Are System Facts?

System facts are immutable state descriptors formatted as a semicolon-delimited string. Unlike system instructions or role prompts, these values represent objective environmental conditions—current timestamps, battery levels, or network status—that the model may reference when interpreting ambiguous user requests.

According to the implementation in [[`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py)](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py), the constructor stores this string as UTF-8 bytes in `self._system` and forwards it to the native C engine during initialization (around line 55). The engine then makes these facts available to the model at every generation step.

### Supported Fact Keys

The native engine recognizes a fixed vocabulary of keys documented in [[`doc/apis.md`](https://github.com/cactus-compute/needle/blob/main/doc/apis.md)](https://github.com/cactus-compute/needle/blob/main/doc/apis.md). Only these identifiers trigger specialized behavior:

- **date** – Current date-time string used for absolute-time resolution
- **locale** – Language/region code (e.g., `en-US`, `ja-JP`)
- **device** – Hardware category (`phone`, `laptop`, `desktop`, etc.)
- **battery** – Remaining charge as a percentage
- **network** – Connectivity type or status
- **location** – Approximate geographic coordinates or region
- **user** – Anonymized identifier for the end-user
- **assistant** – The persona or identity the model should adopt

## Implementing System Facts in Your Agent

### Basic Constructor Usage

To provide system facts, instantiate the `Needle` class with the `system` argument. The string should follow the pattern `key: value; key: value` without additional commentary.

```python
import needle

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

```

The constructor validates and encodes this value before it reaches the inference engine downloaded via [[`needle/agent/fetch.py`](https://github.com/cactus-compute/needle/blob/main/needle/agent/fetch.py)](https://github.com/cactus-compute/needle/blob/main/needle/agent/fetch.py).

### Runtime Impact on Model Behavior

When system facts are present, the model uses them to ground relative references. For example, the phrase "tomorrow at 7" resolves to an absolute timestamp **only** if a `date:` fact exists in the system turn; otherwise, the text remains untouched. This deterministic behavior ensures that time-sensitive tool calls receive precise parameters without requiring the application layer to rewrite user queries.

## Complete Working Example

Below is a runnable implementation that declares a lighting-control tool, initializes the agent with comprehensive system facts, and processes a time-relative request.

```python
import needle

# 1️⃣ Declare a simple tool

@needle.tool
def set_lights(room: str, on: bool, brightness: int = 100):
    """Control a room's lights."""
    return {"room": room, "on": on, "brightness": brightness}

# 2️⃣ Create an agent with system facts

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

# 3️⃣ Run a query that relies on the supplied facts

result = agent.run("Turn the living-room lights on at 7 pm tomorrow")
print(result)   # → {"room": "living-room", "on": True, "brightness": 100}

```

For applications requiring manual step-through, drive the loop explicitly:

```python

# Driving the loop manually (useful for custom pipelines)

response = agent.complete("Dim the bedroom to 30%")
if response["type"] == "call":
    args = response["function_calls"][0]["arguments"]
    tool_result = set_lights(**args)
    
    # Feed the result back so the model can continue

    response = agent.complete(str(tool_result))
print(response)

```

## Summary

- **Provide system facts** by passing a semicolon-delimited string to the `system` argument in `needle.Needle()`.
- **Store facts as state**, not instructions—these describe the environment rather than directing model behavior.
- **Reference keys precisely**: `date`, `locale`, `device`, `battery`, `network`, `location`, `user`, and `assistant` are the only interpreted fields.
- **Enable absolute-time resolution** by including a `date` fact, which allows the engine to convert relative expressions like "tomorrow" into concrete timestamps.
- **Trace the data flow** from [`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py) (Python constructor) through `self._system` to the native C library.

## Frequently Asked Questions

### Can I add custom keys to the system string?

No. The native engine only recognizes the eight standard keys (`date`, `locale`, `device`, `battery`, `network`, `location`, `user`, `assistant`). Arbitrary keys are ignored during inference, though they will still be stored in `self._system`. For custom metadata, use the tool schema or application-layer logic rather than the system turn.

### What happens if I omit the `system` argument?

The agent operates without environmental context. The `_system` attribute defaults to an empty state, and the model treats all references as relative to its training data cutoff. Time expressions remain ungrounded, and device-specific optimizations are unavailable, though basic tool calling still functions normally.

### How should I format the date value for maximum compatibility?

Use a human-readable format that includes the full year, abbreviated month, day, and 24-hour time, such as `2026-07-21 Tue 14:30`. The engine parses this during tokenization to calculate offsets for phrases like "in two hours" or "next Monday." Avoid Unix timestamps or ambiguous formats like `07/21/26` to ensure consistent resolution.