Put it to work

The ways, side by side

Sessions

A session is one conversation with one agent, on one version, with its own files. Start one with Test on the agent's page or card. Past sessions are listed on the agent's page under Sessions, newest first, with who it was for, its title, when it started and the version it ran; Open shows it again.

• Your own sessions open in chat and carry on. Anyone else's opens read only: "You are observing this session." The owner and Admins can see every session; a Member sees their own.
• The paperclip attaches images (PNG, JPG, GIF, WEBP) and files (PDF, DOCX, TXT, MD, CSV, JSON): up to 6 MB per message in all, and a Word file up to 5 MB. The microphone types what you say, where your browser supports it.
• While the agent is working, Send now interrupts it with your new message and Queue sends it afterwards.
• Files, in the session's header, shows what the agent wrote, ready to preview or download.
• Rename a session with the pencil beside its title. Delete it from the ⋯ menu; that cannot be undone.

Website chat and the share link

Every agent has a chat page of its own, reached by its share link, and a line of code that puts the same chat on your website. Both are set in the Website chat panel on the agent's page, under Who can chat:

Every new agent starts Restricted. To add your website, press Add a website and type its domain: acme.com covers its subdomains too, and localhost works for testing. Then press Copy beside Code for your website and give it to whoever runs your site:

<script src="https://agentnava.com/embed/v1.js"
        data-agent-id="your agent's id"
        defer></script>

It draws a round chat button at the bottom right of the page. data-color sets the button's colour, and data-user-id passes your own ID for the visitor, which then appears in the agent's Sessions list.

Your page can also hand the agent's HTTP tools a value it knows about this visitor, such as their cart, with window.AgentNava.page.set('cart_id', value). A tool that lists the name in pageValues uses it as {{pageEncoded.cart_id}} in the address or {{pageJson.cart_id}} in a JSON body; the plain {{page.cart_id}} form takes only letters, digits and - _ . ~. The value is kept with the visitor's conversation and filled in when the tool runs. The agent never sees it unless your API's answer repeats it. Names are lowercase letters, digits and _; values are up to 1,024 characters with no spaces, quotes or brackets. Set a value to '' to remove it.

The agent can also ask the page to do something, such as add a product to the cart. Give the agent a page action (in the builder, or pageActions through the API), then handle it on the page: window.AgentNava.page.handle('add_to_cart', async ({ variant_id, quantity }) => { ...; return { cartCount } }). What the handler returns goes back to the agent; if it throws, the agent is told it failed. A page with no handler for the name answers that the action is not available there, and a handler that takes longer than about 12 seconds is treated as failed. The inputs come from the agent, so check them in the handler before acting.

• Under the message box, the chat says "its name is an AI assistant." and shows a "Made with AgentNava" link. On a paid plan (Team and up) you can hide the link: in the Website chat panel press Customize and set Made with AgentNava to Hide, ask the Agent Builder, or set appearance: { showMadeWith: false } through the SDK. It is part of the draft, so visitors see the change after you publish. The AI notice always stays, and if the plan ends, the link shows again.
• Each visitor can send up to 50 messages to an agent a day (in UTC). Signed-in members are not held to that limit. Visitors send text only.
• Publishing a new version moves the website chat to it, unless the new version needs each person's own account or secret, which a website visitor cannot bring.
• While the agent is paused, visitors read "This assistant isn't taking messages right now." If your workspace is out of credit, they read "This assistant can't reply right now." They are never told why.

Schedules

In the Build screen, open Trigger and choose Schedule. Switch it to Enabled, pick a Frequency (or Custom cron, five fields), check the Timezone, which starts as your browser's, write the Instructions for scheduled runs, and press Save schedule.

Saving takes effect at once, as a new version, with no Publish. Each run is a turn, and all of a schedule's runs continue one conversation, so the agent can build on what it did last time. The agent's card shows the next run and the last result, and "Last scheduled run failed" with a Fix link when one goes wrong.

Webhooks

A webhook lets another system start the agent, for example when a payment arrives or an issue is opened.

The sender posts JSON or text, up to 1 MB. Resending is the sender's job: a delivery seen in the last 7 days is recognised and skipped, shown as "Repeat, skipped" under Recent deliveries. Switching the webhook off stops its address at once; switching it on again, or Regenerate URL, gives a new one.

Projects

A project is a team of agents working toward one goal, coordinated by a project manager agent you talk to. Projects are rolling out: when Projects appears in your rail, press New project, give it a name and a goal, choose the agents, and press Start the project.

From your own code

Developers can start sessions and run agents from their own software. In the rail, open Developer and press Create key; the key is shown once. Then follow the Quickstart in the developer docs.