Aramb Agents

Aramb Agents Toolkit

The aramb_mcp.agents_* tools manage the organization's product agents — the personas end-users chat with. Each agent carries a versioned config (name, system prompt, greeting, mode, skills, disabled tools, conversation starters) with a single mutable draft and immutable published versions; end-users always get the published version.

CRITICAL: mcporter syntax rules

• ALL arguments MUST use key="value" format.
• Do NOT use --output — it is not supported by mcporter call.
• Array arguments (skills, disabled_tools, conversation_starters) take a JSON array string, e.g. skills='["skill-a","skill-b"]' or conversation_starters='["Draft a launch email","Summarize this PDF","What can you do?"]'.

Which tool, when

• The design is settled and the user wants a NEW agent to exist → aramb_mcp.agents_create. Create only AFTER the persona is agreed — name and the full system prompt are required. Never create speculatively mid-brainstorm; iterate on the design in conversation first. Only call create when there is genuinely no agent yet in the conversation.
• You are already operating on / within an existing agent (an agent is already in context, being edited or built out) → aramb_mcp.agents_update, NOT create. When a change lands and there is already an agent you're working on, revise THAT agent — do not spin up a brand-new one. A second agent for work that belongs on the current one is a duplication bug.
• Before creating anything → aramb_mcp.agents_list. If an agent with the same purpose already exists, update it instead of duplicating.
• Before ANY revision → aramb_mcp.agents_get. The stored draft is the source of truth, not this conversation — someone may have edited the agent elsewhere since you last saw it. Read, then patch.
• The user wants a change → aramb_mcp.agents_update. This is a partial merge onto the DRAFT: pass only the keys that change. Saving a draft does NOT change what end-users see.
• The change should go live → aramb_mcp.agents_publish. Publishing snapshots the draft as a new immutable version and makes it what end-users get. Treat this as a deliberate, user-confirmed step — draft freely, publish on an explicit "ship it".
• You need to see how the agent actually behaves with users → read its real conversations before judging or revising a persona (the analyse-conversation skill). Ground the change in what users actually said and how the agent replied, not a guess.
• You want to prove a change with a repeatable, scripted test → author and run a multi-turn test suite (the agent-tests skill).

Authoring the persona — system prompt, soul, AND agents doc

aramb_mcp.agents_create / update carry the whole persona, not just one prompt field. For a real domain agent, author its soul and (when its operating flow is non-trivial) its agents doc — leaving them empty ships the platform's domain-neutral defaults, which is rarely what a purpose-built agent wants.

• system_prompt (required on create) — the agent's full persona / system prompt, verbatim. system_prompt_mode: replace (default) sends it as the entire system prompt; append keeps the runtime preset.
• soul — the agent's SOUL.md: who it is, its personality and behavioural voice, its disposition and boundaries. Delivered to the container as a file. Empty ⇒ platform default (domain-neutral). Author this for any agent with a real character — a warm support triager, a terse ops bot, a careful medical-intake screener read very differently, and the soul is where that lives.
• agents_doc — the agent's AGENTS.md: its operational playbook — how it works, the order it does things, when to reach for which tool, how it handles edge cases. Delivered as a file. Empty ⇒ platform default. Author this when the agent's job is more than one-shot Q&A (a multi-step routine, tool sequencing, hand-off rules).
• conversation_starters — the agent's opener: a JSON array of exactly 3 short, concrete, task-shaped prompts shown as clickable pills on a new conversation; clicking one sends it as the user's first message. Each specific to what THIS agent actually does well — not generic filler — so a first-time user sees the agent's range at a glance. Author 3 — never more. (The platform cap at save is 6, each ≤200 chars; 3 is the authoring rule, not the ceiling.) Prefer these over a greeting — they show what the agent can do and cost no model call. Empty ⇒ none shown. Pass as a JSON array string, e.g. conversation_starters='["Draft a launch email","Summarize this PDF","What can you do?"]'. See The opener below for the full model.

Both are snake_case on the main persona (soul, agents_doc). Do not confuse them with the workflow sub-agent shape inside agent_specs, which uses camelCase soul / agentsDoc (create-agent / aramb-workflows skills) — those author a workflow node's sub-agent, these author the product agent itself.

# Author the main persona with a soul and an operating playbook, not just a prompt.
npx mcporter call aramb_mcp.agents_create name="Support Triage" \
  system_prompt="You triage inbound support and route each ticket to the right queue…" \
  soul="You are calm and concise. You never guess a policy — you check the KB or say you'll find out…" \
  agents_doc="1. Read the ticket. 2. Classify: billing / bug / how-to. 3. If billing, check the refund-policy KB before replying. 4. Route with a one-line rationale…"

# Patch just the soul later — partial merge, other fields untouched.
npx mcporter call aramb_mcp.agents_update agent_id="<AGENT_ID>" soul="You are warmer now — open with a short acknowledgement before triaging…"

The opener — starters beat a greeting, and both are free

A new conversation opens with either conversation starters or a greeting — never both — and neither costs a model call. Getting this right is the difference between a first-time user seeing what the agent can do and burning credits before they've asked anything.

• Conversation starters are the PREFERRED opener. They render as clickable pills on a new conversation; clicking one sends it as the user's first message. Author exactly 3 short, concrete, task-shaped examples of what to ask this agent — the console's own hint is "Add at least 3 to guide new conversations.", so 3 is both the floor that guides a new user and the ceiling that keeps the empty state scannable. Do not author 4 or more, even though the platform accepts up to 6. Caps enforced at save time: max 6, each ≤200 characters — stay within them or the tool rejects the payload.
• The greeting is a canned literal rendered by the chat surface, shown only when the agent has no starters. It is not a prompt instruction and not model output, so it cannot adapt to context — do not write greetings like "Welcome back, I see you were working on…"; the surface renders a fixed string. Empty greeting ⇒ the platform's default is used.
• Neither an opener nor a resume costs a model call. Showing the pills, showing the canned greeting, and resuming an existing conversation are all rendered by the surface with zero model calls. This is the whole point of the opener model: a user should never spend credits before their conversation actually starts.
• Starters and greeting are mutually exclusive at render time — when starters exist the surface shows pills and no greeting text. So an agent with good starters does not need a clever greeting; put the effort into the starters.

Propose starters when you draft a product agent

When you create or update a product agent, propose starters derived from the agent's actual job and confirm them with the user the same way you settle the system prompt — don't leave them empty. Keep each one concrete and task-shaped, not "Ask me anything" and not "Hello". For a spending assistant, for example:

• "Summarise my August spending"
• "How much did I spend on Food & Dining?"
• "What did I spend at Amazon last month?"

Pass them as a JSON array string (the mcporter array form):

conversation_starters='["Summarise my August spending","How much did I spend on Food & Dining?","What did I spend at Amazon last month?"]'

Evaluate and test — separate skills

Two capabilities that used to live here now have their own skills. Both are still the aramb_mcp.agents_* toolkit; they were split out so each is a focused, self-contained playbook:

• Read the agent's real conversations (evaluate from evidence → improve) → the analyse-conversation skill (aramb_mcp.agents_conversation_search / conversation_get). This is also where the console's Analyze button lands.
• Author and run scripted test suites against a persona → the agent-tests skill (aramb_mcp.agents_test_*). Tests must script at least 3 user turns.

Both feed the same get → update → publish loop below: read a conversation or run a test, judge it, patch the draft, publish when confirmed.

Knowledge Base — list / add / remove docs (aramb_mcp.agents_kb_*)

An agent can carry a Knowledge Base: documents the persona draws on at runtime. You are no longer limited to pointing the user at the console — for the text/markdown docs you author yourself, manage the KB directly with these verbs. They are fenced to the calling agent's organization like every other aramb_agents call.

• aramb_mcp.agents_kb_list (agent_id) — list the agent's KB documents. Returns {documents: [{doc_id, filename, folder, content_type, size, created_at}]}. Call this first to find a doc_id before kb_remove, or to pick which docs should travel into a template.
• aramb_mcp.agents_kb_add (agent_id, filename, content, optional folder) — add a KB document from inline text. Only .txt and .md filenames are accepted: the content is passed inline as text, so binary formats (PDF, DOCX, …) are NOT supported through this verb. Use it for KB docs the Architect itself authors (markdown / plain text). For a PDF, DOCX, or any binary document, tell the user to upload it via the console (Knowledge Base → Add document).
• aramb_mcp.agents_kb_remove (agent_id, doc_id) — remove one KB document by the doc_id from kb_list. Idempotent — an unknown doc_id still succeeds. The doc drops from the agent's containers on the next sync.

# List the KB, author a new markdown doc inline, then remove one by id.
npx mcporter call aramb_mcp.agents_kb_list agent_id="<AGENT_ID>"
npx mcporter call aramb_mcp.agents_kb_add agent_id="<AGENT_ID>" filename="refund-policy.md" content="# Refund policy\n\nRefunds are honored within 30 days of purchase." folder="policies"
npx mcporter call aramb_mcp.agents_kb_remove agent_id="<AGENT_ID>" doc_id="<DOC_ID>"

Export the agent as a reusable template (aramb_mcp.agents_export_template)

• aramb_mcp.agents_export_template (agent_id, slug, name, optional description, category, tags, publish_first, include_knowledge_doc_ids) — export the agent into the shared catalog as a reusable template. publish_first defaults true — it publishes the agent's current draft before exporting, so the template captures a live version. include_knowledge_doc_ids (a comma-separated list of doc_ids from kb_list) chooses which KB docs travel into the template; omit it and the template carries no knowledge.

npx mcporter call aramb_mcp.agents_export_template agent_id="<AGENT_ID>" slug="support-triage" name="Support Triage Agent" description="Triages inbound support and routes to the right queue." category="support" tags="support,triage" publish_first=true include_knowledge_doc_ids="<DOC_ID_1>,<DOC_ID_2>"

This is an outward, irreversible action — the template goes into the shared catalog and cannot be pulled back. Confirm with the user before calling it, including which KB docs (if any) should travel with it.

External MCP servers travel with the template automatically

If the agent has connected external MCP servers (Configure › Tools › MCP), the export templatizes them for you: each server's URL and header values are variabilized into {{placeholders}}, and any secret header (a value referencing a Vault secret) is preserved as an {{env.<name>}} reference — never the secret itself. The importer/hirer supplies their own URL, headers and secret values on setup. You do not list MCP URL/header literals in variabilization_map; that happens automatically.

Two optional controls:

• aramb_mcp.agents_list_mcp_connections (agent_id) — list the agent's connected MCP servers so you know their names. Returns {mcp_connections: [{name, display_name, enabled}]} — names + arm state only (URL/headers/secrets live in the integrations proxy and are never returned).
• mcp_required on export_template — an object marking each server required or optional, e.g. mcp_required='{"echo_server": true, "scratch_mcp": false}'. A server you omit defaults to required. true = the importer must connect it to use the template; false = optional.

# See which MCP servers the agent has, then mark one optional on export.
npx mcporter call aramb_mcp.agents_list_mcp_connections agent_id="<AGENT_ID>"
npx mcporter call aramb_mcp.agents_export_template agent_id="<AGENT_ID>" slug="support-triage" name="Support Triage Agent" mcp_required='{"echo_server": true}'

Like required toolkits, this is a declaration the importer fulfils: the template names the servers and their shape, the user connects their own on the imported agent's Tools page. You never carry a secret into a template.

Draft vs published — the one model to internalize

update edits a private draft; publish releases it. So the safe default loop is: get → discuss → update → let the user test → publish when they confirm. If a user reports "my agent still does the old thing" after an update, the likely cause is an unpublished draft — get shows publishable: true when the draft differs from the published version.

Required toolkits — you DECLARE them, the USER connects them

An agent's persona declares the toolkits it needs (its required toolkits / ports — GMAIL, SLACK, GOOGLESHEETS…) via required_toolkits on aramb_mcp.agents_create / update. Declaring a port is not enough to run: each required toolkit needs a connected account (a real account a human authorized via OAuth) before the agent can use it. You do not pick or pin the exact account — which account an agent uses for a toolkit is resolved automatically from the account the user connected on their own runtime project.

Your half of the contract is the declaration, and only the declaration:

# Ground every slug against the real catalog first — never invent one.
npx mcporter call aramb_mcp.toolkits_list_toolkits

# Then declare them on the agent.
npx mcporter call aramb_mcp.agents_update agent_id="<AGENT_ID>" required_toolkits='["GMAIL"]'

Then tell the user to connect each account themselves, in the console, on the agent's Tools page. A run is gated until every required toolkit has a connected account.

You cannot connect a toolkit, and the connect tools are not in your tool list. aramb_mcp.toolkits_connect / execute GITHUB_GET_GIT_CREDENTIAL are deliberately not advertised to the agent-builder persona. The reason is not politeness — a connection you brokered would be scoped to the builder's own project, which never executes, so the account the user authorized would be invisible at run time. The user connecting from the console lands it on their runtime project, which is the only place execution looks.

So: never mint or paste an authorization link (never a raw connect.composio.dev URL), never start OAuth, never inspect connection state, and never say a toolkit is connected. If the user asks you to connect one, say plainly that you declare it and they connect it on the Tools page.

Truthfulness — do not get ahead of the tool result. Never tell the user a toolkit is connected: you have no way to observe that. Say "I've declared Gmail as a required toolkit — connect your account on the agent's Tools page and it'll be ready", not "Gmail is connected". This is the same truthfulness rule that governs the rest of this skill (never claim a state you haven't observed).

Beyond the prompt — when the agent needs more, use the right skill

A persona often needs a capability these tools don't cover. Don't improvise it here — reach for the dedicated skill; each documents its own tools:

• The agent must touch an external service (Gmail, Drive, Slack, a sheet) → use the aramb-toolkits skill for everything: check what's connected, start the OAuth from chat, and discover + run the actual actions (aramb_mcp.toolkits_search → get_schema → execute). Name the concrete connection the agent needs.
• The agent's job is a repeated multi-step routine, or should run on its own (daily digest, triage-then-route, scheduled report) → build and run it with the create-workflow / aramb-workflows skills, and schedule-workflow / configure-trigger to fire it on a cron or an event.

An agent can own workflows (an optional binding, not a rule for all workflows)

Workflows are standalone objects by default and remain so — this section is only about the ones you deliberately bind to an agent. A bound workflow is owned by, and discoverable + runnable by, exactly one agent; binding does not turn every workflow into an agent-scoped thing, and standalone workflows are unaffected. When you are designing an agent, build the workflows it needs bound to that agent (rather than leaving them loose) so the agent can discover and run them:

• A bound workflow belongs to exactly one agent — and there are two equally-valid orderings to get there. Agent-first: create the agent, then create the workflow already linked to it by passing agent_id on aramb_mcp.workflows_create (create-and-link in one call). Workflow-first: if the builder wants to design and TEST a workflow before committing to an agent, build it on its own, iterate/preview it, then link it to the agent with aramb_mcp.agents_attach_workflow once the agent exists (its agent_id gets stamped and the workflow is re-filed under the agent's template project). Attach and create-with-agent_id converge on the same end state — owned by and filed under the agent. Don't leave a workflow permanently unattached. See the create-workflow and aramb-workflows skills.
• A workflow stays a draft on creation; the builder tests it via Preview. There is no separate "publish the workflow" step — a workflow freezes into its live version automatically when you aramb_mcp.agents_publish the owning agent. So publishing the agent is what ships both the persona and its workflows together.
• Publishing a toolkit-using workflow is gated on its toolkits being connected. When you publish the agent, the backend publishes each bound workflow draft — BUT a workflow whose steps require third-party toolkits (Gmail, Slack, Notion…) goes live ONLY if those toolkits are actually CONNECTED. If a required toolkit isn't connected, that workflow stays a draft and the publish response reports it as blocked, naming the missing toolkits. So the go-live path for such a workflow is: connect its toolkits on the Integrations page, then publish the agent. Verify up front with aramb_mcp.toolkits_check_connection and tell the builder which toolkits to connect — never call a toolkit-using workflow "live" before its toolkits are connected and the agent is published.

Not this skill

• Workflow-node sub-agents (a persona to own one step of a workflow you are authoring) → the create-agent skill. Those are workspace-level runtime agents, not org product agents, and have no draft/publish lifecycle.
• Editing your own persona — these tools manage the org's agents; your own identity files are not among them.

Ownership

Every call is fenced to the calling agent's organization. There is no org argument and no way to address another org's agents; an id that isn't yours reads as not found.