Reference
bbasata-universal interchange format
The bbasata-universal exporter writes a neutral, portable JSON snapshot of every agent in your bbasata subscription to .bbasata/agents/*.json. It is an interchange / migration format — not a loader. It does not inject agents into any tool by itself.
What it is — and what it is not
- It is: a full, structured copy of each bbasata cloud agent (prompt, tools, permissions, model settings) as one JSON file per agent.
- It is not: a universal agent loader. Tools do not read
.bbasata/agents/*.jsonnatively — each tool has its own on-disk agent format. - Use it for: backup, portability, CI, and as the source data when hand-writing a native agent file for a tool that has no bbasata exporter yet.
Export the interchange files
The exporter is registered under the target name bbasata:
bbasata agents sync --target bbasataThis writes one file per agent into .bbasata/agents/, e.g. .bbasata/agents/software-engineer.json. Pass --force to bypass the TTL cache and fetch fresh agents from bbasata cloud.
bbasata login + bbasata initin your project. Requires an authenticated subscription with agents assigned.Understand the real schema
Each file is the agent record (CloudAgent) from bbasata cloud, plus the bbasata_managed: true marker:
Show full agent JSON example
{
"slug": "software-engineer",
"name": "Software Engineer",
"description": "Builds REST APIs with Next.js, Prisma, zod",
"category": "engineering",
"prompt": "You are a senior backend engineer...",
"tools": ["bbasata_create_task", "bbasata_move_task"],
"allowedShellCommands": [],
"temperature": 0.2,
"topP": 0.95,
"maxTokens": 8192,
"tone": "professional",
"permissions": {
"saasTools": null,
"systemTools": {
"bash": "ask",
"edit": "allow",
"git": "allow",
"webfetch": "allow",
"websearch": "allow"
},
"bashDeny": ["rm *"]
},
"bbasata_managed": true
}Show full agent JSON example
{
"slug": "software-engineer",
"name": "Software Engineer",
"description": "Builds REST APIs with Next.js, Prisma, zod",
"category": "engineering",
"prompt": "You are a senior backend engineer...",
"tools": ["bbasata_create_task", "bbasata_move_task"],
"allowedShellCommands": [],
"temperature": 0.2,
"topP": 0.95,
"maxTokens": 8192,
"tone": "professional",
"permissions": {
"saasTools": null,
"systemTools": {
"bash": "ask",
"edit": "allow",
"git": "allow",
"webfetch": "allow",
"websearch": "allow"
},
"bashDeny": ["rm *"]
},
"bbasata_managed": true
}The important fields are prompt (the agent instructions),tools (which bbasata MCP tools it may call), and permissions (system-tool policy: bash/edit/git/webfetch/websearch as "allow" | "ask" | "deny" plus bashDeny patterns). Note there is no server-list or system-prompt key — those are tool-specific concepts, not part of this format.
Port to a tool's native format
Third-party tools with their own file-based agents use formats that differ from the interchange JSON. To load a bbasata agent there, translate theprompt andpermissions fields into that tool's documented schema:
Generic third-party format How to port from interchange JSON
Markdown agents (*.md + YAML frontmatter) Translate prompt + permissions into name/description/tools/model fields
JSON agents (*.json, one file per agent) Translate prompt + permissions into name/description/prompt/tools fields
YAML agents (*.yaml) Translate prompt + permissions into the tool's documented agent keysFor example, a Markdown-based tool expects Markdown files with YAML frontmatter (name/description/tools/model), while a JSON-based tool expects one JSON file per agent with fields likename/description/prompt/tools plus each tool's own server configuration. Check each tool's official docs for the exact schema.
Tools without a native exporter
For third-party tools without a bbasata exporter — port manually as described in step 3 from the interchange JSON. For any tool that speaks MCP, the generic integration path is to connect the bbasata MCP server directly and use its tools, not to import agent files.
Keep files in sync
Re-run the export whenever agents change in bbasata cloud:
bbasata agents sync --target bbasata --forceThe --force flag ignores the TTL cache and fetches the latest agents from bbasata cloud. Commit the.bbasata/agents/ directory to version control to keep a portable, reviewable copy of your agent catalog.