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

plori (https://plori.ai) gives you a hosted agent on its own cloud computer, with a
persistent 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

## 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`),
  `GET /v1/agents/{id}/runs` (history),
  `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 computer 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. `schedule_run` defers an
invocation (delay or RFC3339 time). `list_workflows`, `create_workflow`,
`run_workflow`, and `get_workflow_execution` list, create, run, and poll workflows;
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
(24-hour 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
- 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