# Agents and your own tools

Give an agent your own operations, called for one of your customers, keeping only what you allow.

## Your own tools

`POST /platform-agents/tools` registers one of your operations: a name, a description written for the model, input and output schemas, a tier (`read`, `change`, or `approval` for anything that books, spends, sends or deletes), the scope a session needs, what may be kept, and your https address. The secret is in the answer once.

Request:

```
curl -sS https://api.rivier.ai/platform-agents/tools \
  -H "Authorization: Bearer $RIVIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "passport", "description": "What this guest has shared with you", "tier": "read", "scope": "read", "retain": "none", "url": "https://you.example/tools/passport", "input": {"type": "object"}, "output": {"type": "object", "properties": {"summary": {"type": "string"}}, "required": ["summary"]}}'
```

## How Rivier calls you

One POST per call, signed as webhooks are with `x-rivier-signature`. The body names the customer and your `ref` for them, the session, the scopes it was opened with, whether it is test mode and an idempotency key. Apply your own rules for that person. Your answer is checked against the output schema and given to the model as data, never as instruction; with `retain: none` it is kept nowhere.

Each call Rivier makes to one of your tools is a row of your log of calls with the method `TOOL` (`GET /usage/requests?direction=out`), and each turn counts as an agent run.

Request:

```
POST https://you.example/tools/passport
x-rivier-signature: t=1764590400,v1=5d41402abc4b2a76b9719d911017c592...
x-rivier-tool: passport

{"tool": "passport", "version": 1, "input": {}, "customer": {"id": "…", "ref": "guest-7"}, "connection": null, "session": "…", "agent": "…", "scopes": ["read"], "test": false, "idempotencyKey": "…"}
```

## Agents, with or without a model

`POST /platform-agents/agents` sets an agent's instructions, the typed parts its answers may carry and a first step: one of your tools asked first each turn. If it answers, that is the turn's answer and no model is asked; if it passes, the model goes on with its context. An agent with no model answers only by its first step.

## Sessions and turns

Open a session for one of your customers, with scopes (`read`, and `act` to be offered tools that act) and how much it keeps. With `retain: none` Rivier keeps no words: send the history you want considered with each turn and keep the transcript yourself.

Request:

```
curl -sS https://api.rivier.ai/platform-agents/sessions/$SESSION/turns \
  -H "Authorization: Bearer $RIVIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Is there a boat on Tuesday?", "history": [{"role": "customer", "text": "Hello"}, {"role": "agent", "text": "Hello. How can I help?"}]}'
```

## Approvals and mandates

A tool of tier `approval` waits for your customer's yes, given with their customer token, unless a mandate they gave covers it (a tool, and the most an input may be). A yes makes the call once. The model's use in a session counts on your plan, marked with the customer and the business.

## Messages to a business's agent

Inside a business that granted `agents:message`, a session's agent may send the business's own agent a message typed as one of its parts, by the built-in tool `message_business` or with `POST /platform-agents/sessions/:id/messages`. Both sides keep it and hear of it (`agents.message.sent`, `agents.message.received`, `agents.message.answered`). The business's agent that answers platforms (`answersPlatforms`) answers at once, with only its tools that need no person; otherwise a person of the business answers.
