How to Pass System Facts (Date and Locale) to the Needle Agent

The Needle agent receives system facts like the current date and locale through a built-in system_facts tool registered via the @tool decorator in needle/agent/tools.py, which automatically exposes these values to the LLM runtime without manual wiring.

The Needle framework from cactus-compute/needle provides a streamlined way to inject real-time system context into LLM-driven workflows. By leveraging the automatic tool registration system, developers can pass critical environmental data—such as timestamps and localization settings—directly to the agent's context payload with minimal configuration.

Built-in System Facts Tool

The core functionality resides in needle/agent/tools.py, where the system_facts function is defined and decorated with @tool. This decorator registers the function's JSON schema with the agent runtime, making it discoverable by the LLM during prompt processing.

How system_facts Works

When invoked, the function gathers system data using Python's standard library:

• datetime.datetime.now(tz=datetime.timezone.utc).isoformat() generates an ISO-8601 timestamp
• locale.getdefaultlocale() or locale.getlocale() retrieves the active system locale string

The function returns a dictionary structured as:

{
    "date": "2026-08-22T14:35:12+00:00",
    "locale": "en_US"
}

Because the @tool decorator handles schema registration, the agent automatically understands the function signature (def system_facts() -> dict) and can invoke it when context is required.

Using System Facts in Agent Workflows

Implicit Tool Invocation

The most common pattern involves letting the LLM decide when to fetch system facts. When you initialize a Needle agent and submit a prompt requiring temporal or regional context, the runtime automatically selects the system_facts tool:

from needle import Needle

agent = Needle(model="gpt-4o-mini")

response = agent.run(
    "Give me a short report that includes the current date and formats the heading "
    "according to the system locale."
)

print(response)

The internal flow follows four steps:

1. Prompt parsing – the LLM identifies requirements for "date" and "locale"
2. Tool selection – the runtime matches the request to system_facts in needle/agent/tools.py
3. Execution – the function fetches live system data
4. Response generation – the agent merges the returned dictionary into the final context

Direct Tool Access

You can also invoke the tool manually for debugging or custom preprocessing:

from needle.agent.tools import system_facts

info = system_facts()
print(f"Today's date: {info['date']}")
print(f"System locale: {info['locale']}")

Customizing System Facts

Creating Custom Wrappers

For scenarios requiring specific timezones or non-default locales, extend the pattern by creating your own decorated function. The agent will expose this alongside the built-in tool:

from needle.agent.tools import tool
import datetime
import locale

@tool
def custom_system_facts(tz: str = "UTC", loc: str = "fr_FR") -> dict:
    """Return date and locale, optionally overriding defaults."""
    now = datetime.datetime.now(datetime.timezone.utc).astimezone(
        datetime.timezone(datetime.timedelta(hours=int(tz)))
    )
    locale.setlocale(locale.LC_ALL, loc)
    return {"date": now.isoformat(), "locale": locale.getlocale()[0]}

This approach allows you to pass custom system information to the agent while maintaining the same automatic discovery mechanism used by the default implementation.

Summary

• The system_facts tool in needle/agent/tools.py automatically exposes date and locale data via the @tool decorator
• System facts are retrieved using standard library modules datetime and locale, returning ISO-8601 timestamps and locale strings
• The agent runtime in needle/agent/__init__.py handles tool discovery and invocation without manual registration
• You can override default behavior by creating custom functions decorated with @tool and passing specific timezone or locale parameters

Frequently Asked Questions

How does the Needle agent discover the system_facts tool?

The agent discovers the tool through the @tool decorator defined in needle/agent/tools.py. During initialization in needle/agent/__init__.py, the runtime scans for decorated functions and registers their JSON schemas, making them available for LLM tool selection without explicit configuration.

Can I override the default timezone or locale?

Yes. While the built-in system_facts uses UTC and the system default locale, you can create a custom function decorated with @tool that accepts tz and loc parameters. This custom tool will be automatically exposed to the agent alongside the default implementation.

What format does the date field return?

The date field returns an ISO-8601 formatted string generated by datetime.datetime.now(tz=datetime.timezone.utc).isoformat(), including timezone offset (e.g., 2026-08-22T14:35:12+00:00).

Where is the tool registration handled?

Tool registration occurs in needle/agent/tools.py where the @tool decorator is defined and applied to system_facts. The agent bootstrap process in needle/agent/__init__.py loads these registered tools into the runtime context, while needle/cli.py serves as the entry point for command-line invocation.

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