Using an agent¶
If someone shared a Donkit agent with you, this page is all you need. You don't build anything or configure anything — you just open the link and start a conversation.
Layout¶
The chat is the same one you'd get talking to your own main assistant, including its canvas, shown as a panel next to the agent's own interface — if the agent has one. An agent built with no interface of its own opens straight into the chat, full-size. When something the agent makes needs the canvas, it opens there in place of the interface, with App | Canvas tabs to switch back; the panel button in the top-left corner hides and shows the chat.
On a phone you see one screen at a time — app, chat, or canvas — and switch between them with the bar at the bottom. The canvas opens only when you tap it, so the conversation stays on screen while the agent answers: once the agent has made a file, Canvas appears in the bar. An agent with no interface of its own has no bar; there the Canvas toggle in the chat header gets a dot, and tapping it opens the canvas in place of the conversation.
Chatting¶
An empty chat opens with the agent's welcome and, if its owner added them, a few suggested first messages — click one to put it into the chat box, adjust it if you like, and send. A model picker appears in the chat box only if the owner allows choosing the model.
Open the agent's link and type in the chat box. Replies stream in live, word by word. While the agent works you'll see a status indicator, and you can:
- Stop a response mid-generation,
- Retry a failed turn, or
- Edit and resend your last message.
You can also keep typing while the agent is still answering. Your message reaches it at once — it either breaks off mid-sentence to take it into account, or finishes the action it is running and reads your message right after. Until it is read, the message shows in a lighter style and can be cancelled or edited; Stop gives the text back to the message box instead of losing it. If the agent's setup can't take a message mid-answer, yours waits and is sent on its own the moment the answer is done.
If the AI service behind the agent stalls or fails partway through a step — it stops responding, the connection drops, or it's overloaded — the agent restarts that step on its own after a short wait, at most twice, and a notice in the chat says so. You don't need to do anything (Stop still works meanwhile), and what the agent had already done is kept; if the step keeps failing, the answer ends with an error message and everything done up to then stays in the chat.
Write in whatever language you prefer: the agent answers in the language you used and follows along if you switch mid-conversation, unless its owner pinned a specific language in its instructions.
The chat is transparent about what the agent is doing:
- Thinking — when the agent reasons before answering, that reasoning streams in as its own visible strand.
- Tool activity — each action the agent takes shows as a single quiet line that says in plain words what it is doing right then — Searching the web for iPhone prices rather than a technical tool name (a line with no such phrase shows the tool's name). While it works, the line stays live with a timer, so you can always tell the agent has not stalled. Several actions in a row fold into one line with a step count — tap it to see every step. The line shows what the agent is doing, not the raw data behind it: contents are shown only for code the agent ran (the code and its output), sub-agents, media such as screenshots and other images, sources, and workflow cards.
- Sub-agents — when the agent hands work to helpers or to other agents, each one gets the same kind of line: its name and what it is doing right now, then the first line of its answer once it is done. Tap it to see its steps and its full answer; several helpers started together fold into one line.
Replies render as full formatted text — headings, lists, tables, links, syntax-highlighted code, diagrams, and inline images. When answering from a knowledge base, the agent can cite sources in a "Sources" section grouped by document, with page numbers and expandable snippets. You also get a copy button, suggested-prompt chips in an empty chat (tapping one fills the message box so you can edit it before sending), and an indicator of how much of the conversation the agent is holding in memory (with a nudge to start a new chat when it fills up).
When the agent asks you something¶
Sometimes the agent needs a decision from you before it can go on, and it asks right in the chat: a short question with options to choose from — one, or several where it says so. If none of the options fit, pick Other and type your answer instead; the agent receives exactly what you wrote, not one of its own suggestions. Answer whenever you're ready — if you leave the question too long the agent stops waiting and carries on without it, and the question says so rather than sitting there unanswered. And if your answer can't reach the agent — the connection dropped just as you sent it — the question stays on screen with a note, so you can send it again instead of wondering whether it went through.
Uploading files¶
Use the attach (＋) button or drag and drop — up to 10 files per message, each showing an upload status. Any file type is supported and immediately available to the agent to work with.
- Images (PNG, JPEG, GIF, WebP) are displayed as pictures the agent can see — up to 5 images per message, each up to 5 MB, shown as thumbnails.
- Documents and data (word processing, spreadsheets, slides, plain text, PDFs — including scanned ones) are read by the agent so it can analyze and work with their contents.
- Other formats (archives, videos, fonts, and other types) are available as files the agent can reference or process.
Once attached, files are immediately usable. To add a file to the agent's Knowledge base for deeper indexing and persistent storage across conversations, toggle Add to Knowledge on the attachment — Donkit will process it and it becomes available to all agents you connect to that Knowledge collection. You can also ask the agent to add a file to your Knowledge during the conversation.
Conversations and history¶
Each user has their own conversations, saved across sessions. A new conversation starts automatically on your first message and is titled automatically from what you said. A collapsible history panel groups past chats (Today, Yesterday, This week…) with a New chat button. You can rename and delete conversations, and roll a conversation back to an earlier point — which is how "edit an earlier message and continue from there" works. If other agents have delegated work to this agent, those appear in a separate "From agents" list you can open read-only.
Voice¶
When the owner has enabled voice, a microphone button appears in the composer while the message box is empty. Tapping it opens a full-screen voice overlay for a real-time spoken conversation. Voice shares the same conversation as text — you can speak, then switch back to typing without losing the thread — and everything spoken is transcribed into your history. Tool activity still shows during voice turns.
Realtime voice is also available in your own workspace. Dictation into the message box is temporarily unavailable — see Chat & your main assistant.
What the agent remembers about you¶
An agent keeps its own notes about you and your work with it, and every agent you talk to sees your short profile. Only you see your notes; other people using the same agent don't. You can review, edit and delete both — see Profile & memory.
Agents shared with you on the web¶
The rail has two collapsible sections: My agents, the agents you built, and Shared, everything others shared with you. Each section shows the three most recent agents; Show more opens the rest. An agent from Shared opens inside the workspace, in the same layout as any agent. If its owner shared it with you for editing, it opens in the builder instead. When the owner gave you Can copy or Can edit, the agent also offers Make a copy — your own copy of it; see what a copy contains. Your access level is set by the owner.
Setting up an agent shared with you¶
Some agents ask each person who uses them to connect their own accounts rather than sharing the owner's. If the agent you were sent uses any per-user connections or parameters, the My settings panel opens on its Connections tab when the agent needs them: connect the accounts it asks for, such as your own mailbox or Telegram chat (or pick a connection you already have in your Connections library), and fill in any parameters it needs from you. To change your connections or parameters later, open My settings at the top of the agent's page — a dot on the button means something still needs setting up. In the Android app the same setup is its own screen — see My settings below.
The same connections serve the agent's workflows when they run for you — see Your workflows.
Who pays for your use¶
Payment is where you choose who pays for your use of this agent. It is a separate item next to Connections in the agent's settings: on the agent's page, in the chat's agent settings, and in the mobile apps. It is available to everyone who uses someone else's agent. Leave Agent default and it follows what the owner set: they pay, or you do. Or pick your own personal wallet, or an organization you belong to. Save wallet changes only who is charged. It does not switch your workspace, move your conversations, or change which accounts the agent connects to. Chat, voice, images and video, API calls, and workflow runs all use that choice.
The screen shows how much of the owner's monthly allowance for you is already used, and when it resets. An empty allowance means no limit. Use you pay for yourself is not counted against it. The allowance is checked before each model request, including the ones that come after tool calls. A reply in progress can stop midway once the sponsored spend already recorded reaches the allowance; what was already used is charged. Several uses at once can all pass before their charges are recorded. Changing the allowance does not erase spend already recorded this period. It resets with the billing period of the wallet that pays for you.
If that allowance is used up, the chat says so, shows the date it resets, and offers Choose a wallet. Saving a wallet does not rerun the message or the run — you start it again. Donkit does not switch you onto your own money by itself.
When the owner pays and their balance is out of credits, you can choose Pay from my wallet and continue on your own money.
The agent's page shows the same notices before you send anything: when the owner's allowance for you is used up or the wallet you chose is gone, its notice offers Choose a wallet; when the owner is out of credits, it offers Pay from my wallet. Both open Payment. Topping up your own plan does not unblock an agent the owner pays for.
To remove your saved wallet choice, select Agent default and press Save wallet. This also works in the Android app and restores the owner's payment rule for your next use.
If a wallet you chose is revoked or deleted, you have to choose again. Donkit does not silently switch you back to the owner. Until you do, new paid work is refused. Work that already started keeps the wallet it started on.
Your workflows¶
If the owner lets the people they share the agent with run its workflows, the My settings panel on the agent's page — a published agent's page, or a team's page for its lead agent — has a Workflows tab. It appears once there is a workflow you may run, and lists each one with your own schedule and webhook. Open a workflow to get its card:
- Its name and description — what the workflow is for. The steps themselves aren't listed (your installation may choose to list their names and kinds), and what happens inside a step — its code, its prompt, its settings — isn't shown.
- Its Configuration form. You fill in the workflow's own fields with your own values. A field that comes from an integration shows the value from your own connection, or from the one the owner shares, and can't be typed into.
- Run, which starts a run that acts as you: it works on your own connections wherever the agent asks you to connect your own, and on the owner's shared ones for the rest — and it is paid the way your chat with the agent is, the agent's default or a wallet you chose (see Who pays for your use). If something of yours is missing, Run takes you to the panel's Connections tab, showing only what this workflow needs; connect it there, go back to Workflows — the workflow is still open — and press Run again. If what is missing is a connection the owner shares, or one of the agent's own variables, you're told the owner hasn't connected or filled it in yet. A workflow the owner hasn't finished can't be run, and its card says so.
- Your own schedule and webhook, in the card's Triggers section — see Personal schedules and webhooks. Switching your schedule on is checked the way Run is, and a refusal takes you to Connections the same way. A workflow that reads a request body runs only from its webhook or Run: its schedule toggle is locked, with a line saying why. When your schedule was switched off for you — its last run failed, you lost access for a while, or the workflow started reading a request body — the workflow list and the card say which, and you switch it back on once that's sorted. Max parallel runs stays the owner's setting, and it applies to your webhook on its own.
- My runs — your own runs of the workflow: when each ran, its status and, when you paid for it, what it cost. A run that's still going can be stopped, and an interrupted one resumed (where these controls are available on your account). A run that failed says why in one plain sentence: your connections need setting up; the workflow's settings need filling in; there weren't enough credits; the owner's allowance for this agent is exhausted; the wallet that pays has to be chosen again; the owner has to set up a shared connection or an agent variable it uses; the agent is paused by its owner; or, for any other reason, that the run didn't finish. A run you stopped yourself has no sentence — its status says it stopped. The error text stays out of this list. Where your installation lists a workflow's steps, each run also lists its steps with their status and how long each took, and a step's result, when it's meant to be read, opens with Show output.
The owner sees your runs only when they fail, as a short row with the time, the step and the kind of failure, or while they are still going, as a row the owner can stop — never what the run produced, and never your name.
You can also ask the agent in a chat: to run a workflow, to run one for you on a schedule — "every Monday at 9" — in your local time, to tell you which schedules you have or cancel one, and how one of your runs went — its status, why it failed if it did, and its final result. In your chat the agent itself never gets what happens inside a workflow's steps, a run's output step by step, or anyone else's runs, so asking it for them doesn't get them.
The Android, iPhone, iPad and Mac apps don't have the Workflows tab: open the agent's page on the web, or ask the agent in a chat. For how this looks from the owner's side, see Workflows on a shared agent.
Your own knowledge¶
You can attach your own knowledge collections to an agent someone else published — from My settings → Memory → My knowledge on the agent's page, from chat, or from My memory in the mobile apps. They work only in your own conversations with that agent: nobody else who uses the agent sees them, including its owner. Removing or detaching a collection stops the agent from using it.
Your API keys¶
If the owner has turned on Let users create their own API keys, an API keys tab appears in the My settings panel on the agent's page. There you can:
- create up to 10 keys,
- see each key's secret once, when you create it,
- delete a key you no longer need.
A key acts as you: it uses your own memory, files, profile, and personal connections when it calls the agent, and gets the same user-level access you'd have in the agent's database. If the owner turns the setting off, or you lose access to the agent, your keys stop working. A call made with a key before you've finished the agent's setup is refused with an agent_setup_required error — finish setup on the agent's page and retry.
In the Android app you manage your keys from the agent's menu in the chat header — see My API keys below. The iPhone, iPad and Mac apps don't manage keys: use the agent's page on the web.
The agent's interface in the apps¶
In the apps, an agent's own interface opens inside the app: your own agent's interface (the UI button), another person's published app, and the live preview in the builder. A file the interface offers for download, or prepares itself, is saved to your device. A file kept on another site opens in your browser.
| App | Where the file goes | What you see |
|---|---|---|
| Android | Downloads | Saved to Downloads, or Could not save this file. A large file first shows Saving “name”... |
| iPhone and iPad | The app asks where to save it | File saved afterwards, or Could not save this file. Cancelling shows nothing. |
| Mac | Downloads; a name that is already taken becomes name (1) |
Saved to Downloads, or Could not save this file. |
A file the interface links to can be up to 2 GB, and a file it prepares itself up to 50 MB. In the Android app the limit is a few megabytes when the file is packed into the link itself. A file over the limit shows This file is too large to save from the page. and is not saved.
A file is saved only after you tap or click in the interface, within a few seconds of the download starting; the time you spend answering a dialog the interface shows does not count. One tap saves one file, and one file saves at a time; a file the interface starts on its own is ignored, with no message.
Links to other sites open in your browser. Email, phone and text-message links open the matching app. A button that asks before it starts the agent's work shows the question in the interface itself, where the button is, with one button to confirm and one to cancel. When the interface uses a system dialog instead — to confirm something, show an alert or ask for text — the app shows it as a dialog. Maps and videos embedded in the interface show inside it. An agent's own interface does not print inside the apps: when it offers a document as a file, save the file and print it from your device.
The interface opens no sign-in windows inside the apps. In another person's published app, when it needs one of your accounts, the app opens My settings, its own setup screen for that agent (see My settings): by itself the first time the interface opens while your setup for the agent is unfinished, and whenever you tap a connect button. Connect the account there and go back; if the interface still asks for it, reload it from the toolbar. If you go back without finishing, My settings does not open by itself the next time you open the interface: tap a connect button, or open My settings from the agent's menu in the chat header. If the interface shows a setup window of its own instead, its owner has not published the agent again yet: open My settings from the agent's menu in the chat header.
In your own agent's interface and in the builder's preview, a connect button opens no sign-in window. The interface shows a note instead: The sign-in window can't open inside the app. Connect this account in the app's own agent setup, or open the agent in a browser. For your own agent, connect the account in the builder's Integrations panel or in your Connections library, or open the agent in your browser and connect it there. Do the same if a connect button shows no note.
A button in the interface can take you to the agent's chat with a message already in the message box — a question about the item you were looking at, for example. Text you had already typed stays, and the new message is added below it. Nothing is sent until you send it, so you can change the message first. In the live preview in the builder such a button does nothing.
In the Android app¶
The Agents tab lists every agent you can open — your own, your organization's and the ones shared with you — with the most recently used first. The built-in agents keep their own section at the top. The switch above the list narrows it to All, Mine (the agents you built) or Available to me (everyone else's). An agent that isn't yours shows who it belongs to: the owner's name, Organization or Catalog.
Open an agent and the menu in its chat header offers, for any agent you can use:
- My memory — what the agent remembers about you. See Profile & memory.
- My files — your own files with this agent: the ones you attach in chat and the ones the agent makes for you.
- My settings — the accounts and details this agent needs from you. It appears when the agent has anything to set up, with a dot while something is still missing.
- My API keys — your own keys for the agent. It appears when the owner turned on Let users create their own API keys.
- The agent's app — for an agent someone else built that has an interface of its own, it opens that interface inside the app.
My settings¶
My settings shows what the agent still needs from you before it can work as you. Each connection it asks for is a card with its state — Connected, Choose one, Not connected or Needs reconnect:
- If you already have connections that fit, pick one from the list with Choose a connection (or Change to swap it). They come from your Connections library.
- Otherwise connect a new one on the spot: sign in to the service, enter the keys it asks for, or add a mailbox or a Telegram chat. Where a connection can be checked, Test tells you whether it works.
Under Your details are the values the agent asks each person for. A value you already saved shows as Saved and is never displayed again. Continue switches on once nothing is left.
When you message an agent that needs this first, the app tells you and opens My settings for you; Continue takes you back to the chat.
My API keys¶
My API keys shows the agent's API address with a copy button and lists your keys for it, each with when it was last used. Create key asks for a name and shows the secret once, with a copy button — copy it then, you won't see it again. You can have up to 10 keys and delete any you no longer need; apps that use a deleted key stop working. If the owner hasn't turned API access on for the agent, the screen says so instead.
Signing in¶
You always sign in with your own platform account. Beyond that, how you get in depends on how the owner published the agent — you may just click a link, enter a password, be recognized as an organization member, or accept an emailed/linked invite. If the owner set end-user billing, you'll see a clear notice that usage draws on your own balance. You can also choose your own wallet, or leave the agent's default — see Who pays for your use. See Accounts & sign-in.