Docs › Start here
Complete one support task with your agent
Follow a return request from the first check to the recorded outcome. This walkthrough marks every point that needs approval. The case is from Acme Commerce, a fictional online shop; the order, the dates and the replies are illustrations. The same task, from the customer's side, is on Customer service; every tool named here is in the MCP reference.
What you need
A map that covers your shop and your helpdesk (Get started), with your returns policy among the documents the scan read. An agent connected with a key that acts with approval, and with its own access to both systems: Maplith never performs the action and never sees the agent's credentials. Test with exactly these permissions; a read-only key stops at step 3 and hands the rest to you.
An admin opens Agents & access › Policies, adds the refund and the reply ("Add an action" offers payments.issue_refund and helpdesk.reply_to_case among Maplith's starting points) and allows each for this key under "What each agent may do", set to act with approval. Without a policy for the operation, request_action answers denied and says where to add one.
01Find the case
Where your helpdesk sends Maplith its events, a new conversation is a support_case_opened signal and the agent finds it with list_signals. Otherwise you give the agent the case yourself, and it asks Maplith for the case's context by kind: the kind of identifier it holds and the kind of case, never the customer's values. This call is real; run it as it stands.
{
"case": {
"identifier": "order number",
"topic": "return"
}
}› list_signals states: [open] order: urgency support_case_opened · attention · objects: support_conversation · created_at: [the version]
02Take it
With a signal, the agent takes it first, so no other agent does the same work. It passes the signal's created_at as signal_version, and holds the signal for 24 hours unless it asks for less or more. Nothing changes in any system by this call.
› take_signal signal_id: [the signal] signal_version: [its created_at] in_progress · held by this key until [24 hours from now] · then: record_action closes it
03Read the context
Maplith answers with what the case needs: the fields to look the customer up by, the routes from the conversation to the order and the refund with how far to trust each hop, the rules that apply, the playbooks in use, and the operations this key may ask for with the decision each one would get. It holds no rows: the agent reads the records in your systems with its own access.
{
"lookup": [{ "object": "support_conversation", "field": "order_number" }],
"routes": [
{ "from": "support_conversation", "to": "order",
"join": "order number quoted in the message", "basis": "guessed", "trust": "check before relying on it" },
{ "from": "order", "to": "refund", "join": "order_id", "basis": "measured" }
],
"statements": [{ "text": "returns within 30 days; exceptions need a person" }],
"playbooks": [{ "title": "Return request" }],
"actions": [
{ "system": "payments", "operation": "issue_refund", "target_kind": "order", "expected": "pending" },
{ "system": "helpdesk", "operation": "reply_to_case", "expected": "pending" }
]
}A route whose first hop is guessed, because the order number sits in the customer's message. The agent confirms the order in the shop before it asks for anything. "expected" is a forecast of the decision, never a permission.
04Do the permitted work
Reading is permitted: the agent looks the order up in the shop, reads the delivery date and drafts the reply. In the example the return was requested 44 days after delivery, outside the 30-day rule, so the policy says a person decides. The agent has done everything it may do on its own.
05Ask: the request is pending
Before anything changes in your systems, the agent calls request_action with the operation, the target, the params, a reason a person reads and its own idempotency_key. The answer is one of three words. "pending" means exactly this: nothing has happened, a person has not decided, and the agent must not act.
› request_action op: ask system: payments operation: issue_refund target: { kind: order, id: [order id] } params: { amount_dkk: [the amount] } reason: "Refund a return requested 44 days after delivery.\nWhat it does: refunds the order in full.\nProblem: the policy allows 30 days; no exception is recorded.\nValue: the customer keeps their trust; the exception is decided by a person." idempotency_key: [your key for this request] signal_id: [the signal] decision: pending · request_id: [the request] · approve_url: [a link for a person]
The agent shows you approve_url and stops. The link opens the request in Maplith, where a signed-in workspace admin approves or denies it, under Agents & access › Activity or from the Slack message; the link itself decides nothing. The proposed reply and the reason are there to read.
06Wait: the decision
The request stays pending until a person decides. The agent does nothing in your systems meanwhile. When it is woken, or on its next run, it asks again with the identical request and the same idempotency_key and reads the decision. On a signal it cannot keep waiting on, it records needs_human instead, with the task the person finishes.
› request_action (the same request, the same idempotency_key) decision: allowed · request_id: [the request] # or: decision: denied · why: what to tell your human
07Act: in your systems, with the agent's own access
Only "allowed" lets the agent act, and it acts with its own credentials: the refund in the shop, then the reply in the helpdesk, each asked for separately. Where Maplith signs grants, the agent redeems the grant first with redeem_action_grant; only the outcome "redeemed" authorises the action. Maplith performs nothing itself.
› shop: refund order [order id] → accepted by the shop › helpdesk: send the approved reply → sent
Denied: the agent sends nothing, refunds nothing and tells you why. A refund the shop refuses is reported as a failure, never as done.
08Check: read the result back
Before it reports anything, the agent reads the refund back from the shop and the reply back from the helpdesk. What it records next is what those systems state, not what it sent. An amount is stated only when the system states it; the agent never estimates one.
› shop: read refund for order [order id] → status: succeeded · amount as the shop states it › helpdesk: read the conversation → the reply is on it
09Record it
Last, the agent tells Maplith how the request ended: record_action with the request_id, or with the signal and its version and episode, the outcome, the resolution and a summary of at most 500 characters. The record is what Maplith knows about the work; it is not a second look at your systems.
› record_action request_id: [the request] signal_id: [the signal] signal_version: [its created_at] episode: [as read] outcome: done resolution: fixed summary: "Refund approved by a workspace admin; replied to the customer; return exception." recorded · the signal is done
Under Agents & access › Activity: the request, the decision and the record, each with who did it. Under Business map › Activity › agent work: the signal, who held it and how it ended.
Make it routine
Keep refunds set to act with approval while you test. If the scan drafted a playbook for return requests from your helpdesk export, an admin reviews it under Rules & know-how › Playbooks and chooses "Approve and put in use"; an agent is handed only the playbooks in use, and a playbook guides the work without granting permission. To have the agent find new cases without being asked, connect the helpdesk's events or wake the agent: Wake your agent. What the handled cases were worth is counted only from the amounts your systems stated, on get_value_summary.