Skip to main content
Prime functions are not available yet. This page describes how they will work, so you can plan for them. Until they are on for your account, search and get do not list the prime_function and function_run kinds, and save_prime_function is refused with FEATURE_NOT_ENABLED.
Your account’s own agent, the Prime (see hosted buyer agents), can write code: a script that pulls a week of delivery into a summary, or checks pacing across a set of campaigns. A Prime function keeps that script and runs it again later, on a schedule, when a platform event happens, or when another system calls a webhook. The script runs without the agent: no model call, the same code every time. Nothing runs until two people have said yes. A person reads the script and makes it Live in your Library. An administrator approves where, when and for whom it runs.

How a function is made

  1. The agent writes the script. In a conversation you started, the agent saves it to your Library as a Draft, in the script category. A script is one Python 3 file.
  2. A person makes it Live. Anyone with write access to the account and to the advertisers the script is filed under can read it and make it Live, as with any Draft in your Library. No agent can make a script Live.
  3. The agent proposes the function. It names the script revision, what starts a run, the advertiser or Project it works for, and the one kind of memory it may save. You, the person in the conversation, become accountable for its runs. The answer is approval_required, with a link.
  4. An administrator approves it on Apostra. The approval page shows the whole script, a fingerprint of it (its sha256), what starts a run, the advertisers and Project, who is accountable, where each run posts, and a plain list of what the script may read. Only an administrator of the account, or of its organization, signed in as themselves, can approve, and only for advertisers they can read.
A function is pinned to the exact revision that was approved. If someone saves a new revision of the script, the function keeps running the old one until a new version of the function pinning the new revision is approved. If the approved revision is archived or changed, the function stops.

What starts a run

Each function has one of these: A canvas on the function’s Project or advertiser can also show its latest result straight away and ask for a fresh run. It never waits for the run to finish.

What a run can do

A run acts as your account’s agent, working for the accountable person. It can only read, and only the advertisers the function was approved for, and only what that person can still read. It reads the same campaign, media buy, creative, delivery and memory information a canvas can. It writes two things and nothing else:
  • One post in your account’s conversation, or the Project’s, saying what ran, how it ended, and what the script printed. Only people who can read every advertiser the run worked for see it.
  • Up to 20 memories of the one kind the function was approved for, facts or events, in its advertiser’s or Project’s memory (see agent memory). Each is marked as unattended work, so you can see what it saved and forget anything you disagree with.
A run never buys, changes a campaign or a media buy, sends a message, saves to the Library, writes account or personal memory, or writes an instruction. The script has no passwords or keys, and it cannot reach the internet: it can only call Apostra’s own read proxy.

Limits

  • A run stops after 5 minutes. Up to 8,000 characters of what it prints, and 2,000 of its errors, are kept.
  • A run makes at most 100 reads.
  • A function runs at most 12 times an hour, and an account runs at most 2 functions at once.
  • An account has at most 20 active functions.
  • Five failed runs in a row switch a function off. An administrator can switch it back on.
Prime functions are not charged while the Prime is in beta.

Pausing and changing a function

Anyone with write access who can read the function’s advertisers can pause it. An administrator can switch a paused function back on. Changing the script revision, the trigger, the advertisers, the Project, the accountable person or the memory it may save makes a new version that needs approval again, and the old version stops running at once. If the accountable person leaves your account, their functions pause until a new version names someone else and is approved.

For developers

Hosted orchestrators, external buyer agents and any other agent using its own credentials can neither propose nor read functions.

Calling a webhook function

When a webhook function is approved, its address is shown on the function, and its signing secret is shown once to the approving administrator on Apostra. An administrator can replace the secret there, and it is shown once again. Each request is a POST with a JSON or plain-text body of at most 64 KB, signed with HMAC-SHA256 over the Unix timestamp in seconds, a full stop and the raw body:
A timestamp more than 5 minutes off, or a signature already used, is refused. The body reaches the script only as data, and is never posted or shown to the agent.

Agent memory

Where a function’s results are kept

Hosted buyer agents

Your account’s own agent and how it runs