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

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 with mode-specific handlers in 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:

#!/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 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:

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.

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
4. Enable via /login → MCP Connections

Example: Custom MCP integration:

# 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, 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:

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
JSON/RPC mode implementations	packages/coding-agent/src/modes/headless-completion.ts
SDK and AgentSession	packages/coding-agent/src/core/sdk.ts
Sub-agent runtime (rlm)	packages/coding-agent/src/core/rlm-runtime.ts
MCP integration guide	packages/coding-agent/docs/mcp-integrations.md
Skill discovery and loading	packages/coding-agent/src/core/skills.ts
Daemon lifecycle control	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 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 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 and enable through the MCP Connections UI.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}