Agents

An agent is a browser automation you describe in plain language instead of scripting. You give it a mission and a starting URL; it opens a real cloud browser, works through the site (navigating, filling forms, clicking, reading, downloading) and returns data that matches the output schema you defined.

The difference from a scraper is maintenance. A scraper is a list of CSS selectors that breaks when the site is redesigned. An agent reads the page it is on and works out what to do, so a moved button or a renamed field does not require a code change.

Use a flow when the data is in a document you received. Use an agent when the data lives on a website, or when something has to be done on a website with data you already have.

Agents live under Agents in the sidebar. You can start from a blank agent or build one from an existing flow, so the flow's output fields arrive already set up as input variables.

1. 1Click Create Agent (or New from flow) and give the agent a name.
2. 2On the agent's Configuration tab, write the Mission and the Starting URL.
3. 3Add the Variables the mission needs and the Captures you want back.
4. 4Click Save, then Test run and watch the run live.
5. 5When the result is right, set up Delivery and switch the agent to active in the top bar.

A new agent starts as a draft. The active switch in the top bar controls whether it runs on its schedule. Duplicating an agent copies its configuration, but not its secret values or its schedule, so a copy never starts firing on its own.

An agent is five pieces of configuration: what to do, where to start, what it knows going in, what it must bring back, and where that goes.

Each variable has a name, a type (text, number, boolean, date, object, list or file) and a source. The mission refers to variables by name.

File variables. A variable of type file hands the agent a flow run's original document so it can upload it to the site (an invoice to a customs portal, for example). Set it to Triggering run's document to get the document of the flow run that started the agent, or give it a run ID; a Test run or an API call can send another run ID for each run. The run must belong to your organization; otherwise the run fails before a browser opens, with nothing billed.

Secret variables. A static text variable can be flagged Secret, for a portal password for example. Its value is stored encrypted and never appears in the agent configuration, run inputs, outputs or step log.

• Only Owners and Admins, who are the only ones who can edit an agent, can set or clear a secret
• Secrets must be at least 6 characters; once saved, the field shows that a value exists without showing it
• The agent types the secret into the page by name, without ever seeing the value
• A secret can only be typed on the starting URL's site (the same host or one of its subdomains)
• If a secret value shows up in the page text, it is masked as *** in the steps and output

Captures declare the shape of the result. Each one has a name, a type and an optional description, and nested structures are supported, so an agent can return a list of objects rather than a blob of text you have to parse afterwards.

Give an agent a file-typed capture and it can fetch documents as well as read them: a statement behind a login, an invoice PDF from a portal. It can download a file from a link, or click a download button and keep whatever file the site sends back.

Exceeding a limit does not stop the run: the agent is told the file was too large and carries on with the rest of the mission. If a site answers a download with a web page instead of a file (a login screen, for instance), the agent is told so rather than saving the page as if it were the document.

Some portals email a one-time login code or a confirmation link. Connect a mailbox and the agent can wait for that email, read the code or link, and carry on. It is set up under Settings → Mailbox.

• The mailbox is read over IMAP in read-only mode; nothing is marked as read or changed
• Only a message that arrives after the run started counts, the newest match wins, and each message is used at most once
• The agent waits up to 5 minutes for the email, checking every 10 seconds
• If nothing arrives, the agent is told so, and your mission decides what happens next (resend the code, or stop)
• For Gmail or Google Workspace, turn on 2-step verification and create an app password

Say it in the mission, too: “After submitting the login form, wait for the verification email and enter the code.”

The strongest setup is extract, then act. A flow pulls fields out of a document, and the agent uses those fields as its inputs, so the document you received drives what happens on someone else's website with no copying by hand.

1. 1On the agent, add variables with the source From flow run and pick the flow field each one reads (or use New from flow to create them all at once).
2. 2Open the flow and select the Agent panel in its sidebar.
3. 3Click Link Agent and choose the agent.
4. 4Run the flow. When the run completes, the agent starts automatically with the flow's output as its input.

• The agent receives the cleaned output when the flow has a Cleaner
• If the flow uses Human in the Loop, the agent runs only after a reviewer approves, with the approved data; a rejected run never reaches the agent
• Deliveries and webhooks of an agent run started by a flow carry that flow run's ID
• In a pipeline, an Agent node does the same thing on a canvas, fed by a flow node

Worked example. A purchase order arrives by email. The flow extracts the supplier and the part numbers, and a Cleaner normalises them. The linked agent logs into the supplier portal, looks up the parts, captures the live unit price and lead time, and writes the results into a Bucket next to what the PO said, so the discrepancy is visible before anyone approves the order.

An agent can deliver each completed run to several places at once. Turn on as many deliveries as you need on the Delivery tab; they run independently, so one failing never stops the others. With none turned on, results stay on the run page to view or download.

Email and Bucket deliveries have an Include input variables in the delivered payload option, which makes a Bucket row self-describing: what was asked, and what came back. The webhook always includes them.

The webhook payload carries bot_id, bot_run_id, status, inputs (the run's resolved input variables, secrets excluded), output (the captures, with a link for each file) and, when a flow run triggered the agent, flow_run_id, so your system can attach the result to the document it came from.

{
  "bot_id": "3f2a...",
  "bot_run_id": "9c41...",
  "status": "completed",
  "flow_run_id": "b7e0...",
  "inputs": { "part_number": "AX-2210" },
  "output": { "unit_price": 18.4, "lead_time": "3 weeks" }
}

If a delivery fails, the run is marked Completed with warnings and the run page lists the Delivery errors. The agent's creator also gets an in-app notification.

An agent can be started six ways. However it starts, it goes through the same limits, concurrency and deliveries.

Schedule. Turn on Run on a schedule and pick a frequency: Every hour, Every day, Weekdays (Mon–Fri), Every week or Custom cron (five fields: minute, hour, day of month, month, day of week, for example 30 8 * * 1-5). Times are in your organization's timezone, and the settings panel shows the next run.

• Scheduled runs use the static variables and secrets saved on the agent
• The schedule only fires while the agent is active
• Runs start within about a minute of the scheduled time, later if all workers are busy
• A missed window is not replayed: after a delay the agent fires once, not once per missed slot
• A scheduled run that can't start (the previous run is still going, or your organization can't start new work right now) appears as a failed run that says why
• Failures of scheduled and API runs send the agent's creator an in-app notification, since nobody is watching the run page

Bucket trigger. Under Settings → Bucket trigger, turn on Run once per matching bucket row to start one run for every row of a Bucket that passes your filters, for example one run per lead whose status is not yet complete. Pick the Row key that identifies a row and which columns fill which input variables.

• The bucket is checked about every 30 seconds; a row whose run is still in progress never gets a second one
• Each row gets a limited number of attempts per 24 hours (1 to 10, default 3), at least 10 minutes apart
• The pace is the agent's concurrency limit: N runs work while N more wait, and the trigger keeps the limit on
• Close the loop with a Bucket delivery that updates the same row (status = complete), so a processed row stops matching
• If the bucket is gone or credits run out, the trigger pauses and a failed run says why

By default, overlapping triggers run in parallel. Many portals don't like two sessions for the same user at once, and some sites should not be hammered, so an agent can be limited to one run at a time, or up to ten, under Settings → Concurrency.

• A run waiting for its turn shows the status Waiting; it holds no worker and is not billed
• Up to 20 runs can wait per agent; beyond that, new triggers are refused (the API answers 429)
• A run that waits more than 24 hours is marked failed
• Only one scheduled run waits at a time, so a slow agent on a fast schedule can't pile up

Every run streams its steps as they happen, and you can open a live view of the browser session to watch it work. Finished runs keep a replay, so you can see exactly what the agent did rather than inferring it from the output.

• Steps: a log of what the agent did, in order
• Captured output and Captured files, with downloads
• Summary: duration, LLM calls and tokens
• Watch live session while it runs, View session replay afterwards
• Browser sessions: one entry per browser session when the run paused for a person and was resumed
• Identifiers (run ID and session ID) for support requests

Cancel run stops a waiting, queued, running or paused run. The browser session ends within a few seconds and nothing is delivered.

Some steps only a person can do: a captcha, a code sent to the account owner's phone, a login someone has to approve. Turn on Settings → Human help and the agent can stop and ask for help instead of failing, then carry on with the mission.

1. 1The agent asks. Whoever started the run (or the agent's creator) gets an in-app notification, Agent needs your help, that opens the run page.
2. 2The run stays Running with the browser open. The run page shows The agent needs your help with its request, above the live session.
3. 3Do what it asks in the live session, optionally leave a Note for the agent (“I typed the SMS code and logged in”), and press Done — continue. The agent picks it up within a few seconds, in the same browser.
4. 4If nobody comes within the wait, the browser is closed and the run is saved where it was, with the status Waiting for a person. Press Resume run when you are ready: a new browser opens on the same page, still signed in, and the agent continues where it left off. If the obstacle is still there it asks again, so stay on the run page.

• The wait counts inside Max runtime and is billed as browser minutes; the agent always keeps about two minutes to finish after a wait
• A paused run holds no browser or worker and costs nothing while it waits; resuming needs the same one-minute minimum balance as a new run
• Resuming continues the same run: steps, captures, duration and credits add up, and Browser sessions lists every session with its replay
• A paused run can be resumed for 72 hours, then it is marked failed; one run can use up to 10 browser sessions
• A paused run can be cancelled; it frees its concurrency slot, but its schedule and its bucket-trigger row still count it as in progress

Say it in the mission too, so the agent knows when to ask: “If a captcha or a verification code appears, ask for help and wait.” For codes sent by email, a Mailbox (above) needs no person at all.

Runs are bounded so a mission that goes wrong cannot run forever. Two limits apply, both set per agent under Settings → Limits. Leave a field empty to use the default.

Your own systems can start an agent and poll for the result with your API key, sent as X-API-Key to https://run.tavnit.io/api. Name the agent by its ID, shown on its Agent ID panel, or by its name.

By name. bot_name must match the agent's name as shown in the app, ignoring case and extra spaces. Archived namesakes are ignored (a name only an archived agent has answers 409, agent archived). No match answers 404; when several active agents share the name the call answers 409 with their IDs in bot_ids, so rename one or use the ID. Renaming an agent changes what bot_name must say: use bot_id for integrations that must survive a rename.

Every API call starts a new run. A 402 means your organization can't start new work right now; contact the Tavnit team. For the full request and response reference, see the API page. If you would rather not call the agent directly, trigger the linked flow and let the agent follow.

Only Owners and Admins can create, edit, duplicate or delete an agent, which includes setting secrets. Members can run agents, read their runs, help a run that asks for a person and resume a paused one. HITL Only members have no access to agents.

See user roles and permissions for the full matrix.