Marketing
Your agent
Let an agent you already run, such as Hermes or any MCP client, do the marketing steps instead of Borkol.
View as MarkdownBy default Borkol runs every step of a run on your OpenRouter key. If you already run your own agent, for example Hermes Agent, it can do the steps instead, on its own models. Borkol keeps the brand context, the pipeline and the checks; your agent picks up the work, reads the same brief Borkol would use, and sends the results back. Nothing changes for you: you still type a request on the Overview, and the scripts still land under Scripts.
Setting it up takes three things: a token, the three setup blocks pasted into your agent, and the brand switched to Your agent.
Create a token
Marketing → Settings → Connections → More · Your agent (/m/marketing/settings/integrations?section=agent) lists the tokens your agents use to connect. It moved there from its own settings section; the old address /m/marketing/settings/agent still opens it.
- Click Create token and give it a Name, for example "Hermes on my laptop".
- Click Create token. The next window shows the token, which starts with
bka_. Copy the token now: it is shown only once. After you close the window only its last four characters are visible, and nobody at Borkol can show it again. - The same window shows the three setup blocks with your token already filled in (see below). Copy what you need, then click Done.
More in the create window holds two optional limits, closed by default:
| Option | Default | What it does |
|---|---|---|
| What the agent may do | All three | See waiting work and read briefs (work:read), Send back results (work:submit), Report what a step cost (cost:report). At least one is required. |
| Brand | All brands | Limits the token to one brand. The agent then sees no work of other brands. |
Once a token is active, a line under the list links to AI pipeline, where you set Steps run on to Your agent for a brand.
The list shows each token's Name, the last four characters under Token, the Brand, Last used (Never until the agent first connects) and Status (Active or Revoked).
Only the account owner can create and revoke tokens. Team members see the list with "Only the account owner can create or revoke tokens."
The three setup blocks
The one-time window shows the blocks with your token in them. Setup instructions under the token list shows the same blocks later, with <your token> in place of the token: paste your own token there.
| Block | What it is |
|---|---|
| Agent config (Hermes) | The mcp_servers entry for Hermes' ~/.hermes/config.yaml: the Borkol Marketing server address and the token as a header. |
| Skill | The Borkol Marketing skill (SKILL.md, the Agent Skills format): how to find work, read the brief, submit and report costs. It is also served at the address under the block, so an agent can install it from there. |
| Schedule | A suggested schedule line: check Borkol for work every 15 minutes. |
With Hermes
- Add the Agent config (Hermes) block to
~/.hermes/config.yaml. - Install the skill:
hermes skills install https://api.borkol.com/mcp/marketing/SKILL.md(the address in the Skill block). - Run the Schedule line once. Hermes runs scheduled jobs inside its gateway, so keep
hermes gatewayrunning.
To try it right away, ask Hermes "Use the borkol-marketing skill: check Borkol for work and do it."
Any other MCP client
The server speaks the Model Context Protocol over HTTP, so any MCP client can connect. Point it at the server address from the config block and send the token as Authorization: Bearer <token>. The skill text works as instructions for any agent.
Switch a brand to your agent
Marketing → Settings → AI pipeline → More → Who runs the steps has one field, Steps run on: Borkol (the default) or Your agent. It is per brand, like every AI pipeline setting, and saves through the bar at the bottom. Runs already started keep their setting. On Your agent the step models do not apply: your agent picks its own models, and the page says so above them.
Choosing Your agent while no token exists shows "Your agent has no token yet. Create one under Your agent." with a link to the token page.
A brand that runs on your agent needs no OpenRouter key: you can start runs without one.
What the agent does
Your agent works through these tools on the Borkol Marketing server:
| Tool | What it does |
|---|---|
list_work | Lists the steps waiting for the agent, oldest first |
get_brief | Claims a step and returns its brief, playbook, output format and limits. A token without Send back results only reads the brief and leaves the step waiting for another agent |
submit_research | Sends back the research |
submit_angles | Sends back the angles |
submit_scripts | Sends back the scripts |
submit_check | Sends back the check of each script |
submit_scenes | Sends back the scenes of one script hook. A scenes run has one step per script and hook, so the agent passes the step_id from list_work to get_brief and here |
report_cost | Optional: reports what a step cost on the agent's own models |
report_metrics | Reports ad results per ad and day, so Borkol can learn from them. See below |
Every result is checked against the same format and limits as a step Borkol runs itself: the number of scripts, hooks per script, the allowed tags. Output in the wrong shape comes back to the agent as an error naming the field that failed, and the agent fixes it and sends it again. The step stays open until a valid result arrives. Scripts get their ad codes and go through the check exactly as they would on Borkol.
What your agent sends is treated as data, never as instructions: in later briefs it appears only as quoted material, and the check fails a script that repeats instruction-like text. Knowledge entries the agent proposes during research wait for acceptance under Knowledge, like proposals from any run.
Reporting ad results
An agent that can read your ad platform can send the results to Borkol with report_metrics, instead of you importing a file. The results are stored exactly like an ad results import and feed learnings. The token needs Send back results (work:submit); without it the tool is not offered.
Arguments:
| Name | Type | Required | Description |
|---|---|---|---|
brand_id | string | No | The brand the ads belong to. Required when the account has more than one brand and the token is not limited to one |
rows | array | Yes | 1 to 500 rows, one per ad and day |
Each row:
| Name | Type | Required | Description |
|---|---|---|---|
ad_name | string | Yes | The ad name as the ad platform shows it, holding the Borkol ad code (up to 500 characters) |
date | string | Yes | The day, YYYY-MM-DD |
spend | number | Yes | Spend that day, 0 or more |
impressions | integer | No | Impressions |
plays_3s | integer | No | Video plays of at least 3 seconds |
thruplays | integer | No | ThruPlays |
clicks | integer | No | Clicks |
purchases | integer | No | Purchases |
revenue | number | No | Revenue |
currency | string | No | Three-letter currency code of spend and revenue |
video_seconds | string | No | Length of the ad video: seconds (22, 22s) or mm:ss (0:22) |
channel | string | No | The ad platform, for example meta or tiktok (up to 32 characters) |
Every row is checked with the same rules as a file import. A row that fails is left out and listed under errors with its index, field and reason; the other rows are saved. The answer is {ok, created, updated, matched, unmatched, skipped, errors}: matched rows joined a script through their ad code, unmatched rows are kept and join once the script exists, skipped rows are for an ad and day the Meta ads connection already synced, so they never count twice. Sending the same ad and day again updates it.
Errors that stop the whole call:
| Code | When |
|---|---|
BRAND_REQUIRED | The account has more than one brand, the token is not limited to one, and no brand_id was sent |
BRAND_NOT_ALLOWED | The token is limited to one brand and brand_id names another |
BRAND_NOT_FOUND | No brand with this brand_id |
INVALID_INPUT | rows is missing, empty or longer than 500 |
A token limited to one brand can leave out brand_id.
On the run page
A run on your agent shows Runs on: Your agent under Details, and its steps can show two extra states:
| Step status | Meaning |
|---|---|
| Waiting for your agent | The step is ready; your agent has not picked it up yet |
| Stalled | The step has been waiting for 30 minutes without your agent picking it up |
A stalled step adds a line at the top of the run: "Your agent has not picked up a step in time. Check that your agent is running and its schedule is on, or cancel the run to free the brand for new runs.", with a link to Your agent. The bell shows one notification per stalled step ("Your agent has not picked up {step}: {request}"), and the mobile app sends it as a push notification. Once the agent picks the step up, it continues as normal. A stalled run still counts as active for its brand, so with Runs at the same time at 1 new runs on that brand wait behind it: cancel the run to free the brand.
A step your agent started but did not finish within an hour goes back to Waiting for your agent, so the next check can pick it up again.
Cost
Your agent pays for its own models; nothing is charged to your OpenRouter key. When the agent reports its cost, the run page shows it per step and in total as reported by your agent. Reporting is optional, so a step without reports shows no cost, and a run without any shows Not reported by your agent. The model shows only when the agent reported it.
The Cost limit per run applies only to runs on Borkol. A run on your agent is never paused at the cost limit.
Revoke a token
The row menu of an active token has Revoke. After you confirm "Revoke this token?", the agent using it can no longer connect, and the row shows Revoked. This cannot be undone: create a new token and update the agent's config instead. A step the agent had claimed goes back to Waiting for your agent at once, so another agent can pick it up.
Who can do what
Creating and revoking tokens is owner-only. Switching Steps run on needs marketing edit access, like the rest of the AI pipeline. Members with read access see the token list and the run pages.