Guides / Integrations

Integrations

Live Neon is not your agent runtime. It is the identity layer that your runtime consumes. That distinction is the key to integrating it well.

The clean architecture

Your framework should own:

  • Tool execution
  • Task planning
  • Orchestration
  • UI
  • Session management

Live Neon should own:

  • Identity structure
  • Inheritance
  • Prompt generation
  • Provenance
  • Behavioral discovery
  • Identity evolution over time

That split keeps your stack modular.

Four integration patterns

1. Stable prompt generation

Use Live Neon to periodically compile a prompt snapshot and ship that into your runtime. Best when you want predictability, you release prompt changes intentionally, and you have a review step before rollout. This is the safest pattern for teams starting out.

GET /api/v1/agents/{agentId}/resolved-identity
POST /api/v1/agents/{agentId}/regenerate-prompt

2. Dynamic identity injection

Use Live Neon to generate the current identity close to runtime. Best when the agent evolves frequently, you want changes to flow through faster, and you already have good governance and observability. Pair it with snapshots and diff review so identity changes do not feel mysterious in production.

POST /api/v1/agents/{agentId}/dynamic-prompt

3. Identity file bridge

If your stack already uses a file like SOUL.md or similar identity files, treat Live Neon as the system that helps keep that file honest. Start with a hand-written identity file, seed the non-negotiables manually, learn from real sources, compare learned identity against the static file, and regenerate the file from the evidence-backed model.

This is the practical bridge from static identity to living identity. It is also one of the strongest adoption paths because many agent builders already understand the value of a persistent identity file.

4. Closed-loop pattern

Consume identity from Live Neon, run the agent in your runtime, then send behavior back as conversations or content so the platform can evolve the identity. Use this when you want real learning loops and audit trails for why the prompt changed.

POST /api/v1/conversations
POST /api/v1/conversations/{sessionId}/messages
POST /api/v1/conversations/{sessionId}/publish
POST /api/v1/pbd/process

Recommended default architecture

Live Neon stores identity
        |
Your app fetches compiled prompt
        |
Framework runs the task
        |
Important sessions are published back to Live Neon
        |
PBD proposes identity updates
        |
Humans approve what becomes durable

That keeps the runtime simple while preserving evolution.

Getting started

Every integration follows the same pattern:

  1. Create an API key in your organization's Settings page.
  2. Fetch the agent's resolved identity or system prompt via the API.
  3. Pass the system prompt to your LLM of choice.

Fetch the system prompt

The simplest integration: fetch the generated system prompt and use it directly.

curl https://persona.liveneon.ai/api/v1/agents/{agentId} \
  -H "Authorization: Bearer ln_your_key"

# Response includes:
# { "system_prompt": "You are...", ... }

The system_prompt field contains the full merged identity (org + group + agent layers) formatted as markdown. It regenerates automatically when beliefs or responsibilities change.

Dynamic prompt

To combat persona numbing (LLMs habituating to static prompts), use the dynamic prompt endpoint:

GET /api/v1/agents/{agentId}/dynamic-prompt

This returns a randomized variant of the system prompt on each call. Starred beliefs are always included. Non-starred items are sampled based on configurable rates per category. Enable dynamic prompts in the agent or org settings before using this endpoint.

Change detection and safety

Useful endpoints for production refresh logic:

  • GET /agents/{agentId}/diff?since=...
  • POST /agents/{agentId}/snapshots

These help you answer: what changed? Should we refresh the runtime prompt? Did this release materially alter identity?

Claude / Anthropic SDK

import Anthropic from "@anthropic-ai/sdk";

// Fetch identity from Live Neon
const res = await fetch(
  "https://persona.liveneon.ai/api/v1/agents/{agentId}",
  { headers: { Authorization: "Bearer ln_your_key" } }
);
const agent = await res.json();

// Use with Claude
const anthropic = new Anthropic();
const message = await anthropic.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  system: agent.system_prompt,
  messages: [{ role: "user", content: "Hello" }],
});

OpenAI / GPT

import OpenAI from "openai";

// Fetch identity from Live Neon
const res = await fetch(
  "https://persona.liveneon.ai/api/v1/agents/{agentId}",
  { headers: { Authorization: "Bearer ln_your_key" } }
);
const agent = await res.json();

// Use with GPT
const openai = new OpenAI();
const completion = await openai.chat.completions.create({
  model: "gpt-4o",
  messages: [
    { role: "system", content: agent.system_prompt },
    { role: "user", content: "Hello" },
  ],
});

LangChain

LangChain is a good fit when you want custom tool orchestration and explicit prompt control. Use Live Neon for stable identity. Use LangChain middleware for task- or user-specific runtime context.

from langchain_anthropic import ChatAnthropic
from langchain_core.messages import SystemMessage, HumanMessage
import requests

# Fetch identity from Live Neon
res = requests.get(
    "https://persona.liveneon.ai/api/v1/agents/{agentId}",
    headers={"Authorization": "Bearer ln_your_key"}
)
agent = res.json()

# Use with LangChain
llm = ChatAnthropic(model="claude-sonnet-4-6")
messages = [
    SystemMessage(content=agent["system_prompt"]),
    HumanMessage(content="Hello"),
]
response = llm.invoke(messages)

CrewAI

CrewAI is a good fit when you are modeling teams of agents with explicit roles and collaboration. Use Live Neon as the source of durable identity. Map that identity into CrewAI's role, goal, backstory, or custom prompt layer carefully. Then inspect the effective prompt, not just the code you wrote.

Note: CrewAI automatically injects additional system instructions based on agent configuration, especially around format and tool use. Do not assume the final runtime prompt is only your backstory text.

from crewai import Agent
import requests

# Fetch identity from Live Neon
res = requests.get(
    "https://persona.liveneon.ai/api/v1/agents/{agentId}",
    headers={"Authorization": "Bearer ln_your_key"}
)
agent_data = res.json()

# Create CrewAI agent with Live Neon identity
agent = Agent(
    role=agent_data.get("job_title", "Assistant"),
    goal=agent_data.get("description", ""),
    backstory=agent_data["system_prompt"],
    verbose=True,
)

Claude Code and coding agents

For Claude Code projects, you can fetch an agent's system prompt and include it in your CLAUDE.md file to give Claude Code a persistent identity across sessions. The same pattern works for any coding agent that loads identity from a file at startup.

Use Live Neon for role identity, voice and boundaries, and responsibility framing. Keep runtime instructions focused on the current task, repo context, tool safety, and output format. Do not let task instructions swallow identity, and do not let identity swallow task instructions.

# Fetch and save to CLAUDE.md
curl -s https://persona.liveneon.ai/api/v1/agents/{agentId} \
  -H "Authorization: Bearer ln_your_key" \
  | jq -r '.system_prompt' > CLAUDE.md

Split-stack learning

If you are running coding agents or semi-autonomous systems, you may also be using failure-memory or self-improving tools. These solve a different problem than Live Neon, and they pair well together.

Identity learning (Live Neon) answers: who is this agent becoming? What values, boundaries, and tendencies keep recurring? What responsibilities does it actually own?

Failure learning (external tools) answers: what went wrong? What should not happen again? What constraint should we enforce now?

A good split looks like this:

  • Live Neon owns: beliefs, responsibilities, voice, boundaries, provenance, identity evolution
  • Failure-memory layer owns: mistake logs, constraint generation, tool gotchas, runtime guardrails, self-healing operational rules

The combined result: your agent becomes more consistent in who it is and less likely to repeat known failures. That is a far better system than either identity-only or constraint-only learning.

File-based agent ecosystems

If your stack already uses persistent identity files, Live Neon fits naturally. Use Live Neon to learn and govern identity, compile that identity into a file-based artifact or prompt, and keep separate files for workflows, tools, and failure learnings if your stack already uses them.

File-based agents already have a strong mental model for persistent identity, startup-time loading, human-readable steering, and editability. Live Neon adds the missing piece: evidence-backed identity evolution.

Custom runtimes

You do not need a named framework to integrate Live Neon well. A custom runtime only needs three capabilities:

  1. Fetch identity or prompt from Live Neon
  2. Pass it into the model as the highest-authority instruction layer
  3. Send meaningful outputs back for future learning

That can be a serverless endpoint, a Next.js route, a worker queue, or a CLI harness.

Prompt refresh strategy

Do not fetch and recompile identity on every single token unless you need that level of freshness. A better default is:

  • Fetch on session start
  • Refresh after approved identity changes
  • Refresh on deploys to production or staging
  • Optionally fetch dynamic prompts per new conversation

Environment-aware integrations

Live Neon has first-class environments and model assignments. Use them if you want different deployment behavior for staging, production, internal testing, or sandbox agents.

A strong production pattern is:

  • One identity model
  • Multiple deployment environments
  • Different model assignments per environment
  • The same approval workflow across all of them

Governance recommendations

  • Do not auto-inject everything discovered into production. Approval exists for a reason. Use pending to approved as a real editorial step unless you explicitly want auto-approval behavior.
  • Snapshot before major imports. Especially before bootstrap recommendations, bulk belief creation, major source additions, or org-wide consensus actions.
  • Use diffs for deployment confidence. If an identity changed, treat that like a prompt-relevant deploy artifact.
  • Separate runtime telemetry from identity evidence. Not every runtime trace deserves to become identity. Publish the interactions that are actually representative.

Agent discovery

Live Neon publishes a machine-readable agent card for automated discovery:

GET /.well-known/agent-card.json

The OpenAPI spec is also available for tool-using agents:

GET /openapi.json

And a plain-text summary optimized for LLM consumption:

GET /llms.txt

Rate limits

API requests are rate-limited per API key:

  • General: 200 requests/minute
  • Heavy operations (sync, PBD): 30 requests/minute
  • Bulk operations: 10 requests/minute

429 responses include Retry-After and X-RateLimit-* headers.

Next reads