@shennian/agent

Node.js/TypeScript SDK for the Shennian Agent Protocol.

Build AI agents that plug into the Shennian platform with a few lines of code.

Install

npm install @shennian/agent

Quick Start

import { Agent } from '@shennian/agent'

const agent = new Agent({
  name: 'My Agent',
  model: 'gpt-4o',
})

agent.onSend(async ({ text, sessionId }) => {
  agent.delta('Thinking...')
  // call your LLM here
  agent.delta('Here is the answer.')
  agent.final()
})

agent.run()

Modes

Spawn mode (default) — CLI starts a new process per user message:

echo "Hello" | my-agent /run --session abc --workdir /tmp

Stdio mode — long-running process, receives JSONL on stdin:

const agent = new Agent({
  name: 'My Agent',
  model: 'gpt-4o',
  mode: 'stdio',
  proactive: true,
})

Emitting Events

agent.delta('partial text')          // stream text to user
agent.delta('thinking...', true)     // thinking indicator
agent.toolCall('search', { q: 'x' }) // tool call
agent.toolResult('search', '42')     // tool result
agent.notify('Done!', 'Title')       // notification
agent.error('Something went wrong')  // error (ends run)
agent.final()                        // end run

Protocol

See PROTOCOL.md for the full specification.