> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ringee.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Use it from an agent

> Give any shell-capable agent access to Ringee

Any agent harness that can run shell commands can operate Ringee through the CLI — no MCP client implementation required. Install it, export the connection, and have the agent call commands with `--json`.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
npm i -g ringee
export RINGEE_MCP_URL="https://api.ringee.io/api/mcp/<userId>/sse"

ringee config check                 # confirm connectivity
ringee contacts search acme --json  # machine-readable for the agent
```

This works with Claude Code, OpenClaw, Hermes, a cron job, or your own loop.

> [!NOTE]
>
> If your harness speaks MCP natively, connect the [MCP server](https://docs.ringee.io/mcp/connect.md)
> directly instead — you get typed tool schemas and the client can surface
> confirmation prompts itself.

## Why this is safe

The guardrails live in the CLI, not in the prompt. An autonomous agent cannot spend credits, mint a magic link or delete a contact without passing a flag that encodes a deliberate decision:

| Action | Required |
| - | - |
| `leads reveal` | `--yes` |
| `sessions create` | `--yes` |
| `sessions revoke` | `--yes` |
| `contacts delete` | `--confirm-phone <storedPhone>` **and** `--yes` |
| `campaigns delete-lead` | `--yes` |
| `dnc remove` | `--yes` |
| `voice-agents call` | `--yes` |

Without them the command exits non-zero with an explanation, which the agent can relay to the user instead of guessing.

## Brief the agent

Three commands print the shared operating knowledge, no connection needed:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
ringee tools    # capability catalog with sensitivity tags
ringee flow     # the outbound flow, step by step
ringee prompt   # the full agent system prompt
```

Feeding `ringee prompt` into your agent's system message gives it the same rules the Claude skills and the ChatGPT app follow — which tool maps to which action, the prospect → contact → session → outcome → follow-up flow, and when to stop and ask.

## A typical loop

**1. Resolve before acting**

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
ringee contacts search "ada" --json
```

Never act on an id the user did not approve.

**2. Do the work**

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
ringee outcomes log <callId> interested --note "Wants pricing" --json
ringee callbacks create <contactId> 2026-05-24T10:00:00-04:00 --json
```

**3. Stop at sensitive steps**

Ask the user, then pass the flag:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
ringee sessions create --contact <id> --title "Tue outbound" --yes --json
```

For an autonomous phone conversation, resolve the agent first, name the destination to the user and wait for approval before starting it:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
ringee voice-agents list --json
ringee voice-agents call <agentId> --to +13055550123 --var first_name=Carlos --yes --json
```

**4. Check exit codes**

Sensitive commands exit non-zero when the confirmation flag is missing. Treat that as "ask the human", not as a bug to work around.

## Build on the agent layer directly

If you are writing TypeScript instead of shelling out, use `@ringee-io/agent` — the package the CLI itself is built on. It contains no business logic: it validates input, talks to the MCP, and shares the catalog, flows, prompts and rules.

```ts theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
import { RingeeClient } from "@ringee-io/agent";

// Reads RINGEE_MCP_URL, or RINGEE_BACKEND_URL + RINGEE_USER_ID [+ RINGEE_ORG_ID]
const ringee = RingeeClient.fromEnv();

const { contacts } = await ringee.searchContacts({ query: "acme" });

const created = await ringee.createContact({
  phoneNumber: "+14155552671",
  name: "Jane Doe",
});

// Sensitive — confirm with the user first:
const session = await ringee.createCallSession({
  title: "Tuesday outbound",
  contacts: [{ contactId: created.contact!.id }],
});
console.log(session.joinUrl); // share exactly as returned

await ringee.close();
```

Reuse the operating knowledge in your own prompts:

```ts theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
import {
  buildSystemPrompt,
  TOOL_CATALOG,
  PRIMARY_FLOW,
} from "@ringee-io/agent";
```

| Export | Purpose |
| - | - |
| `RingeeClient` | Typed facade — one method per capability |
| `RingeeMcpClient` | Lower-level MCP SSE transport wrapper |
| `TOOL_CATALOG` | Action → tool map with sensitivity classes |
| `PRIMARY_FLOW` | The outbound flow definition |
| `buildSystemPrompt()` | Composed prompt from catalog, flow and rules |
| `schemas`, `types` | Zod input schemas and result shapes |

## Next steps

> [card] [Claude skills and apps](https://docs.ringee.io/mcp/apps.md)
>
> Ready-made `/ringee` commands for Claude and ChatGPT

> [card] [Safety model](https://docs.ringee.io/mcp/safety.md)
>
> What the server enforces regardless of the client


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.