# How to Integrate Prime-Agent with Other Tools: 3 Methods Explained

> Learn to integrate Prime-Agent with other tools using JSON event-stream mode, RPC mode, or the Node.js library for flexible automation and control. Explore the PrimeIntellect-ai/prime-agent repository.

- Repository: [Prime Intellect/prime-agent](https://github.com/PrimeIntellect-ai/prime-agent)
- Tags: how-to-guide
- Published: 2026-08-16

---

**Prime-Agent from PrimeIntellect-ai/prime-agent integrates with external tools through JSON event-stream mode, RPC mode, or the Node.js/TypeScript library, giving you lightweight automation, full-duplex programmatic control, or native in-process API access.**

Prime-Agent is an extensible AI coding agent that offers multiple integration paths for embedding its capabilities into your own applications, pipelines, and services. Whether you need quick shell scripting, real-time interactive control, or tight TypeScript integration, the same core engine powers all three approaches according to the PrimeIntellect-ai/prime-agent source code. This guide walks through each integration method with complete code examples and references to the actual implementation files.

## JSON Event-Stream Mode: Lightweight Line-Delimited Integration

The **JSON event-stream mode** is the simplest way to integrate Prime-Agent. Run the CLI with `--mode json` and every session event becomes a line-delimited JSON record on stdout. Commands are read from stdin using the same format.

This approach requires no libraries—just any tool that can pipe JSON lines. It excels in CI pipelines, shell scripts, and language-agnostic automation.

### Basic JSON Mode Usage

```bash

# Stream results and extract final assistant message

prime-agent --mode json "List all TypeScript files" \
  | jq -c 'select(.type=="message_end") | .message.content[]?.text'

```

The command passes the prompt directly on the command line. The `jq` filter selects only `message_end` events and extracts the text content.

### Sending Commands via Stdin

You can also feed JSON commands to trigger specific tools:

```bash
echo '{
  "type":"bash",
  "command":"git status"
}' | prime-agent --mode json --no-session

```

All event types—`agent_start`, `message_update`, `tool_execution_end`, and more—are documented in [`packages/coding-agent/docs/json.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/json.md) according to the PrimeIntellect-ai/prime-agent source code.

## RPC Mode: Full-Duplex Programmatic Control

For long-running services and interactive applications, **RPC mode** provides a full-duplex JSON Lines protocol over stdin/stdout. It supports commands with request/response correlation, real-time streaming of assistant messages, and a rich extension-UI sub-protocol for dialogs and confirmations.

### Starting RPC Mode

```bash
prime-agent --mode rpc --no-session

```

The client sends **command objects** (e.g., `prompt`, `bash`, `set_model`) with optional `id` fields for correlation. While processing, the agent streams **events** on stdout with the same shape as JSON mode, as defined in [`packages/coding-agent/docs/rpc.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/rpc.md).

### Python RPC Client Example

```python
import subprocess, json, sys

proc = subprocess.Popen(
    ["prime-agent", "--mode", "rpc", "--no-session"],
    stdin=subprocess.PIPE, stdout=subprocess.PIPE, text=True
)

def send(cmd):
    proc.stdin.write(json.dumps(cmd) + "\n")
    proc.stdin.flush()

def read_events():
    for line in proc.stdout:
        yield json.loads(line)

# Send a prompt

send({"type": "prompt", "message": "Explain the Fibonacci sequence"})

# Print streamed text deltas

for ev in read_events():
    if ev.get("type") == "message_update":
        delta = ev.get("assistantMessageEvent", {})
        if delta.get("type") == "text_delta":
            sys.stdout.write(delta["delta"])
            sys.stdout.flush()
    if ev.get("type") == "agent_end":
        print()
        break

```

This minimal client demonstrates prompt sending, streaming text extraction, and graceful termination detection.

### Node.js RPC Client with Stream-Safe Reader

```js
const { spawn } = require("child_process");
const { StringDecoder } = require("string_decoder");

const agent = spawn("prime-agent", ["--mode", "rpc", "--no-session"]);

function attachJsonlReader(stream, onLine) {
  const decoder = new StringDecoder("utf8");
  let buf = "";
  stream.on("data", chunk => {
    buf += typeof chunk === "string" ? chunk : decoder.write(chunk);
    while (true) {
      const i = buf.indexOf("\n");
      if (i === -1) break;
      let line = buf.slice(0, i);
      buf = buf.slice(i + 1);
      if (line.endsWith("\r")) line = line.slice(0, -1);
      onLine(line);
    }
  });
  stream.on("end", () => {
    buf += decoder.end();
    if (buf) onLine(buf.endsWith("\r") ? buf.slice(0, -1) : buf);
  });
}

// Print streamed text deltas
attachJsonlReader(agent.stdout, line => {
  const ev = JSON.parse(line);
  if (ev.type === "message_update" &&
      ev.assistantMessageEvent?.type === "text_delta") {
    process.stdout.write(ev.assistantMessageEvent.delta);
  }
});

// Send a prompt
agent.stdin.write(JSON.stringify({ type: "prompt", message: "List files" }) + "\n");

// Graceful abort on Ctrl-C
process.on("SIGINT", () => agent.stdin.write(JSON.stringify({ type: "abort" }) + "\n"));

```

The reference implementation in [`packages/coding-agent/src/modes/rpc/rpc-client.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/modes/rpc/rpc-client.ts) provides a fully typed RPC client for production use.

### Extension UI Protocol

RPC mode supports **extension UI requests** such as `select`, `confirm`, and custom dialogs. This allows your client to render native UI elements when the agent needs user input, as shown in [`examples/rpc-extension-ui.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/examples/rpc-extension-ui.ts).

## Node.js/TypeScript Library: Native In-Process Integration

For maximum performance and type safety, import the **`@earendil-works/pi-coding-agent`** package directly. This bypasses subprocess overhead and exposes the full `AgentSession` API.

### Installation and Basic Usage

```bash
npm install @earendil-works/pi-coding-agent

```

```ts
import { AgentSession } from "@earendil-works/pi-coding-agent";

async function run() {
  const session = new AgentSession({
    provider: "openai",
    modelId: "gpt-4o",
    // optional: custom session directory, tool configurations, etc.
  });

  const resp = await session.prompt("Write a one-line summary of this repo");
  console.log(resp.message.content.map(c => c.text).join(""));
}
run();

```

### Advanced Library Features

The `AgentSession` class in [`packages/coding-agent/src/core/agent-session.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/agent-session.ts) exposes methods unavailable through CLI modes:

- `session.setThinkingLevel(level)` — adjust reasoning depth
- `session.compact()` — trigger context compaction
- `session.addSchedule(task)` — register autonomous tasks

This direct access makes the library ideal for building native Node applications, VS Code extensions, or serverless functions where latency and type safety matter.

## Extending Prime-Agent with Custom Commands

Prime-Agent's **extension system** lets you register custom slash commands that work across all integration modes. Extensions are TypeScript files placed in `~/.prime/agent/extensions/` or project-local `./.prime/agent/extensions/`.

### Creating a Custom Extension

```ts
import { pi } from "pi";

pi.registerCommand({
  name: "uppercase",
  description: "Upper-case the given text",
  async handler(ctx, args) {
    const text = args[0] ?? "";
    ctx.sendMessage(text.toUpperCase());
  },
});

```

Save as [`my-extension.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/my-extension.ts), restart the agent, then invoke via any client:

```json
{ "type": "prompt", "message": "/uppercase hello world" }

```

Extensions automatically become available in JSON mode, RPC mode, and the interactive TUI, as documented in [`packages/coding-agent/docs/rpc.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/rpc.md).

## Skills and Packages for Tool Expansion

Beyond extensions, Prime-Agent supports **skills** (importable Python packages that add tool implementations) and **packages** (bundled npm modules). Install packages via:

```bash
prime-agent package install <source>

```

These can provide additional commands, tools, or UI components. The full package management workflow is documented in [`packages/coding-agent/docs/usage.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/usage.md).

## Architecture Overview

All three integration methods feed into the same pipeline, as illustrated in [`packages/coding-agent/docs/architecture.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/architecture.md):

```

CLI/JSON/RPC/Library → AgentConnection → Supervisor → Worker → AgentSessionRuntime (IPython kernel) → Model provider

```

This unified architecture ensures that **model selection**, **tool execution**, **sub-agent spawning**, **compaction**, and **autonomous mode** behave identically regardless of how you integrate.

## Summary

- **JSON event-stream mode** (`--mode json`) offers the fastest path to integration—pipe JSON lines for lightweight automation in any language
- **RPC mode** (`--mode rpc`) provides full-duplex control with streaming, request/response correlation, and extension UI support for interactive applications
- **Node.js/TypeScript library** (`@earendil-works/pi-coding-agent`) delivers native, type-safe API access with the lowest overhead
- **Extensions** registered via `pi.registerCommand()` work across all modes, enabling reusable custom functionality
- The architecture diagram in [`packages/coding-agent/docs/architecture.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/architecture.md) confirms all methods share the same core engine, ensuring consistent behavior

## Frequently Asked Questions

### Can I integrate Prime-Agent with Python applications?

**Yes.** While there's no native Python library, you can spawn the CLI in JSON or RPC mode and communicate via subprocess pipes. The Python RPC client example above demonstrates streaming text deltas with under 30 lines of code. For synchronous use cases, JSON mode with `subprocess.run()` and `jq`-style filtering suffices.

### How do I handle user prompts and confirmations in RPC mode?

**Implement the extension UI sub-protocol.** When the agent needs user input, it sends UI request events (e.g., `{"type":"select","options":[...]}`). Your client renders the appropriate interface, then sends the response back as a UI response command. See [`examples/rpc-extension-ui.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/examples/rpc-extension-ui.ts) for a complete implementation handling `select`, `confirm`, and custom input types.

### What's the performance difference between RPC mode and the Node.js library?

**The Node.js library eliminates subprocess overhead.** In RPC mode, every message serializes through stdin/stdout pipes, adding latency proportional to JSON encoding and OS buffer handling. The `AgentSession` class operates in-process with direct method calls, reducing latency by roughly 1-10ms per interaction depending on payload size. For high-frequency or latency-sensitive applications, prefer the library.

### Can I use Prime-Agent in CI/CD pipelines without interactive input?

**Absolutely.** JSON mode with `--no-session` is designed for this. Each invocation starts fresh, processes the provided prompt or command, streams results as JSON lines, and exits. Combine with tools like `jq` for filtering or `xargs` for batch processing. The deterministic, non-interactive behavior makes it ideal for automated testing, documentation generation, and code review workflows.