Getting Started

Quickstart

Install Spineforge, register an agent, and trace your first run in under 5 minutes.

1. Install

pip install spineforge

Spineforge requires Python 3.9+. It installs the SDK and the OpenLLMetry instrumentation packages for supported frameworks.

2. (Optional) Set environment variables

Without any configuration, Spineforge runs in offline mode — no registry, local identity only. To connect to the Spineforge backend, set:

# .env
SPINEFORGE_REGISTRY_URL=https://spineforge-backend.onrender.com
SPINEFORGE_VERBOSE=true
SPINEFORGE_TRACE_CONTENT=true

In offline mode, identity is stored in .spineforge/registry.json and telemetry goes to .spineforge/logs/actions.jsonl. No data leaves your machine.

3. Init and run

import spineforge

# 1. Init — resolves or creates a Spine ID for this agent
spine = spineforge.init(agent_name="my-research-agent")

# 2. Wrap your top-level invocation in a run
with spine.run(input=user_query) as run:
    result = run_your_agent(user_query)
    run.set_output(result)

That's it. Spineforge auto-instruments LLM calls (LangChain, Groq, etc.) in the background via OpenTelemetry. No changes to your agent logic.

4. What you'll see

Console output (when SPINEFORGE_VERBOSE=true):

🦴 Spineforge initialised: agent='my-research-agent'  spine_id=a1b2c3d4…  log=.spineforge/logs/actions.jsonl
🦴 [SPINE:a1b2c3d4] RUN started  input="What is the capital of France?"
🦴 [SPINE:a1b2c3d4] [RUN:e5f6g7h8] ⚡ llm_call  gpt-4o  612ms ✓  (prompt:48 comp:12)
🦴 [SPINE:a1b2c3d4] [RUN:e5f6g7h8] RUN completed  847ms ✓

5. Instrument tool calls (if needed)

LangChain, LangGraph, CrewAI, and AutoGen tool calls are captured automatically. If you're using the raw OpenAI SDK and have custom tool functions, add one decorator:

from spineforge import track_tool

@track_tool
def call_vendor_api(endpoint: str, query: str) -> str:
    """Every call now has an identity + audit trail."""
    return requests.get(endpoint, params={"q": query}).text

@track_tool is only needed for raw SDK agents. LangChain-based agents don't need it — the LangChain instrumentor fires on on_tool_start / on_tool_end automatically.

6. Connect to the backend (optional)

When SPINEFORGE_REGISTRY_URL is set, init() does additional work:

  1. Generates or loads an Ed25519 keypair (.spineforge/agent_key.pem)
  2. Registers the public key with the backend — gets a server-assigned Spine ID
  3. Creates an APISink that sends telemetry to the backend with FileSink as fallback

From that point, the agent can call spine.lease_credential() and spine.request_token().

Full example

import spineforge

spine = spineforge.init(
    agent_name="research-agent",
    allowed_scopes=["telemetry:write", "credential:lease"],
)

user_query = "Summarise the latest developments in AI agent frameworks."

with spine.run(input=user_query) as run:
    # Lease a credential (requires registry URL)
    api_key = spine.lease_credential("openai-api-key")

    from openai import OpenAI
    client = OpenAI(api_key=api_key)

    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": user_query}]
    )

    result = response.choices[0].message.content
    run.set_output(result)

print("Done. Check .spineforge/logs/actions.jsonl for the full trace.")

Next steps