Skip to main content

Start with an admin agent

The first agent worth building on Blue Leaf is one that builds the rest. Tell an admin agent "make me an agent that drafts replies to support emails" or "write a tool that pulls yesterday's orders", and it writes the prompt or the code, saves it to your account, tests it and tells you what it made. Setting it up takes about ten minutes, and after that most new things are one chat message away.

What it can do

  • Agents: create new ones, then refine their prompts and settings until they do the job. It tests each one by running it as a sub-agent.
  • Tools: write TypeScript tools that run in Blue Leaf's sandbox, test them, and fix them when they break.
  • Knowledge: write and update Markdown documents in /workspace/docs, which any of your agents can read.
  • Schedules: set an agent to run on a timetable, like a morning report or a nightly cleanup.
  • Files: read and write anything in your workspace, including other agents' prompts and settings.

Almost all of this uses tools every Blue Leaf agent already has: Create_Tool, Run_tool, Execute_Code for files, Get_Resource for documents, and Invoke_Agent to run another agent. The only gap is account management (creating agents and adding schedules), which goes through your account's API. You'll give the admin agent one small tool for that.

For everything else it reads the platform docs, which are also published as one Markdown file at https://www.blle.co/docs.md and kept current. Its prompt tells it to fetch that file whenever it needs details, so it keeps up as the platform changes.

graph LR
    You -->|chat| Admin[Admin agent]
    Admin -->|Create_Tool, Run_tool| Tools[Your tools]
    Admin -->|Execute_Code| Files[Files, docs, agent prompts]
    Admin -->|blle_admin| Account[New agents, schedules]
    Admin -->|Invoke_Agent| Test[Tests the agents it builds]

Step 1: Add two secrets

On the Secrets page, add:

Name Value
ANTHROPIC_API_KEY the API key for the model your agents run on (name it after your provider)
BLLE_API_KEY your Blue Leaf API key, from the Account page

The admin tool uses BLLE_API_KEY to create agents and schedules for you. Secrets are encrypted, and tools read them by name, so the key never appears in a prompt or in code.

Step 2: Create the admin agent

On the Agents page, create an agent called Admin with this prompt:

# Admin

You help me build and run things on my Blue Leaf account: agents, tools, knowledge documents and schedules. I describe what I want; you build it, test it and tell me what you made.

## How my account is laid out

- **Agents** are folders in `/workspace/agents/<folder>/`: `AGENT.md` is the prompt, `agent.json` the settings. Create, list and delete them with the `blle_admin` tool. To change an existing agent, edit its two files with `Execute_Code` (`context.fs.read` / `context.fs.write`); the next run uses them.
- **Tools** are TypeScript that runs in a sandbox, one file each in `/workspace/lib/tools/<name>.ts`. Use `Search_Tools` and `Get_Tools` to see what exists, `Create_Tool` / `Update_Tool` to write them, and `Run_tool` to test them.
- **Knowledge** is Markdown in `/workspace/docs/`. Any agent can read a document with `Get_Resource`, using its path under `/workspace/docs` without the `.md` as the key.
- **Secrets** (API keys) are listed with `Manage_Secrets`. Tools read them as `Deno.env.get("NAME")`; agent settings name them, e.g. `"apiKey": "ANTHROPIC_API_KEY"`.
- **Public files** go in `/workspace/public/`; anyone with the link can open them.

For anything else (API endpoints, agent settings, limits, runners, secrets), read the current platform docs: fetch https://www.blle.co/docs.md with `Execute_Code`. They are kept up to date; when they and this prompt disagree, follow the docs.

## The blle_admin tool

Call it with `Run_tool`, tool name `blle_admin`:

- `{"action":"list_agents"}`
- `{"action":"create_agent","name":"...","prompt":"<full AGENT.md>","settings":{...}}`
- `{"action":"delete_agent","id":123}`, using the numeric `id` from `list_agents`
- `{"action":"add_schedule","agent_id":"<uuid>","name":"...","prompt":"...","cron":"0 7 * * 1-5"}`. Cron is minute hour day month weekday, Central time. Changing, pausing or deleting a schedule is done on the Schedules page.

## Building an agent

1. Agree on its job with me in a sentence or two, then write a focused prompt: its role, the steps it follows, which tools it uses and what it should never do.
2. Settings: copy `provider`, `model`, `apiKey` (and `baseURL` if present) from your own `agent.json` unless I ask for something else. To give it my tools, add an `mcpServers` entry (no API key needed). To limit it to certain tools, put `tool_configuration` inside that server entry, never at the top level:
   `"mcpServers": {"blle": {"type": "url", "url": "https://api.blle.co/mcp", "tool_configuration": {"allowed_tools": ["Get_Resource", "Run_tool"]}}}`
3. Create it with `blle_admin`, then test it with `Invoke_Agent` on a realistic request. Fix the prompt and test again until it does the job.

## Building a tool

Write a module that exports `async function run(context)`. Parameters arrive on `context`; `context.fs` reads and writes `/workspace`; `fetch` is available; import npm packages from `https://esm.sh/<package>@<major>`. Return a JSON-friendly result. A tool call has a 5-minute limit, so long work is split across calls. Test every tool with `Run_tool` before telling me it's done.

## Rules

- Never ask me to paste an API key into this chat. Tell me which secret to add on the Secrets page, and its exact name.
- Ask before deleting or overwriting anything you didn't create in this conversation.
- When you finish, say exactly what you created or changed (names, paths, ids), and how you tested it.

And these settings. Swap in your own provider and model; a strong model pays off here, because this agent writes code and prompts:

{
  "provider": "claude",
  "model": "claude-sonnet-4-6",
  "apiKey": "ANTHROPIC_API_KEY",
  "mcpServers": {
    "blle": { "type": "url", "url": "https://api.blle.co/mcp" }
  }
}

The mcpServers entry gives the agent all of Blue Leaf's built-in tools and every tool you add. It needs no API key: an agent running on Blue Leaf reaches your own MCP server as you.

Step 3: Give it the admin tool

Open a chat with your Admin agent and send: "Create a tool named blle_admin with the description 'List, create and delete agents; add schedules' and exactly this code:", followed by the code below.

// blle_admin — the account actions an agent can't do with the built-in tools:
// list, create and delete agents, and add schedules.
//
// Secret: BLLE_API_KEY (your API key, from the Account page)

const SITE = "https://www.blle.co";

async function call(path, method, form) {
  const res = await fetch(`${SITE}${path}`, {
    method,
    headers: { Authorization: `Bearer ${Deno.env.get("BLLE_API_KEY")}`, "User-Agent": "Mozilla/5.0 blle-admin" },
    body: form ? new URLSearchParams(form) : undefined, // sent as a form
  });
  const text = await res.text();
  let data;
  try {
    data = JSON.parse(text);
  } catch {
    throw new Error(`${path}: HTTP ${res.status}, not JSON (the site's firewall may have refused the request)`);
  }
  if (!res.ok || data.success === false) throw new Error(`${path}: ${data.message ?? data.error ?? `HTTP ${res.status}`}`);
  return data;
}

export async function run(context) {
  const { action } = context;

  if (action === "list_agents") {
    const { agents } = await call("/api/agents", "GET");
    return agents.map((a) => ({ id: a.id, uuid: a.uuid, name: a.name, folder: a.folder, version: a.version }));
  }

  // Create the agent with a placeholder, then write its real prompt and
  // settings as files: prompts full of code or URLs never pass through a
  // web form, and the next run uses the files.
  if (action === "create_agent") {
    const { name, prompt, settings } = context;
    if (!name || !prompt || !settings) throw new Error("name, prompt and settings are required");
    const { agent } = await call("/api/agents", "POST", { action: "add", name, prompt: `# ${name}` });
    const dir = `/workspace/agents/${agent.folder}`;
    await context.fs.write(`${dir}/AGENT.md`, prompt);
    await context.fs.write(`${dir}/agent.json`, JSON.stringify(typeof settings === "string" ? JSON.parse(settings) : settings, null, 2));
    return { id: agent.id, uuid: agent.uuid, name: agent.name, folder: agent.folder };
  }

  if (action === "delete_agent") {
    if (!context.id) throw new Error("id (the numeric id from list_agents) is required");
    return call("/api/agents", "POST", { action: "delete", id: String(context.id) });
  }

  // cron: minute hour day month weekday, Central time.
  if (action === "add_schedule") {
    const { agent_id, name, prompt, cron } = context;
    if (!agent_id || !name || !prompt || !cron) throw new Error("agent_id (uuid), name, prompt and cron are required");
    return call("/services/chatbot/schedules", "POST", { action: "add", agent_id, name, prompt, cron_expression: cron, enabled: "1" });
  }

  throw new Error("action must be list_agents, create_agent, delete_agent or add_schedule");
}

create_agent makes the agent through your account's API with a placeholder prompt, then writes the real prompt and settings as files. Prompts often contain code or URLs, which can trip the website's security filter when sent as a form; files avoid that.

Then ask it to check its own setup: "List my agents with blle_admin." If it lists the Admin agent, everything is connected.

Step 4: Ask for things

Talk to it like you'd brief a colleague. When I tested this setup, my first message was:

Set me up with a small test: a tool word_stats that takes text and returns word count, sentence count and the 3 most common words longer than 4 letters; a knowledge document /workspace/docs/style-guide.md with three short writing rules; an agent "Editor" that reads the style guide, runs word_stats on a paragraph and returns an edited paragraph with before-and-after stats; and a schedule for that agent. Test the tool and the agent before you tell me it's done.

In under a minute it wrote the tool and ran it on a sample paragraph (23 words, 3 sentences, the right top words), saved the style guide and checked that an agent could read it, and created the Editor agent with access to just the two tools it needs. It then ran the Editor on a sample paragraph, which came back rewritten in the active voice, cut from 23 words to 13, with both sets of stats. Last, it added the schedule. Its reply listed every name, id and path it had created, and how it had tested each one.

Some other first requests that work well:

  • "Make an agent that turns my meeting notes into a summary with action items, and save my team's names and roles as a knowledge document it can use."
  • "Write a tool that fetches the current weather for a city, then make a 7am weekday schedule that emails me the forecast." (It will tell you which secret an email service needs.)
  • "Look at my Support agent's prompt and tighten it: it keeps apologising too much."
  • "Build the podcast digest agent from your blog."

Good to know

  • It reads the live docs. For anything its prompt doesn't cover, it fetches the platform docs as one Markdown file, /docs.md, which we keep current. When the platform changes, your admin agent picks it up without a new prompt.
  • It never sees your secret values. When something needs an API key, it tells you the secret name to add on the Secrets page.
  • It asks before deleting anything it didn't make in the same conversation, and you can tighten that rule in its prompt.
  • Schedules: it can create them; to pause, change or delete one, use the Schedules page.
  • Everything is versioned. Every agent save keeps the previous prompt and settings, and Update_Tool keeps the previous code, so a bad change is easy to undo.
  • It's yours to change. Its prompt is a file at /workspace/agents/admin/AGENT.md (the folder follows the name you gave it). Add your own conventions, like naming rules, a default model, or where reports should go, and it will follow them from then on.

Need help with your project or have questions?

We specialize in AI automation, custom integrations, and intelligent workflows tailored to your business needs.

Whether you need help deploying, building, implementing, or creating a solution - or just want expert guidance on your project - we're here to help.

Contact us today to discuss your project.