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.How a function is made
- The agent writes the script. In a conversation you started, the agent saves
it to your Library as a Draft, in the
scriptcategory. A script is one Python 3 file. - 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.
- 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. - 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.
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.
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.
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 aPOST 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.
Related
Agent memory
Where a function’s results are kept
Hosted buyer agents
Your account’s own agent and how it runs