Most agent integrations run as external services: a separate process, a hosted platform, a webhook receiver. You configure it outside your app, point it at your API, and hope the two stay in sync.
forge-agent takes a different approach. The agent runtime runs inside your Forge process. Lifecycle events in Forge trigger agent execution. Agents write results back via MCP. Nothing to deploy separately.
What it does
forge-agent handles two trigger types:
Signal-triggered — when Forge fires a lifecycle signal (after_publish, after_archive, etc.), a matching agent job runs. The agent receives the full event context: content type, slug, title, URL, previous state, actor role.
Cron-triggered — a job runs on a schedule, independent of any content event. Standard 5-field cron expression with IANA timezone support.
In both cases, the agent has access to your full MCP tool set — it can read content, create drafts, schedule posts, manage navigation. Whatever your token allows.
AgentJob: managing jobs via MCP
Agent jobs are AgentJob nodes — a Forge content type, same as Post or Story. This means the full set of MCP tools is generated automatically:
create_agent_job update_agent_job publish_agent_job
archive_agent_job list_agent_jobs get_agent_job
delete_agent_jobThe lifecycle maps directly to job state:
draft— job exists but does not runpublished— job is active and fires on triggerarchived— job is permanently stopped
Activating a job is publish_agent_job. Pausing it is archive_agent_job. No redeploy. No config file change. The operator — human or agent — manages jobs through the same interface as content.
Two use cases in production
UC1 — Devlog published: social media drafts
When a post is published on forge-cms.dev, an agent reads the post body and creates four draft scheduled posts — two for X and two for Mastodon, from two distinct angles — for operator review.
The agent job:
name: devlog-social-drafts
trigger: after_publish
content_type_filter: Post
system_prompt: <400-line prompt covering brand voice, post rules,
character limits, and tool call instructions>content_type_filter restricts the trigger to Post events. Without it, the job would fire on every published content type — including other AgentJob publishes.
The agent receives the SignalEvent as JSON in its task string. It parses the slug, calls get_post, reads the body, writes four posts, and calls create_scheduled_post four times. The operator reviews the drafts and queues them.
UC2 — Daily electricity prices: push notification
A cron job fetches day-ahead spot prices for the DK2 price zone from a public API every day at 13:45 Copenhagen time, when the next day's prices are available. It analyses the curve, identifies the cheapest charging window, and sends a plain-text summary to ntfy.sh.
The agent job:
name: dk2-spot-prices
trigger: 45 13 * * *
webhook_url: https://ntfy.sh/<topic>
system_prompt: <instructions for fetching, analysing, and formatting the summary>No MCP calls needed for this job — the agent uses the built-in http_get and http_post tools. webhook_url tells the agent where to POST its output.
Wiring into a Forge app
import "forge-cms.dev/forge-agent/flow"
// Create the agent_jobs table (once, at startup)
flow.CreateTable(db)
// Initialise the module
agentMod := flow.New(db, flow.Config{
AnthropicKey: os.Getenv("ANTHROPIC_API_KEY"),
MCPURL: os.Getenv("AGENT_MCP_URL"),
MCPToken: os.Getenv("AGENT_MCP_TOKEN"),
})
// Register with your Forge app — wires MCP tools, signal bus, cron scheduler
agentMod.Register(app)
defer agentMod.Stop()Register does three things: registers AgentJob as a content type (generating the MCP tools), subscribes to the Forge signal bus for signal-triggered jobs, and starts the cron scheduler for cron-triggered jobs. Published jobs activate immediately on next trigger.
Two modules, two licenses
The forge-agent repo contains two packages:
forge-cms.dev/forge-agent— MIT. The generic agent loop: Anthropic tool-use,
MCP client, built-in HTTP tools. Zero Forge dependency. Works with any MCP server.
forge-cms.dev/forge-agent/flow— AGPL. The Forge integration adapter:AgentJob
as a Forge content type, signal bus wiring, cron scheduler. Requires a Forge app.
If you are building something that does not use Forge, the MIT core is usable standalone. The AGPL adapter follows the same license terms as Forge core: any hosted service built on it must open-source the full stack or obtain a commercial license.
forge-agent v0.3.4.
*See Signal bus for how after_publish and other signals work.* *See MCP overview for how the agent connects to your Forge instance.*