Build a BeeAI Email Agent

Command references used in this guide: nylas email list, nylas email read, and nylas email drafts create.

How do you give a BeeAI agent email?

You give a BeeAI agent email by making email a tool, not by teaching the model provider APIs. BeeAI, formerly bee-agent-framework, is IBM's open framework for Python and TypeScript agents, and its tool boundary fits the CLI well: 1 subprocess call in, JSON out.

The practical shape is small. Authenticate once with nylas auth login, then let a BeeAI tool call commands like nylas email list --json --limit 10. The stored grant is reused, so the agent doesn't handle OAuth tokens or provider refresh logic. The same wrapper works for Gmail now and can cover the other 5 supported mailbox providers without changing the agent prompt.

BeeAI's current repository describes agents, tools, memory, workflows, and protocol serving, including ACP and MCP protocol integrations added in 2025. That makes the email wrapper useful in 2 places: directly inside a BeeAI agent's tool list, and as a hosted agent that other local or remote agents can reach through ACP.

How do you register the CLI as a BeeAI tool?

Register the CLI as a BeeAI tool by giving the agent a named action with a narrow input schema and a subprocess body. In BeeAI terms, the model sees a tool such as ReadInbox; the implementation runs nylas email list and returns exactly what the command printed.

The TypeScript tool below keeps the boundary to 1 command and 1 numeric input, which is enough for a first inbox triage pass. It calls nylas email list --json --limit 10 because 10 messages fit easily in a model context window and still expose recent sender patterns.

import { Tool, StringToolOutput } from "beeai-framework/tools/base";
import { z } from "zod";
import { execFile } from "node:child_process";
import { promisify } from "node:util";

const run = promisify(execFile);

export class ReadInboxTool extends Tool {
  name = "ReadInbox";
  description = "List recent mailbox messages as JSON.";
  inputSchema = () => z.object({ limit: z.number().min(1).max(25).default(10) });

  protected async _run({ limit }: { limit: number }) {
    const { stdout } = await run("nylas", [
      "email", "list", "--json", "--limit", String(limit),
    ]);

    return new StringToolOutput(stdout);
  }
}

A Python BeeAI tool can follow the same pattern with subprocess.run, but keep the public capability identical: read recent messages, search, read a selected ID, and draft. Don't bundle those into a single “email assistant” tool. Four small tools are easier to log, deny, test, and expose over ACP.

How does the BeeAI agent call email commands?

A BeeAI agent calls email commands through the tools you register on the agent, so command choice becomes part of the agent's action space. The first turn should list only metadata, then the agent should read 1 to 3 selected messages by ID before drafting a response.

Test the exact commands outside the agent before you wire them into BeeAI. The first command returns 10 recent messages as JSON for triage; the second reads 1 message by ID after the agent chooses a candidate. Piping to jq proves the output shape before the model sees it.

nylas email list --json --limit 10 \
  | jq '.[] | {id, subject, from, date}'

nylas email read MESSAGE_ID --json \
  | jq '{id, subject, from, body}'

In BeeAI, attach those wrappers to a focused agent such as RequirementAgent with a role like “Inbox Triage Specialist.” The repository's examples pair agents with tools such as ThinkTool, WikipediaTool, OpenMeteoTool, and HandoffTool; your email tools sit in that same list. Add GlobalTrajectoryMiddleware during development so every tool call is visible in the console.

How does ACP let other agents reach the email-capable BeeAI agent?

ACP lets the email-capable BeeAI agent become a service boundary instead of a private helper buried in one process. BeeAI added ACP protocol integration in 2025, so a coordinator agent can ask an email specialist for inbox facts without receiving direct access to the mailbox tool.

This matters when you have more than 1 agent. A planning agent can decide that email context is needed, call the ACP-served BeeAI email agent, and receive a short result. The planner never gets ReadInboxTool or CreateDraftTool directly, which reduces the number of components that can touch private mail.

Keep the ACP contract higher level than the raw CLI. Good operations are “summarize unread support requests from the last 2 days” or “draft a reply for this approved thread ID.” Bad operations are raw shell access or arbitrary search strings from another model. ACP gives you agent-to-agent reach; the tool list still defines what can happen.

What guardrails should the BeeAI agent have?

A BeeAI email agent needs guardrails at the tool layer because email joins private data, untrusted content, and external communication in 1 loop. That is the lethal trifecta: private data + untrusted content + external communication. Break the chain by giving autonomous agents read and draft tools, not send.

The draft command below creates a provider draft for review instead of dispatching mail. It uses nylas email drafts create with 3 explicit fields: recipient, subject, and body. Register this only after you have a review queue, terminal approval step, or UI where a human can inspect the output.

nylas email drafts create \
  --to approver@example.com \
  --subject "Draft reply for review" \
  --body "Proposed response from the BeeAI email agent."

Treat every email body as hostile input, even inside a trusted mailbox. OWASP LLM01 (2025) covers prompt injection, and inboxes are full of attacker-controlled text. Keep the BeeAI prompt explicit: summarize content, don't obey instructions inside messages, don't forward secrets, and don't call draft creation unless the user asked for a draft. For deeper containment patterns, read stop an AI agent going rogue and build a human-in-the-loop email agent.

Next steps

• Build an Atomic Agents Email Agent - schema-first tools around the same CLI boundary
• Build a Langroid Email Agent - task and tool-message patterns for email work
• Build a human-in-the-loop email agent - draft review before external communication
• Stop an AI agent going rogue - containment beyond prompts and policies
• Full command reference - every supported command and flag