Agent Builder

The Agent Builder at /agents is the single most important screen on AgentSwarms, because almost everything else on the platform either is an agent, is composed of agents, or is a tool for inspecting and improving agents. An agent here is a complete, self-contained AI worker — a system prompt plus a model plus optional tools plus optional memory plus optional guardrails — that can be chatted with in the playground, embedded as a node in a swarm, exported as runnable LangChain or LangGraph code, or published to the community marketplace. The rest of this page walks through every configuration block in detail, in the order they appear in the form.

Creating an agent

Clicking New Agent opens a dialog with the full configuration form. The form is organized into clearly labelled sections, every field has inline help text, and the form auto- saves a draft every few seconds so you can close the dialog and come back without losing work. New agents start with the AgentSwarms AI provider selected by default, which means you can save and chat with a working agent within about thirty seconds of clicking the button, without configuring anything.

Identity

The identity section sits at the top of the form because the decisions you make here propagate everywhere the agent is referenced — in swarm node tooltips, in playground dropdowns, on community listings, and in the trace viewer. A few minutes spent getting the identity right pays off every time you have more than a handful of agents and need to find one in a hurry.

• Name is the primary identifier and should be descriptive enough to identify the agent at a glance. "Insurance Claim Triage v2 (Strict)" is a name; "Agent 17" is a regret waiting to happen.
• Description is a free-text summary surfaced on the agent card, in swarm tooltips, and in the community listing when published. Treat it as the elevator pitch for the agent: what it does, what it is good for, and what it is explicitly not for.
• Avatar or icon can be an emoji or an uploaded image and is purely cosmetic, but it makes long lists of agents much easier to scan.
• Active toggle controls whether the agent shows up in the playground and swarm pickers. Inactive agents are not deleted and retain all their configuration; toggling them off is the right move for half-built or deprecated agents that you do not want to delete but also do not want cluttering your pickers.

Model

The model section selects which underlying language model the agent uses, with what sampling parameters, and what to do when that model fails. Picking the right model is one of the single biggest determinants of agent quality and cost, and the form is designed to make that choice easier rather than to bury it under defaults.

• Provider picks the upstream model vendor: AgentSwarms AI (the default, no key required), OpenAI, Anthropic, Google Gemini, Grok (xAI), Azure OpenAI, AWS Bedrock, Google Vertex AI, OCI Generative AI, Alibaba Qwen, custom Ollama, or self-hosted vLLM. Switching providers re-filters the model picker; the previously-selected model is remembered per-provider so you do not lose your last choice when you toggle back.
• Model is filtered by the selected provider and enriched with live data from the Model Registry: context window size, price per million input and output tokens, whether the model supports tool calling, whether it supports structured output, and a small quality-tier badge.
• Temperature controls randomness. Set it to zero for deterministic tasks like SQL generation or classification; set it to 0.7 or higher for creative tasks like draft writing. The form shows a small preview of how the parameter changes example outputs from the selected model so the choice is informed rather than arbitrary.
• Maximum output tokens caps the length of a single completion. The cap exists primarily as a cost-control measure: a runaway tool loop that calls a model with no cap can rack up surprising bills, and a sensible cap is the first line of defence.
• Top-p, frequency penalty, and presence penalty are exposed for the providers that support them, with the standard defaults pre-selected so you can ignore them entirely if you do not have a strong opinion about them.
• Fallback model is the model the agent automatically retries on when the primary model errors, rate- limits, or hits a safety filter. The fallback can be on the same provider or a different one entirely, which is the most reliable way to keep an agent working through a provider outage. The playground's fallback dialog tells you in real time exactly when the fallback kicked in and why.

System prompt

The system prompt is the text that frames the model's behaviour for every conversation. It is the single most important configuration choice for any agent, and the editor reflects that: it is a full-height code editor with syntax highlighting, a live token counter, and a one-click insertion path from the Prompt Library for starter prompts. The editor also supports double-brace template variables which are filled in at runtime from chat input, upstream swarm nodes, or approval payloads, so the same prompt can be reused across many contexts without copy-paste drift.

Knowledge bases

Any agent can be attached to one or many knowledge bases from/knowledge. A knowledge base is a vector index, built on the same Lovable Cloud database that powers the rest of the platform using pgvector, and it can be populated from a range of sources. The moment you attach a knowledge base, the agent automatically gains a search tool scoped to that knowledge base — no separate tool configuration required.

• URL crawls can ingest a single page or a full site with configurable depth and include/exclude path filters. The crawler respects robots.txt by default and is rate-limited to be a polite citizen.
• GitHub repository ingestion takes a repo URL and a set of file globs (for example "src/**/*.md") and indexes the matching files, refreshing on a schedule you control.
• File uploads support PDF, DOCX, Markdown, plain text, and CSV. Files are parsed, split into chunks, and embedded automatically; the process status is shown live in the knowledge base detail page.
• Raw text paste is the fastest path to a small knowledge base — useful for short policy documents or FAQ snippets where setting up a full ingestion source would be overkill.
• Knowledge graph view on the knowledge base page renders the relationships between chunks visually, which is the best way to spot retrieval coverage gaps before they embarrass the agent in production.

Skills

Skills are reusable, parameterised capabilities — either prompt- based or code-based — that you build once in theSkill Builder and attach to any agent. From the agent's perspective, an attached skill shows up as a callable tool with a name, a description, an input schema, and an output schema. The model decides at runtime when to call it, just as it would any other tool. Skills are the right unit of reuse when the same small capability — "summarise this in three bullet points", "extract invoice fields as JSON", "translate to formal legal English" — keeps showing up across multiple agents.

Tools

Tools are the agent's interface to the world outside its own context window. The tool catalogue is intentionally broad because real agentic systems are mostly defined by what they can do rather than by what they can say, and every entry below is a production-grade implementation rather than a stub.

• Web search performs a live search query against a curated search index via the AgentSwarms gateway, returning titles, URLs, and snippets the agent can cite.
• URL fetcher and web scraper uses Firecrawl under the hood to retrieve and clean a page's content, returning markdown the agent can reason about directly rather than raw HTML.
• Knowledge base search is added automatically for every attached knowledge base and surfaces the top-k most relevant chunks for the agent's query, with metadata that lets the agent cite its sources.
• SQL query tool generates and executes SQL against a configured set of tables — see the SQL tables subsection below for the full safety architecture.
• HTTP request is a generic outbound HTTP tool with allow-listed domains, configurable method, headers, and body templates. Useful for calling any internal API you maintain.
• Code interpreter runs short snippets of JavaScript inside a sandboxed runtime with no network access and a small memory and time budget. Indispensable for arithmetic and small data transformations the model cannot reliably do in its head.
• Image generation routes to the gateway's image models and returns a hosted image URL the agent can embed in its reply.
• Embeddings exposes an embedding-only tool for agents that need to compute similarity between texts as part of a larger reasoning step.
• Memory tools let the agent explicitly read from and write to its long-term memory store, which is scoped to the current user across all of that user's sessions.
• Custom MCP tools come from any Model Context Protocol server you have connected at /mcp; attaching the MCP server adds every tool that server exposes to the agent's catalogue.
• Generated tools are tools you describe in plain English, which the platform then drafts as a typed wrapper. You review and edit the draft before it becomes callable. Very useful when you know the API you want to wrap and would rather not write the boilerplate yourself.
• Human-in-the-loop approval wrappers can be applied to any tool. The wrapped tool, when called, pauses the run and posts an approval card to your dashboard inboxcontaining the exact arguments the agent wants to call the tool with; the run resumes only after you approve, reject, or edit-and-approve.

SQL tables for text-to-SQL agents

Enabling the SQL tool unlocks a dedicated sub-section where you choose exactly which database tables the agent is allowed to see and query. The runtime then enforces those choices with multiple layers of safety, and this section is worth understanding in depth because text-to-SQL is one of the patterns most prone to going badly wrong in production.

• Table allow-list determines which tables can appear in generated SQL. Tables outside the allow-list are invisible to the agent — they do not appear in the schema context sent to the model, and the SQL validator rejects any generated query that references them.
• SQL AST validation parses the generated SQL before execution and rejects any query containing data- definition statements, data-modification statements, or references to tables outside the allow-list. This catches attacks that the model itself was prompt-injected into emitting, not just honest mistakes.
• Row-level security enforcement ensures every query is executed as the current user, not with elevated service-role credentials. The model never sees rows the user would not otherwise be able to read.
• CSV upload to queryable table lets you upload a CSV file from the SQL Tables sub-section and have it automatically turned into a queryable table with inferred column types, so you can prototype text-to-SQL agents without touching a real database.
• Semantic layer descriptions let you attach natural-language column descriptions and a business glossary to each table. These descriptions are inserted into the prompt context the model sees, dramatically improving the quality of generated SQL on real-world schemas where column names are not self-explanatory.

Guardrails

Guardrails are the safety-net configuration for agents that need to behave responsibly. The guardrails sub-section is opt-in — agents with no guardrails behave exactly as if guardrails did not exist — but turning even one on adds a visible "Guarded" badge to the agent's card so you can spot the safer agents at a glance.

• Input filters screen incoming messages for prompt-injection patterns, jailbreak attempts, and off-topic queries before the model ever sees them. Blocked inputs produce a polite refusal rather than silently dropped messages.
• Output filters screen the model's response against the configured content-safety level and refuse to deliver responses that fail. The level can be set to off, lenient, standard, or strict, with sensible defaults per industry vertical when the agent is provisioned from a template.
• PII blocker uses a combination of regex patterns and a lightweight classifier to detect emails, phone numbers, social security numbers, and similar personally- identifiable information in the agent's outputs, redacting them before delivery.
• Approval requirements can be applied either to all tool calls or to specific tools individually. Useful for high-stakes tools like database writes, payment processing, or outbound email.
• Per-agent budget cap stops the agent from accepting new runs once it has spent more than the configured dollar amount in a rolling twenty-four-hour window, even if your overall account budget has room. Useful for limiting the blast radius of any one agent.

Memory

Memory in AgentSwarms is split into three layers, each with a different lifespan and a different purpose. You do not have to opt into any of them — agents work fine with no long-term memory — but understanding how they layer together is one of the keys to building agents that feel competent across many sessions.

• Short-term memory is the chat history within a single playground session, always enabled, and automatically truncated to fit the model's context window using a recency- weighted strategy.
• Long-term memory consists of summarised facts extracted by a background process from the user's conversations, persisted per user, and recalled at the start of every session via the memory tools. This is what gives an agent the ability to remember that "this user prefers concise answers" or "this user's company is in the insurance vertical".
• Episodic memory is the full turn-by-turn history kept in the trace store and queryable from Analytics. It is not fed back into the model by default but is invaluable for debugging and for evaluations.

Export, share, publish, import

Every agent is fully portable. The four buttons in the agent's card menu cover the four most common things you might want to do with an agent once it is built, and all four are designed to be reversible — nothing locks you into AgentSwarms.

• Export produces a downloadable file in your choice of formats: portable AgentSwarms JSON, runnable LangChain Python code, or runnable LangGraph Python code. The exported code is intentionally readable and idiomatic, not obfuscated, so you can take it directly into a Python codebase and continue developing there.
• Share generates a private link that any signed-in AgentSwarms user can use to import the agent into their own workspace. The link can be revoked at any time and imports are one-time copies — subsequent changes to your agent do not propagate to recipients.
• Publish to Community runs the agent through the publish quality check (no plaintext secrets, no PII in the prompt, a sufficiently descriptive description, an active status) and lists the agent on /community/agents where other learners can browse and remix it.
• Import on the agents page lets you drag in any previously-exported AgentSwarms JSON file to instantly recreate the agent in your workspace, including its knowledge-base attachments, skills, and guardrail settings.

              ┌─────────────────────────────────────────────┐
   chat ───▶  │   System prompt  +  short / long-term memory │
              └────────────────┬────────────────────────────┘
                               │
                               ▼
                        ┌────────────┐
                        │   Model    │  (provider + fallback)
                        └────┬───────┘
                             │
            ┌────────────────┼────────────────────────┐
            ▼                ▼                        ▼
        ┌────────┐    ┌─────────────┐         ┌──────────────┐
        │ Tools  │    │ Knowledge   │         │  Guardrails  │
        │+skills │    │ bases (RAG) │         │  + budgets   │
        └────┬───┘    └──────┬──────┘         └──────┬───────┘
             │               │                       │
             └──────────► response ◄──────────  (HITL approval)