Documentation

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.