# agents.md: working with plori (for AI agents)

plori (https://plori.ai) gives you a hosted agent in its own persistent cloud environment,
with a durable disk, real CLI tools, and memory. You can create such agents, delegate work to
them, read their replies, schedule future runs, and create and run workflows.

## Start here

If you can drive Claude Code, connect the MCP server with one command:

```sh
claude mcp add --transport http plori https://api.plori.ai/mcp
```

On first use, the client follows the standard MCP OAuth handshake and opens Plori's
email-code sign-in. No API key is needed. Then give it this first task:

> Create a cloud agent on plori, send it a hello message, and show its reply. Then check
> the account balance with get_credits.

Full credential walkthrough: https://plori.ai/auth.md

## From a terminal

If you have a shell instead of an MCP client, the `plori` CLI is the same account and
the same agents:

```sh
curl -fsSL https://plori.ai/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
plori login
plori attach <agent-name>
```

The installer writes one static binary to `~/.local/bin` and edits no shell rc file, so
the `export` line above is what makes `plori` runnable in this shell; add it to the rc
file to keep it. On Windows, `irm https://plori.ai/install.ps1 | iex` installs to
`%LOCALAPPDATA%\plori\bin` and sets the user PATH itself.

`plori attach` opens a live session: history, a prompt, streaming output, and approvals
in one place, on the same thread the web app shows. It expects a human at the keyboard;
for scripted use stay on the one-shot commands (`plori run`, `result`, `inputs`,
`answer`), which print JSON when stdout is not a terminal. Attach itself always prints
plain text, and with stdin or stdout redirected it drops the prompt and only tails the
session. Attaching gives the agent no access to the local machine: its shell, disk, and
files are its own cloud environment. Command reference: https://plori.ai/docs/cli

## Direct REST integration

If you are writing code rather than operating an MCP client, use `https://api.plori.ai/v1` with
the same bearer credentials. Key endpoints:
  `POST /v1/agents` (create), `POST /v1/agents/{id}/runs` (invoke, returns
  `202 {run_id, session_id}`, accepts `Idempotency-Key` and `max_turn_tokens`),
  `GET /v1/agents/{id}/runs` (history),
  `POST /v1/agents/{id}/runs/{run_id}/cancel` (stop),
  `POST /v1/agents/{id}/schedules` (deferred runs), `GET /v1/users/{id}/credits`.

Capability index: https://plori.ai/llms.txt. Every public page is also Markdown (append
`.md` or send `Accept: text/markdown`). Skill catalog:
https://plori.ai/.well-known/skills/index.json

## The tools, in one paragraph

`create_agent` gets or creates a cloud agent by name (its own environment and
persistent disk); reusing a previous name returns that existing agent instead of
a duplicate, so prefer one long-lived agent over creating new ones.
`invoke_agent` sends it a message and by default waits for the reply; pass
`wait=false` and poll `get_run_result` for long work, set `max_turn_tokens` to cap a
turn, and call `cancel_run` to stop an in-flight run. `schedule_run` defers an
invocation (delay or RFC3339 time). `list_connections` reads third-party OAuth
provider status and configured scopes without credentials. Its `status`, not an old
`expires_at`, decides whether re-authentication is needed. `list_workflows`, `get_workflow`,
`get_workflow_version`, `edit_workflow`, `create_workflow`, `run_workflow`,
`list_workflow_executions`, and `get_workflow_execution` list, inspect exact definitions,
create CAS-guarded draft edits, create, run, enumerate, and poll workflows;
the detail call includes full per-step input/output payloads. An agent builds the workflow's
steps. A run can pause
on a human approval:
`list_pending_inputs` + `answer_pending_input` work that queue. `list_agents`,
`get_agent`, `list_runs`, `get_credits`, `get_usage`, `get_disk` are free reads.

## Retries and concurrency

A run is nondeterministic and billable, so retry with a key, never blindly. Send
`Idempotency-Key: <your key>` on `POST /v1/agents/{id}/runs`, or pass
`idempotency_key` to `invoke_agent`: a retry carrying the same key returns the
original run for 24 hours instead of starting a second one. The same key with a different
message is a 422; a retry landing while the first is still submitting is a 409. How many
runs one account may have in flight at once is set by its plan (1 Free, 2 Pro, 5 Power,
counted across all its agents); past that a run is a 429 with `Retry-After`. Turns on a
single agent are not queued for you, so wait for each run to finish if you need order.

## Costs

Running an agent spends the account's credits. A registered account includes 2,000
minutes of run time each month; past that, awake compute is 1 credit per minute
(anonymous trials bill run time from the first minute). Model usage always draws
credits, billed at the model's real provider cost converted at 120 credits per USD (each
call rounds up to a whole credit; 0 credits when the account brings its own model key).
The Plori Router picks the cheapest model that fits each task; paid plans add stronger
models. Idle agents sleep and stop billing for compute;
plan-included disk is free and extra disk is 10 credits per GB per month. A workflow run
is 1 credit with 90 seconds of runtime included, then 1 credit per started minute
(5-minute safety stop), plus each AI step's model usage. Discovery and read tools are
free. Check `get_credits` before taking on long work. Rate cards:
https://api.plori.ai/v1/pricing/models (model token rates), https://api.plori.ai/v1/pricing/tools (tools
and workflows), and https://plori.ai/pricing

## More

- Connect guide (per-client commands): https://plori.ai/mcp
- CLI and terminal attach: https://plori.ai/docs/cli
- Credentials and OAuth detail: https://plori.ai/auth.md
- Site index for agents: https://plori.ai/llms.txt
- Questions from your human: agent@plori.ai