从一次对话
到可追溯的工作流

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
nerya setup --web
nerya doctor
nerya run

Dashboard / Python SDK / HTTP client
                  ↓
           AgentKernel.run_turn
                  ↓
    WorkspaceNativeAgentLoop
       ↔ LLM gateway (messages + tools)
       ↔ Tool registry → permissions → tool execution
       ↔ Skill instructions / approved scripts
                  ↓
   blocks · tool_trace · events · artifacts
                  ↓
      Session transcript / Dashboard

from pathlib import Path
from nerya_sdk import connect

client = connect(workspace=str(Path.home() / ".nerya"))
catalog = client.agent.list_tools()
for tool in catalog.get("tools", []):
    print(tool["name"], tool["risk"], tool["read_only"])

from pathlib import Path
from nerya_sdk import connect

client = connect(workspace=str(Path.home() / ".nerya"))
# Reuse the same session ID for follow-up turns.
session_id = "sdk-research-example"
result = client.agent.run_turn(
    text="Inspect the available research workflow. Do not place orders.",
    session_id=session_id,
)
print(result.get("reply_text", ""))
for envelope in result.get("blocks", []):
    block = envelope.get("block", envelope)
    print(block.get("kind"))

# Run in the product repository (not landing-page).
npm install --prefix sdk/typescript
npm run build --prefix sdk/typescript
# In your consuming project, use the real local SDK path:
npm install /absolute/path/to/product/sdk/typescript

import { connect } from "@nerya/sdk";

const client = connect({
  baseUrl: "http://127.0.0.1:18317",
  timeoutMs: 120_000,
  caller: "script:research-example",
});

const catalog = await client.agent.tools();
console.log(catalog.tools.map(tool => tool.name));

// Executing this call invokes your configured runtime and model.
const result = await client.agent.runTurn({
  text: "Inspect the research workflow without placing orders.",
  session_id: "sdk-research-example",
});
console.log(result.reply_text);
console.log(result.tool_trace);

GET /agent/stream/events?session_id=sdk-research-example&after_seq=0&limit=100
GET /agent/session/transcript?session_id=sdk-research-example
POST /agent/interrupt
Content-Type: application/json

{"session_id":"sdk-research-example","reason":"operator_interrupt"}

my_research_skill/
├── SKILL.md        # Required: when to use, workflow, boundaries
├── references/     # Optional: methods, report templates, source rules
├── scripts/        # Optional: deterministic executable helpers
└── templates/      # Optional: reusable artifacts

from nerya_sdk import connect

client = connect()
# Illustrative observations, not live market data.
chart = {
    "kind": "chart",
    "chart_kind": "line",
    "title": "Example observations (illustrative)",
    "series": [{
        "type": "line", "name": "observed_value",
        "data": [
            {"time": 1704067200, "value": 100},
            {"time": 1704153600, "value": 102},
            {"time": 1704240000, "value": 101},
        ],
    }],
    "time": {"timezone": "UTC", "format": "unix_seconds"},
    "source": {
        "skill": "agent", "action": "example",
        "as_of": "2024-01-03T00:00:00Z",
    },
    "warnings": ["Illustrative data; not a backtest or live quote."],
}
result = client.charts.publish_and_announce(chart)
print(result["chart_id"])

Strategy candidate → Validation / backtest → Review
                         ↓
                    Paper execution
                         ↓
      Explicit live enablement + account capability
                         ↓
             Risk Gate → Approval policy
                         ↓
              Order result / reconciliation

from nerya_sdk import connect

client = connect()
preview = client.triggers.dry_run(
    source="script",
    kind="research.requested",
    payload={"question": "Review the available market evidence"},
    target="main",
    idempotency_key="research-example-001",
)
print(preview)

nerya --help
nerya doctor
nerya service status