How to Provide System Facts to the Needle 2 Agent

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), 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). 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.

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).

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.

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:

# 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 (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.

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