Build a custom agent#
This guide shows you how to write a Python program that asks a language model for the content of a page, and applies it to a Plone site only after a person approves. The library does the Plone work, your code decides what the model may do, and nothing reaches the site without a yes.
You need a profile, or the URL of a site. The examples use a local site, which Run a Plone site for testing starts.
Isolate the model call#
Keep the call to the model in one function that returns plain data, so that you can test the rest without a model.
This stand-in lets you run the program without a key.
Save it as model.py.
def write_page(topic: str) -> dict:
"""A page about a topic, as the model would write it."""
return {
"title": f"About {topic}",
"description": f"A short page about {topic}.",
"paragraphs": [f"This page is about {topic}.", "It has two paragraphs."],
}
When the program works, replace it with a real call.
This one uses the Anthropic Python SDK, which reads its key from ANTHROPIC_API_KEY.
Any other model works the same way, as long as the function returns the same shape.
import anthropic
import json
PROMPT = """Write a short web page about {topic}.
Answer only with JSON, with the keys title, description, and paragraphs,
which is a list of strings."""
def write_page(topic: str) -> dict:
"""A page about a topic, written by the model."""
client = anthropic.Anthropic()
answer = client.messages.create(
model="claude-opus-5-5",
max_tokens=1000,
messages=[{"role": "user", "content": PROMPT.format(topic=topic)}],
)
return json.loads(answer.content[0].text)
Write the agent#
Save this as agent.py.
It builds the blocks in code, so the model cannot produce a page that the site rejects.
It runs the change on a dry run client first, prints the plan, and waits.
import sys
from model import write_page
from plone_client import blocks
from plone_client import PloneClient
URL = "http://localhost:8080/Plone"
LOGIN = {"username": "admin", "password": "admin"}
def page_data(page: dict) -> dict:
"""Field values for a page, with blocks built and checked."""
items = [blocks.title(), blocks.description()]
items += [blocks.text(paragraph) for paragraph in page["paragraphs"]]
data = {"title": page["title"], "description": page["description"]}
return blocks.prepare({**data, "blocks": items})
def create(data: dict, dry_run: bool) -> dict:
"""Create the page, or only plan it."""
with PloneClient(URL, dry_run=dry_run, **LOGIN) as site:
answer = site.content.create("/news", "Document", data)
return site.dry_run_log[-1] if dry_run else answer
data = page_data(write_page(sys.argv[1]))
plan = create(data, dry_run=True)
print(plan["method"], plan["url"])
print("title:", plan["json"]["title"])
print("blocks:", len(plan["json"]["blocks"]))
if input("Apply? [y/N] ").strip().lower() != "y":
sys.exit("Nothing was changed.")
item = create(data, dry_run=False)
print("created", item["@id"], item["review_state"])
Run it#
Answer the question with anything but y, and nothing changes.
python agent.py sprints
POST http://localhost:8080/Plone/++api++/news
title: About sprints
blocks: 4
Apply? [y/N] Nothing was changed.
Answer y, and the program sends the same request.
python agent.py sprints
POST http://localhost:8080/Plone/++api++/news
title: About sprints
blocks: 4
Apply? [y/N] created http://localhost:8080/Plone/news/about-sprints private
The new page is private, so publishing stays a separate decision.
To publish, call site.workflow.transition(item["@id"], "publish") after a second approval.
Keep the model on a short leash#
Give the model no tools, as here, and let your code call the library. What it can do is then what your code does.
Set
read_only=Trueon the client of any site that the program should only read.Treat the answer as untrusted: build blocks with
plone_client.blocks, and do not pass fields you did not expect. A site silently ignores unknown fields.Log
site.dry_run_logwith each approval, to know later what was approved.
Protect a site from an agent covers the rest.
Use the MCP server instead when#
The model should choose its own steps, and not follow a fixed program.
You would otherwise rewrite the tools that the server has.
Your program can be the client: Connect from Python connects to the server from Python.