Skip to main content

Agent Builder

Agent Builder lets you describe the agent you want in plain language and have Spec27 generate the agent code for you. It is the fastest way to connect a new agent when you do not want to start from a blank editor.

There are three ways to create an agent in Spec27:

  • Agent Builder — describe the behaviour you want and generate the code (this page).
  • Registry integrations — start from a prebuilt integration for a popular platform.
  • Writing the code yourself — author the agent directly in the code editor.

All three produce the same thing: a small JavaScript agent that takes an input, calls your system, and returns the output Spec27 evaluates.

When to use Agent Builder​

Use Agent Builder when you know what you want the agent to do but would rather not write the request/response code by hand. It is well suited to standard REST calls against your own service or a hosted model. If your platform is already in the registry, start there instead; if you need full control, write the code directly.

Generate an agent​

  1. Open Agents and start a new agent. The create page opens on the Preview tab, with an Agent Builder tab beside it.
  2. Enter a name in Name the agent.
  3. Switch to the Agent Builder tab. You will see the prompt "Describe what you want and click Build to start a conversation."
  4. In Describe the agent you want to build, write what the agent should do — the service it should call, the shape of the request, and what it should return.
  5. Select Build agent. The builder streams its work back as a conversation, and the generated code populates the editor on the Preview tab when it is ready.

You can keep the conversation going to refine the result — ask for changes and the builder updates the code.

Review and refine​

Generated code lands in the editor on the Preview tab, where you can edit it like any hand-written agent. Before saving:

  • Add any secrets the agent needs. In the Configuration panel, open the Secrets tab and select Add secret for each value (for example OPENAI_API_KEY). You declare the keys here and set their values as project secrets later.
  • Set a rate limit if needed. On the Rate limit tab, switch it On and set the maximum number of runs per time window.
  • Preview the agent. On the Preview tab, enter sample text in Input and select Run preview to run the current editor code in the sandbox without saving. Output appears under Output, with a Console tab for logs.

When the agent behaves as expected, select Create Agent.