# How to Integrate PrimeAgent with Other Applications: A Complete Integration Guide

> Easily integrate PrimeAgent with other applications using CLI JSON RPC Node.js SDK MCP skill packages and sub-agent orchestration Embed PrimeAgent in scripts services and multi language pipelines

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

---

**PrimeAgent integrates with external applications through four architectural layers—CLI/JSON/RPC interfaces, the Node.js SDK, MCP skill packages, and sub-agent orchestration—enabling embedding in scripts, services, and multi-language pipelines.**

PrimeAgent is built as a modular, extensible platform that separates concerns across clear interface boundaries. Whether you need to drive it from a shell script, embed it in a Node.js backend, or extend it with custom third-party integrations, the codebase provides purpose-built mechanisms for each scenario. This guide covers the four primary integration patterns with concrete implementations drawn from the PrimeIntellect-ai/prime-agent repository.

## CLI, JSON, and RPC Interface Modes

The `prime-agent` command supports three runtime modes that trade interactivity for automation. These are implemented in [`packages/coding-agent/src/cli/cli.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/cli/cli.ts) with mode-specific handlers in [`packages/coding-agent/src/modes/headless-completion.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/modes/headless-completion.ts).

| Mode | Flag | Use Case |
|------|------|----------|
| **Interactive** | (default) | Terminal UI with rich formatting |
| **JSON** | `--mode json` | Streaming JSON events for parsing |
| **RPC** | `--mode rpc` | Newline-delimited JSON on stdin/stdout |

**JSON mode** emits structured events that scripts can parse. **RPC mode** provides a pure request-response protocol suitable for subprocess communication.

Example: Bash script using JSON mode:

```bash
#!/usr/bin/env bash
prime-agent --mode json <<'EOF' | jq -r '.output'
Write a one-sentence summary of the file ./README.md.
EOF

```

## Node.js SDK and Programmatic API

For backend services or Node.js applications, the SDK in [`packages/coding-agent/src/core/sdk.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/sdk.ts) exposes the **`AgentSession`** class. This handles session lifecycle, model selection, and daemon communication without requiring shell invocation.

Key capabilities:

- `AgentSession.create(options)` — Initialize with model and mode configuration
- `session.runPrompt(prompt)` — Execute a prompt and receive structured output
- `session.exec(command)` — Run shell commands through the agent
- `session.shutdown()` — Cleanly terminate the daemon

Example: SDK usage in a Node.js service:

```typescript
import { AgentSession } from "prime-agent-coding-agent";

async function main() {
  const session = await AgentSession.create({
    model: "gpt-4o-mini",
    mode: "json",
  });

  const { output } = await session.runPrompt(`
    Write a short Python function that returns the Fibonacci number for a given n.
  `);

  console.log("Generated code:", output);
  await session.shutdown();
}

main();

```

## MCP Integrations and Custom Skill Packages

PrimeAgent's **MCP (Model-Context-Protocol)** framework enables integrations with external services like Linear and Notion. These are standard Python packages that implement the `McpIntegration` API, defined in [`packages/coding-agent/docs/mcp-integrations.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/mcp-integrations.md).

To add a custom integration:

1. Create a Python package under `skills/`
2. Subclass `McpIntegration` and decorate methods with `@tool`
3. Register the skill in [`packages/coding-agent/src/core/skills.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/skills.ts)
4. Enable via `/login` → **MCP Connections**

Example: Custom MCP integration:

```python

# my_integration/__init__.py

from prime_agent.mcp import McpIntegration, tool

class MyService(McpIntegration):
    @tool
    async def get_status(self):
        """Return a JSON status object from the external service."""
        return {"healthy": True, "load": 0.42}

```

Once registered, the model can invoke `integration.my_service.get_status()` directly during sessions.

## Sub-Agent Orchestration with RLM Runtime

The **`rlm`** built-in tool enables one PrimeAgent instance to spawn and coordinate child agents. Implemented in [`packages/coding-agent/src/core/rlm-runtime.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/rlm-runtime.ts), this supports parallel execution pipelines and specialized agent delegation.

Use `rlm(...)` from within a running session to:

- Spawn isolated child agents with independent context
- Execute tasks in parallel and aggregate results
- Build hierarchical agent systems with parent-child relationships

This pattern is essential for workloads requiring concurrent processing or domain-specific sub-agents.

## Integration Patterns Summary

| Pattern | Mechanism | Best For |
|---------|-----------|----------|
| **Shell/CI automation** | `--mode json` with stdout parsing | Automated pipelines, test harnesses, CI/CD |
| **Node.js service** | Import SDK, create `AgentSession` | Backend APIs, persistent services |
| **Custom external API** | Python `McpIntegration` skill package | Proprietary or domain-specific integrations |
| **Cross-language embedding** | `--mode rpc` with stdin/stdout JSON | Go, Rust, Python, or other runtimes |
| **Hierarchical orchestration** | Built-in `rlm` tool | Parallel workloads, specialized agent teams |

## RPC Subprocess from Other Languages

The RPC mode accepts newline-delimited JSON messages, making PrimeAgent embeddable from any language with process control.

Example: Go integration:

```go
cmd := exec.Command("prime-agent", "--mode", "rpc")
stdin, _ := cmd.StdinPipe()
stdout, _ := cmd.StdoutPipe()
cmd.Start()

fmt.Fprintln(stdin, `{"type":"prompt","prompt":"What is the current date?"}`)

var resp map[string]interface{}
json.NewDecoder(stdout).Decode(&resp)
fmt.Println("Answer:", resp["output"])

```

## Key Source Files

| Component | Path |
|-----------|------|
| CLI entry and argument parsing | [`packages/coding-agent/src/cli/cli.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/cli/cli.ts) |
| JSON/RPC mode implementations | [`packages/coding-agent/src/modes/headless-completion.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/modes/headless-completion.ts) |
| SDK and `AgentSession` | [`packages/coding-agent/src/core/sdk.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/sdk.ts) |
| Sub-agent runtime (`rlm`) | [`packages/coding-agent/src/core/rlm-runtime.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/rlm-runtime.ts) |
| MCP integration guide | [`packages/coding-agent/docs/mcp-integrations.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/mcp-integrations.md) |
| Skill discovery and loading | [`packages/coding-agent/src/core/skills.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/skills.ts) |
| Daemon lifecycle control | [`packages/coding-agent/src/cli/daemon-command.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/cli/daemon-command.ts) |

## Summary

- **Four integration layers** provide options for every automation need: CLI modes for scripts, SDK for Node.js services, MCP for custom APIs, and RLM for agent orchestration.
- **`--mode json`** and **`--mode rpc`** convert PrimeAgent into a composable Unix-style tool.
- **`AgentSession`** in the SDK abstracts daemon management for programmatic use.
- **`McpIntegration`** Python classes extend PrimeAgent to any HTTP or API-based service.
- **`rlm`** enables PrimeAgent-to-PrimeAgent communication for complex, parallel workflows.

## Frequently Asked Questions

### How do I run PrimeAgent without the interactive terminal UI?

Use **`--mode json`** for streaming JSON events or **`--mode rpc`** for request-response communication. Both are implemented in [`packages/coding-agent/src/modes/headless-completion.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/modes/headless-completion.ts) and disable the TUI completely.

### Can I use PrimeAgent from Python or Go instead of Node.js?

Yes. Start PrimeAgent with `--mode rpc` and communicate via newline-delimited JSON on stdin/stdout. The `rlm` runtime in [`packages/coding-agent/src/core/rlm-runtime.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/rlm-runtime.ts) demonstrates this same protocol for sub-agent communication.

### What is the difference between SDK `runPrompt()` and CLI JSON mode?

`runPrompt()` via the SDK maintains a persistent daemon connection and session state, while CLI JSON mode spins up a fresh process per invocation. Use the SDK for latency-sensitive services; use CLI JSON mode for stateless, fire-and-forget automation.

### How do I add a custom integration for my company's internal API?

Create a Python package with a class extending `McpIntegration`, implement tools with the `@tool` decorator, and place it under `skills/`. Register it in [`packages/coding-agent/src/core/skills.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/skills.ts) and enable through the MCP Connections UI.