AI agents and the API

An AI agent is a program that works in your Mage Engage account through its API. It might be an assistant you have set up, an automation, or your own code. An agent can't sign in to the Mage Engage pages; it works only with a token you create for it.

What an agent can do

Every agent can:

• read your brands and posts;
• create and edit ideas and drafts, and submit them for review;
• upload images and video to a brand's Media Library and put them on a post's platforms.

Two rights are off until the account Owner turns them on, brand by brand:

• Schedule & publish: schedule posts, publish them now (the whole post, or one platform on its own), and change posts that are already scheduled.
• Use AI: have Mage AI write posts. This spends your account's AI Credits, just as when you use Mage AI yourself.

An agent can never approve posts. On a brand that requires approval, a person still approves each post before it can be scheduled. Agents also can't delete posts, take a whole post off the schedule, or use Mage Planner, the Campaign Builder or articles; a person does those in Mage Engage.

Using the API is free. Only AI costs credits.

Adding an agent

The Owner and Administrators manage agents in either of two places:

• in Mage Engage, under Admin → AI Agents;
• in the Press Mage portal, on your Mage Engage service, in the AI Agents panel.

1. Click Add agent (Add AI agent in the portal) and give it a name, and optionally a description of what it does.
2. Under the agent, create a token and copy it. The token is shown only once. If you lose it, revoke it and create a new one.
3. If you are the Owner, tick Schedule & publish and Use AI for the brands the agent should have them on, and save.
4. Give the agent its token and the address of its guide (below).

The guide for your agent

Mage Engage publishes instructions written for AI agents. They cover every call, the rules above, and how to handle errors. Neither address needs a token:

• Guide for agents: https://mageengage.cloud/api/v1/guide
• OpenAPI description, for tools that read it: https://mageengage.cloud/api/v1/openapi.yaml

A simple way to start an agent is: "Read https://mageengage.cloud/api/v1/guide, then use the Mage Engage API with this token: …"

Images and video

An agent uploads an image or video into the brand's Media Library, then attaches it to each platform of a post that should show it; as in the post form, every platform has its own media. Files follow the same rules as uploads you make yourself: JPG, PNG, GIF or WebP images up to 10 MB, and MP4, MOV or WebM video up to 25 MB. They count towards your plan's storage, appear in the Media Library like any other file, and can be reused on other posts.

Keeping agents safe

• Treat a token like a password. Anyone who has it can act as that agent.
• Revoke a token, or Remove the agent, and it stops working at once. Posts the agent made stay.
• The agent's work shows under its name in Activity, and posts it wrote show it as the author.
• Give an agent Schedule & publish only on brands where you are happy for it to post without a person checking first, or turn on Require approval for that brand.