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.
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.
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.
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.