Skip to content

The QuickAgent Builder

The Builder (/build) authors a QuickAgent in the browser. Its start page offers two cards, each one you can click anywhere on:

  • Describe it to AI (/build/describe), first, writes the QuickAgent for you from a description and lands on the summary (below). It needs an account, because a draft spends credits, and it is offered only where the registry takes drafts.
  • Build it by hand opens the form, step by step. The card also links straight to Advanced.

The form has two views:

  • Step by step (/build/steps) shows one section at a time, with the least access already chosen. Each step is checked before you go on, and a Review step shows the contract in plain words and the agent.yaml the package will carry before you save or submit it.
  • Advanced (/build/advanced) shows every field on one page, as the Builder always did.

You can switch between them at any point and keep what you typed, signed in or not. Both end on the summary (/build/summary), the one page a QuickAgent is submitted from (below). Without JavaScript the page is the Advanced view, with its own submit button.

The form has two exits, and only one of them needs an account:

  • Save — anyone, signed in or not. The form is packed into a .tar.zst archive and handed to you; nothing touches the registry. Run it with agentry run --local <dir> --allow-unsigned, keep authoring in a repo, or agentry publish it later. A first agentry publish needs the QuickAgent's record to exist. Create it at /new, which asks for the namespace, the name, the run modes and the visibility and sets up the QuickAgent's git repository, then publish into it. Submit, below, creates the record for you. The archive holds the same files the CLI would pack, and the response carries its digest in an X-Archive-Digest header. Those compressed bytes are not the CLI's byte for byte, so a release published later takes the digest the registry computes when it re-packs.
  • Submit, on the summary — signed in. Submit makes the QuickAgent public, and asks you first (below). The same archive then goes into the publication pipeline. The Builder bypasses nothing: the server re-validates and re-packs what you submit, and the same scanning and review gate applies as to a CLI publish. Signed in, the form views' Continue to submit checks every step and opens the summary; without JavaScript the form's own Submit posts it as it is, to the same question. Signed out, the form views offer Sign in to publish.

The summary

The summary is short, and it is where you submit from, whether you described the QuickAgent or wrote it in the form. It shows:

  • How it works: the one-line summary and the guide's overview.
  • What it needs: every key it declares, its own and each MCP server's, with the help written for it and whether a run needs it or can start without it; the websites it reaches; each MCP server with the tools it may call, its keys, its configuration's names, its hosts and how it signs in (a remote server's address, the scopes it asks for, and a package's issuer, token files and token settings); any file, command or kind of data it declares, one line each; and the knowledge packs it ships, which anyone who can download the release can read, and the one it asks a person for. A kind it declares nothing of says None, or is left out. A host your description did not name is marked.
  • For a drafted QuickAgent, one line on AI Review's check of the finished draft (below).

The summary ends on Save and Submit. See it in the form opens Step by step, on Review, or Advanced, on the same draft, with every choice the summary leaves out: the namespace, version, licence, tags, the instruction file, the run modes, and for a draft the Drafter's notes. A submission the registry refuses comes back to the summary with your work put back. If the form still fails a rule, the summary names it and Fix it opens the step.

Submit asks first

Submit is public: anyone can find and install the QuickAgent once the pipeline publishes it. Before anything is sent, a page asks you to confirm two things: that the QuickAgent becomes public, and what the submission spends. The cost is read from your account: your balance, or your organization's pool if you are a member; nothing for an unmetered account; no credits on a registry without billing. If the cost cannot be read, the page says so rather than guessing. The page works without JavaScript. Submit publicly sends it. Cancel, or your browser's Back, sends nothing and takes you back to the Builder, where the draft your browser keeps comes back with it. If what the page said stops being true before you confirm, for example because the QuickAgent was made private meanwhile, you are asked again.

A QuickAgent that does not exist yet is created public. One that already exists as a private QuickAgent becomes public, together with its earlier versions, only once the pipeline publishes the new version. The page waits about a minute for that. If the version goes to review, is rejected, is refused or takes longer, the QuickAgent stays private, and you land on its Settings, where the result says why and you can make it public. A public release needs an SPDX licence, so Submit checks the licence first. Save does not, since a saved package is not public.

A refusal is said in words: a namespace you cannot publish to, the limit on private QuickAgents, or credits that have run out (with a link to your subscription).

The draft, while you are signed in

Signed in, the Builder renders inside your dashboard and keeps what you have typed as a draft. Click through to Runs and back and the form is as you left it; the start page offers the draft back, in either view. Discard draft is in the form views. A submission the registry refuses brings your work back; one it accepts clears the draft on your next visit to the Builder.

The draft holds the form's fields and nothing else, and it never leaves the browser — it is not on your account, so another browser will not have it, and signing out does not clear it. Discard draft does, and empties the form with it. Signed out, nothing is kept.

Edit a QuickAgent you published

On a QuickAgent you maintain, Edit opens the Builder on its newest published version. A QuickAgent whose only versions are still in review has nothing to edit yet. It keeps the QuickAgent's namespace and name, which you cannot change while you edit, and sets the version to the next minor: 1.2.3 becomes 1.3.0. If a newer version is already in review, the minor after that. You can change the version before you submit. Submit adds the new version to the same QuickAgent, and the pipeline scans it like any other.

The form holds what the Builder can write. A field it has no place for, such as runtime, dependencies, homepage, authors or shipped knowledge, is not carried into the new version. The version you started from keeps it. Tick shipped knowledge packs again in the form if the new version should ship them.

Edit opens your edit as the Builder's draft. A draft you had not finished is replaced only when you say so. The QuickAgent's own settings, which Edit replaced on its page, are linked above the form while you edit.

An instruction file over 512 KiB cannot be edited here. Neither can a manifest the form cannot represent. The page says which, and you can publish those from the CLI.

Edit it with AI

Beside Edit, Edit with AI has the Drafter write the next version for you. It is offered on a QuickAgent you maintain that has a published version, when the account that pays for your drafts is on Pro, Promo Pro, Business or Enterprise. On Standard there is no button. The page says so if you open it anyway, and links to editing it yourself and to the upgrade.

The form takes two texts, and at least one of them:

  • Additional instructions: what the next version should do differently, or do as well.
  • Problems with this draft: what is wrong with the current version, for the Drafter to solve.

Each takes up to 4,000 bytes. Start the revision starts a draft in Agentry against the current published version. AI Review reads your two texts, with that version's agent.yaml and instruction file, before the Drafter's model does, and stops the revision if it flags them. A revision holds the same credits as a draft and settles from what it uses. The form says how much it holds, and the balance it is paid from, before you start. Like any draft, it counts as your one run in flight.

When it finishes, its run page shows the Drafter's notes and what changed against the current version, in agent.yaml and in the instruction file, as the Builder will write them. Nothing is published until you choose:

  • Publish this version submits the revision under the same name at the next minor version, through the same confirmation as the Builder's Submit. The pipeline scans it like any other version, with one difference. When the registry can prove that the manifest and instruction file are exactly what this revision drafted from that version, S9, the check that compares a version with the one before it, scans those two files as it would a first release. Changes to them are not held as a rewrite, and their medium findings are not raised to high. New web access and wider permissions are still reported, and every other stage runs in full. The QuickAgent page shows such a version as Edit with AI (S9 in the trust model).
  • Open in the Builder opens the revision in the Builder at the next minor version, to change before you submit. A version submitted from the Builder, changed or not, gets the ordinary S9.

If the revision breaks one of the Builder's rules, for example a path ending in /, a tag in capitals or a summary over 140 characters, the page says which before you can press Publish this version. Fix it with Open in the Builder and submit from there.

As with Edit, what the Builder cannot hold is left out of the revision. A private QuickAgent becomes public once a revision you publish is published, as with the Builder's Submit.

Agentry Desktop has Edit with AI too. There it can also draft on this computer, for anyone who may publish the QuickAgent, with your own model provider and AI Review key, for no credits. A revision drafted on your computer leaves no record in Agentry, so it gets the ordinary S9.

What the form covers

The sections, in the order Step by step walks them:

  • Basics — the name, the one-line summary, the run modes the release supports (autonomous, interactive, or both), and the interactive session's opening message, which the form takes only when interactive is among the run modes.
  • Instructions — the instruction file itself (AGENT.md), up to 1 MiB. The form starts it with an outline: what the agent is given, its steps, what it returns.
  • Tools and web access — the sites the QuickAgent may reach (none, or a list of host names), and its declared MCP servers. Three servers from npm or PyPI go in structured rows (ecosystem, package, exact version, the tools it may call, the keys it needs, the hosts it reaches, its plain configuration as NAME=value lines, and a sign-in when it works with a person's own account). Two remote servers have rows of their own (address, how it signs in, scopes, tools, and its key). The rest go in a line-syntax field (npm:pkg@1.2.3 tools=a,b secrets=X egress=host env=NAME=value, or https://host/mcp auth=oauth scopes=a,b tools=x), up to eight servers in all (below). Versions are exact, pinned to this release and installed per-signature by the runner, and the pipeline checks each one against the vulnerability database when you submit. Review shows what the registry last knew of each version.
  • Files, commands and data — filesystem read and write, the commands it runs, the key names it needs of its own (never values), whether a run needs each key (below), and the kinds of data it touches, from the closed list (email, calendar, files, tickets, code, messages, payments, other).
  • Questions — the optional intake block: three structured rows (id, prompt, type, choices, required) plus a line-syntax field for more, up to twenty. A choice is kept as you write it, spaces included: separate choices with commas, and put one that holds a comma in double quotes (live incident, "yes, it is a header"). In the line syntax, a choice with a space goes in double quotes too (mode: How urgent? type=choice choices="live incident",postmortem). A question of type host (a server) asks for a server the QuickAgent works over SSH, and declares it as a target host (capabilities.targetHosts), up to four. The person running it gives the address and the sign-in, on their own computer only, and the summary says what it lets the QuickAgent do there. A question of type site (a website to test) asks for a website and gives the run a headless browser held to it (capabilities.browser), up to four; it is written as a url question. Tools and web access takes the other hosts the browser may open, or any public website, and Files, commands and data the keys of its own it may type into the site's forms.
  • Before a run — the optional guide block, which the run setup shows a person before they start a run and never shows the agent: what the QuickAgent does and returns, a "you will need" list, what files to bring, a hint for the task field, and help for each key it needs: four rows of a key's name and its help in markdown, up to 2,000 characters each, plus a NAME: help line field for more. The run setup shows each key's help beneath the key in its Secrets step, rendered with no HTML, no images and only absolute links to other sites.
  • Knowledge — the knowledge packs the release ships, and the pack it asks a person for. Signed in, it lists your packs kept in Agentry whose scan has finished; tick up to five. Each goes into the package under knowledge/<name>/, read back from Agentry and checked against the copy Agentry keeps. A shipped pack is not encrypted: anyone who can download the release can read it. A pack is at most 10 MiB, and a submission from this page at most 16 MiB compressed. The same step takes one line asking a person to attach a pack of their own, and whether a run needs one; the run setup shows that line and never shows it to the agent (Knowledge).
  • Publishing — the namespace (your handle by default), version, licence and up to ten tags. There is no visibility to choose: Submit makes the QuickAgent public.

Any host (*) is in Advanced only. It is refused by runners unless the operator's policy allows it, and it routes the version to review by default. A declared server always lists its hosts: the runner refuses * for a server. A server that needs a key declares it by name, and the key is never in the package: whoever runs the QuickAgent supplies it, from their own environment on their computer, or as a secret when they start it in Agentry (Hosted runs).

Remote servers and sign-ins

A remote server runs at its vendor, and the QuickAgent reaches it at its https:// address, such as https://mcp.linear.app/mcp. Its row says how it signs in:

  • OAuth. Before the first run, whoever runs the QuickAgent signs in at the vendor and allows the scopes the row lists, in the run setup's Connect tools step (Hosted runs). Leave the scopes empty to take the ones the vendor asks for.
  • A key. The row names one key, which is sent to the vendor as a bearer token. It is declared like any other key, so whoever runs the QuickAgent supplies it.
  • Nothing. The server needs no sign-in.

The address is https:// on a public host name, on port 443, with no user name, query or fragment in it, and its host is the only one the server reaches. Agentry checks the address and what the server asks for, not the vendor's code; the pipeline reports each remote server by its address when you submit.

A server from npm or PyPI that works with a person's own account takes a sign-in in its row: the OAuth issuer it signs in with, the scopes, and how the access token reaches the server. Token files are written into a folder of the server's own, one path: template per line; a template may use {access_token}, {expiry} and {expiry_ms}. Token settings are environment variables, one NAME=value per line; a value may use {access_token} and {dir}, the token folder's path. A Gmail server from PyPI, workspace-mcp, takes the issuer https://accounts.google.com, the scope https://www.googleapis.com/auth/gmail.readonly, the setting WORKSPACE_MCP_CREDENTIALS_DIR={dir} and a token file whose template is the JSON it reads, {access_token} in place of the token. The package format has the whole example, and the servers that cannot sign in this way, each with the one to declare instead.

A run gets the access token and nothing else: never a refresh token or a client secret. A token file's template is packed with the QuickAgent, and anyone who can download it can read it, so a client id or secret the server's file needs is a dummy such as agentry, never a real one, and no template holds a real token. The summary lists each server's address or package, how it signs in and what it asks for, before you submit.

Required and optional keys

Each key the QuickAgent or one of its servers declares is Optional or Required. A run starts without an optional key it was not given, and the QuickAgent is told which keys it went without. A run without a required key is refused before it starts. Mark a key Required when the QuickAgent cannot do its job without it: a key for a higher rate limit, or for a paid search beside a free one, can stay Optional.

A key you attach starts as Optional. Files, commands and data shows a choice for each key, which writes capabilities.optionalSecrets in agent.yaml; without the page's script, the same choice is a field naming the Required keys. A draft or a release you edit comes in with the marking it already has, and a release published without optionalSecrets comes in with every key Required, as it runs. A secret question is required exactly when the key it fills is. Moving a key between Optional and Required asks nobody who installed the QuickAgent to consent again: the key's name, and where it goes, do not change.

Before it packs anything, the form checks each field against the rule the registry's validator applies to it: names, versions, hosts, paths, tags, the data categories, secret names, each server's configuration and the guide's limits. The registry still decides on submit, and agentry validate also checks what the form does not, such as the instruction file's front matter.

Describe it

Describe it drafts a QuickAgent from what you say it should do. The page takes one description, with three optional hints folded under it: the services or sites it works with, whether it runs on its own or in a conversation, and an example of the output you want. Press Draft it and Agentry runs the Drafter, a QuickAgent built into Agentry's runner, on its own infrastructure for your credits. Draft it and Submit are the two presses the whole path takes.

  • What it costs. The page states the draft's hold before you press the button, in the registry's own numbers: the model's work up to the hold, the web searches it makes up to the registry's limit and at its price, and 1 credit for AI Review, never more than it holds. A draft settles from what it used; one that never ran is refunded in full.
  • Knowledge, if you keep some. Under the description you can pick knowledge packs you keep in Agentry, or your organization shares, up to 10 MB in all. The Drafter reads them before it searches the web: it learns the domain from them and writes what the QuickAgent needs into its instruction, so the draft is better and may need fewer searches. Where the QuickAgent needs a pack when it runs, the draft asks for one; it never ships yours. Each pack was scanned when you stored it, and the Drafter leaves out what that scan flagged. A pack whose scan did not read all of it cannot be used until you upload it again.
  • A repository or a web address. When the QuickAgent works on a codebase, or on a file at an address you give each time, the draft asks for it with a repository or a url question instead of an upload. It declares no network and no key to fetch it, because the runner fetches it before the run (runs that read a repository or a web address). An API the QuickAgent calls about it, such as a vulnerability database, still appears in its network list.
  • Where your words go. Your description and the Drafter's searches go to a search provider, to AI Review (TypeSafe's Jev) and to the sites the Drafter reads, so the description should hold no secret. AI Review reads every result, page and registry answer before the Drafter's model does, and holds back what it flags or cannot scan. A description AI Review does not pass stops the draft before it starts.
  • Following it. The draft's page is a run page: queued, running, done. When it is done, your browser reads the draft out of its output and opens it in the Builder, on the summary. It does that by itself in the tab that watched the draft run; anywhere else, or when this browser keeps an unfinished draft the new one would replace, it waits for you to press the button, and it says when it would replace one. After Describe again, the new draft replaces the one it came from without that second press, since asking for it was the press. The site's server never reads the output.

The instruction the Drafter writes is for a QuickAgent that will most likely run with no network and no search, so it carries the domain knowledge the run cannot look up. It has six parts: Role, Inputs, Steps, Output, Background (the facts, definitions, formats, thresholds and worked examples the steps rely on) and Checks (missing input, edge cases, and what the result must pass). It is as long as the task needs, up to 32 KiB.

What the Drafter wrote reaches the Builder only as values in the form's own fields. Fields the Builder cannot hold are left out and named, and a draft with a value of the wrong shape or past its limit is not opened at all (the whole output is still yours to download). The Drafter decides what depends on the task: the name, tags, run modes, data access and the contract. The Builder sets the rest, whatever the draft said, and the notes name each change: your namespace; version 0.1.0; the MIT licence, unless your own description names another; and a name none of your QuickAgents already has (weekly-issues-2 when you have a weekly-issues).

The summary shows what the draft needs. Review, in the form views, keeps the Drafter's notes folded under How it was drafted:

  • the published QuickAgents that already do the job, each with Install instead;
  • the sources it read, a page of one of your packs as pack:<name>/<page>, and each one AI Review withheld, from the web or a pack, with the reason; a withheld source is never a link;
  • the questions your description left open;
  • the rules the draft still fails, as the Drafter's own check found them;
  • what the Drafter checked of the draft's commands and MCP servers. A draft declares only the commands every run provides, and each MCP server it pins is held to two lists in the Drafter's own guide: Runs here and Does not run here, what a survey saw in the runner. A server on Does not run here, or one built on a package that list names, is sent back for one more try, like a rule the draft breaks. The notes then say what admitted each server the draft keeps (its Runs here entry, or the Drafter's judgement for a server on neither list), and list a server or a command still to fix, a server with an install script to check before a run, and a server whose registry could not be read. The lists are what was seen, not a judgement of any server, and a server on neither list may be kept (what the Drafter checks);
  • every host the draft reaches that your description did not name. Check each one: a host nobody asked for is what an injected page would add;
  • AI Review's check of the finished draft: the Drafter asks AI Review to read the draft as the pipeline will at publish, and whether it does what you described. The summary gives it one line, and the notes list each finding, its file and its rating. A high finding sends the version to a person for review when you submit, not to refusal. On its own, a medium one does not hold the version: it is shown on the report. The pipeline does not ask whether the draft does what you described, so that answer never holds the version. What you change in the form afterwards is checked only at submit.

The notes are rendered as the run page renders an agent's output: no HTML, no images, and a link only to another site. Every step stays editable, and nothing is submitted until you press Submit on the summary, which goes through the same pipeline as any submission. Describe again, on Review, starts a new draft from the draft as it stands and a note on what should change. The draft's agent.yaml and AGENT.md go with your note, to the same places a description goes, and it is held and paid for like the first. The notes stay with the draft in this browser and go when it does.

What the two buttons do

Both pack agent.yaml, your instructions, a generated README, and a LICENSE into the archive, and each knowledge pack you ticked under knowledge/<name>/. When the license field says MIT — the default — the LICENSE is the MIT text with your namespace as the copyright holder. For any other SPDX id the file names that license and points at its text on spdx.org; the Builder carries no other license text, so replace the file with the full text before publishing if the license asks that it accompany the work.

Download stops there and gives you the file. Submit uploads it over the same path the CLI uses. On the hosted registry a submission spends credits from your subscription tier, 1 by default; the page says how many you have. One the balance cannot cover is refused before anything is stored. The pipeline decides from there and the QuickAgent's page shows the verdict. A version whose findings are low or medium publishes, with every finding on its report. A high finding sends it to a person for review, and a critical one is rejected outright. An organization's policy can hold medium findings too.

Anything the scanner could not read goes to a person. A declared MCP server with no vulnerability data is a medium finding: the version still publishes, and the daily sweep asks again.

For QuickAgents with code, additional files, or a repo history, use the template and agentry publish, or the desktop app's Build tab. Both take the same pipeline, and both let the package carry more than the files this form writes.