Draft a suggested colleague into the world, unsigned and off duty
const url = 'http://localhost:11044/api/v1/agent-suggestions/example/draft';const options = {method: 'POST', headers: {'X-Embabel-Api-Key': '<X-Embabel-Api-Key>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url http://localhost:11044/api/v1/agent-suggestions/example/draft \ --header 'X-Embabel-Api-Key: <X-Embabel-Api-Key>'Writes config/agents/
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The suggestion’s id
Responses
Section titled “Responses”The suggestion, drafted, with its preview
A suggested colleague after it was recorded, drafted, adopted or dismissed, or why that was refused; answered by the /agent-suggestions endpoints
object
Why the change was refused, in words; null when it was made
The suggestion after the change; null when it was refused
object
Name of the installed realm agent that already covers this work; null when an agent is to be drafted instead
The agent definition to draft, in the agents YAML shape; null when adopting. The server strips sponsor, owners and operators and bounds its authority, so a draft starts unsigned and off duty
object
What it may do on its own, verb by verb, once on duty. Null leaves every verb at act
object
Level for every effect not named in verbs: act (the default), request or never. An unrecognised level reads as request
Gatekeeper rules it only tries: authority, sensitive, egress or review. Each is evaluated and recorded on the run, but the call goes through
Namespaces its routines may reach. When set, a call to any API or MCP server not listed is refused, read or write; reading the world’s graph and raising a request never are. Null reaches everything
Whether an independent reviewer reads each write it may make on its own first, and may refuse it; a model call per write. False by default
Level by verb, named as the gateway names it (for example odoo_partnerMessagePost): act, request or never
object
Its hard limits on spend and activity; raising one waits for its sponsor’s signature. Null is no limit
object
Most of its runs that may be in progress at once
ISO-8601 date (yyyy-MM-dd), read in the user’s zone, after which it stands down until re-signed with a later one. A date that does not parse stands it down too
Most requests for people to approve that one run may raise
Most runs it may start in any rolling hour; skipped runs do not count
Percent of each source’s declared rate it may take, keyed by bucket (a producer’s cost.bucket, else its name), with * for every bucket not named. Only sources that declare a rate are paced
object
Most model spend across a day, in US cents
Most model spend one run may make, in US cents
Most writes it may make on its own in a day
Which colleagues it may message and which may message it; both sides must agree. Null is nobody, either way
object
Names of the agents that may message it
Names of the agents it may message
How it is talked to: the realms a conversation reaches and the host tools it keeps. Null scopes it to the realm that shipped it, with every host tool
object
Which host tools it keeps: true or null for all, false for none, or one category name or a list of them. An unknown category is logged and left out
The LLM role the conversation runs on, never a model name; null for the default
Names of the realms the conversation reaches; empty scopes it to the realm that shipped the agent
Bounds on the sampling a caller may ask for; null leaves the role’s own settings
object
The most tokens a caller may ask a reply to take; null declares no cap
Allowed temperature range as two numbers [low, high]; any other length is ignored. Null declares no range
Whether its writes say an agent made them, even under its own account. True by default
The conditions it keeps true
A duty as authored: a condition the agent keeps true, the view whose rows are its violations, its check cadence and the routine that repairs a violation
object
Six-field cron cadence to check it on; null for on demand only
Name of the view or DERIVE label whose rows are the violations
The duty’s name within its agent
Name of the TypeScript action that repairs one violation, run once per violating row with the row bound as violation; null for no repair
Stage for this duty alone (off, observing or on); null runs it as the agent. Dropped from a realm-shipped agent
The condition as the sponsor wrote it: an Always or a Never
Zone the cadence is read in, as a zone ID such as Europe/London; null reads it in the user’s own zone
Whose account each API is called with, keyed by API name: own-account (its own credential) or on-behalf-of (its sponsor’s, the default)
object
The job in one sentence: what a manager reads first. An agent with no job cannot go on duty
Model names keyed by LLM role (for example vc_relevance), used for its own views, routines and conversations ahead of the world’s role map and the deployment default
object
The agent’s name, unique in the world; an agent with no name is not loaded
Usernames of its operators. Dropped from a realm-shipped agent
Usernames of its owners, who may sign it, put it back on duty after a sponsor stands it down, and move a Gatekeeper rule from observe to enforce. Dropped from a realm-shipped agent
Slug of a personality to speak through; null for none
How its work is scheduled, and the models it falls back to when one fails. Null is business priority with no fallbacks
object
Fallback model names keyed by LLM role. A check whose models and fallbacks all fail is held as unknown, never as upheld
object
Interactive, business (the default) or background. Background work takes half of each source it declares no share for; a conversation is interactive whatever is declared
Set by the loader: the realm that shipped this agent, or null for one authored in the world
The TypeScript actions it holds, by name; each body stays in its own action file
A routine an agent holds: a TypeScript action, by name, that fires on a schedule or a signal
object
Name of the action in the world’s actions
Stage for this routine alone (off, observing or on); null runs it as the agent. Dropped from a realm-shipped agent
“Ask me about…”: when people and other agents should come to it
Username of the person who answers for it. Required to go on duty; dropped from a realm-shipped agent, which the world adopts
Its stage: off (the default), observing or on; a bare YAML boolean reads as on or off, and an unrecognised value as off. Forced to off for a realm-shipped agent
Lifecycle state: draft (the default), submitted, active, suspended or retired; an unrecognised value reads as draft. A realm-shipped agent arrives active unless it is retired
The cold materializations it keeps filled, each a saved view run under its budget until a pass buys nothing. Empty sweeps nothing
A sweep: a cold materialization an agent keeps filled by running a saved view pass after pass, under a budget, until a pass buys nothing
object
Most units of paid work (a producer fetch, or a group of an inline judgement) one pass may buy; null takes the host’s default
The sweep’s name within its agent; part of the fill’s identity, so starting it twice is one fill
Name of a saved view of this world that takes no arguments: the query each pass runs
A version number as written in the file; the catalogue shows the latest signed version instead
When the suggestion was last recorded, as an ISO-8601 instant; set by the server
When it was drafted, adopted or dismissed, as an ISO-8601 instant; null while OPEN
The counts the suggestion rests on, each with the query that produced it; at least one is required
One counted piece of evidence for an agent suggestion: what was seen, how often, over what period, and the query that counted it so it can be run again
object
How many times it was seen over the period
The span the count covers, as free text, e.g. “2026-04-06 to 2026-06-22”; empty when not stated
The Cypher query that produced the count, so a person can run it again; null when not given
Example rows the query returned, each a map of column name to value; empty when none were kept
object
What was seen, in a sentence, e.g. the habit or the manual act counted
Free text on whether the work can be done with what is installed: the verbs that exist, or what must be built or learned first
Server-assigned identifier, prefixed sg_; kept when an open suggestion of the same name is replaced. Ignored on POST
The work the colleague would take on, in one sentence; required
WORKS for an agent with duties and routines, TALKS for one people converse with (a persona and realms, no duties)
The colleague’s name: the realm agent to adopt, or the name the draft is written under. Lowercase letters, digits and dashes, starting with a letter, 2-40 characters
Id of the user whose world the suggestion is for; set by the server to the caller
One line per duty saying how many rows its view would act on today, or why it could not run; empty until drafted
The scout’s ranking, weighing value and feasibility together; lists are ordered by it, highest first
OPEN until a person decides; then DRAFTED, ADOPTED or DISMISSED. Always OPEN when recorded
What the agent named by adopt does not cover, in a sentence; null when it covers all of the work
Example
{ "suggestion": { "agent": { "authority": { "default": "act", "observe": [ "authority" ], "verbs": { "additionalProperty": "act" } }, "duties": [ { "stage": "off" } ], "identity": { "additionalProperty": "own-account" }, "qos": { "priority": "interactive" }, "routines": [ { "stage": "off" } ], "stage": "off", "state": "draft" }, "kind": "WORKS", "status": "OPEN" }}No authenticated principal
A refusal with a machine-readable code and a plain-language message. ApiErrorAdvice answers it for a failed validation, a missing resource or a conflicting state, and some controllers answer it directly
object
Machine-readable key to branch on, such as validation_failed, unknown_field, not_found or conflict. Open: a surface may answer codes of its own
Extra context where there is some, such as the fields a body may carry; null otherwise
A plain-language explanation, written to be shown. Never carries an exception message
The body the servlet error dispatch answers for a status raised by an exception rather than written by the endpoint. Every failure except 404, which answers the not-found HTML page
object
The status’s standard reason phrase, such as Bad Request or Forbidden
The request path that failed
The HTTP status code, repeated from the status line
Example generated
{ "code": "example", "detail": "example", "message": "example"}No such suggestion in your world
Refused: already settled, a suggestion to adopt, or the name is taken
A suggested colleague after it was recorded, drafted, adopted or dismissed, or why that was refused; answered by the /agent-suggestions endpoints
object
Why the change was refused, in words; null when it was made
The suggestion after the change; null when it was refused
object
Name of the installed realm agent that already covers this work; null when an agent is to be drafted instead
The agent definition to draft, in the agents YAML shape; null when adopting. The server strips sponsor, owners and operators and bounds its authority, so a draft starts unsigned and off duty
object
What it may do on its own, verb by verb, once on duty. Null leaves every verb at act
object
Level for every effect not named in verbs: act (the default), request or never. An unrecognised level reads as request
Gatekeeper rules it only tries: authority, sensitive, egress or review. Each is evaluated and recorded on the run, but the call goes through
Namespaces its routines may reach. When set, a call to any API or MCP server not listed is refused, read or write; reading the world’s graph and raising a request never are. Null reaches everything
Whether an independent reviewer reads each write it may make on its own first, and may refuse it; a model call per write. False by default
Level by verb, named as the gateway names it (for example odoo_partnerMessagePost): act, request or never
object
Its hard limits on spend and activity; raising one waits for its sponsor’s signature. Null is no limit
object
Most of its runs that may be in progress at once
ISO-8601 date (yyyy-MM-dd), read in the user’s zone, after which it stands down until re-signed with a later one. A date that does not parse stands it down too
Most requests for people to approve that one run may raise
Most runs it may start in any rolling hour; skipped runs do not count
Percent of each source’s declared rate it may take, keyed by bucket (a producer’s cost.bucket, else its name), with * for every bucket not named. Only sources that declare a rate are paced
object
Most model spend across a day, in US cents
Most model spend one run may make, in US cents
Most writes it may make on its own in a day
Which colleagues it may message and which may message it; both sides must agree. Null is nobody, either way
object
Names of the agents that may message it
Names of the agents it may message
How it is talked to: the realms a conversation reaches and the host tools it keeps. Null scopes it to the realm that shipped it, with every host tool
object
Which host tools it keeps: true or null for all, false for none, or one category name or a list of them. An unknown category is logged and left out
The LLM role the conversation runs on, never a model name; null for the default
Names of the realms the conversation reaches; empty scopes it to the realm that shipped the agent
Bounds on the sampling a caller may ask for; null leaves the role’s own settings
object
The most tokens a caller may ask a reply to take; null declares no cap
Allowed temperature range as two numbers [low, high]; any other length is ignored. Null declares no range
Whether its writes say an agent made them, even under its own account. True by default
The conditions it keeps true
A duty as authored: a condition the agent keeps true, the view whose rows are its violations, its check cadence and the routine that repairs a violation
object
Six-field cron cadence to check it on; null for on demand only
Name of the view or DERIVE label whose rows are the violations
The duty’s name within its agent
Name of the TypeScript action that repairs one violation, run once per violating row with the row bound as violation; null for no repair
Stage for this duty alone (off, observing or on); null runs it as the agent. Dropped from a realm-shipped agent
The condition as the sponsor wrote it: an Always or a Never
Zone the cadence is read in, as a zone ID such as Europe/London; null reads it in the user’s own zone
Whose account each API is called with, keyed by API name: own-account (its own credential) or on-behalf-of (its sponsor’s, the default)
object
The job in one sentence: what a manager reads first. An agent with no job cannot go on duty
Model names keyed by LLM role (for example vc_relevance), used for its own views, routines and conversations ahead of the world’s role map and the deployment default
object
The agent’s name, unique in the world; an agent with no name is not loaded
Usernames of its operators. Dropped from a realm-shipped agent
Usernames of its owners, who may sign it, put it back on duty after a sponsor stands it down, and move a Gatekeeper rule from observe to enforce. Dropped from a realm-shipped agent
Slug of a personality to speak through; null for none
How its work is scheduled, and the models it falls back to when one fails. Null is business priority with no fallbacks
object
Fallback model names keyed by LLM role. A check whose models and fallbacks all fail is held as unknown, never as upheld
object
Interactive, business (the default) or background. Background work takes half of each source it declares no share for; a conversation is interactive whatever is declared
Set by the loader: the realm that shipped this agent, or null for one authored in the world
The TypeScript actions it holds, by name; each body stays in its own action file
A routine an agent holds: a TypeScript action, by name, that fires on a schedule or a signal
object
Name of the action in the world’s actions
Stage for this routine alone (off, observing or on); null runs it as the agent. Dropped from a realm-shipped agent
“Ask me about…”: when people and other agents should come to it
Username of the person who answers for it. Required to go on duty; dropped from a realm-shipped agent, which the world adopts
Its stage: off (the default), observing or on; a bare YAML boolean reads as on or off, and an unrecognised value as off. Forced to off for a realm-shipped agent
Lifecycle state: draft (the default), submitted, active, suspended or retired; an unrecognised value reads as draft. A realm-shipped agent arrives active unless it is retired
The cold materializations it keeps filled, each a saved view run under its budget until a pass buys nothing. Empty sweeps nothing
A sweep: a cold materialization an agent keeps filled by running a saved view pass after pass, under a budget, until a pass buys nothing
object
Most units of paid work (a producer fetch, or a group of an inline judgement) one pass may buy; null takes the host’s default
The sweep’s name within its agent; part of the fill’s identity, so starting it twice is one fill
Name of a saved view of this world that takes no arguments: the query each pass runs
A version number as written in the file; the catalogue shows the latest signed version instead
When the suggestion was last recorded, as an ISO-8601 instant; set by the server
When it was drafted, adopted or dismissed, as an ISO-8601 instant; null while OPEN
The counts the suggestion rests on, each with the query that produced it; at least one is required
One counted piece of evidence for an agent suggestion: what was seen, how often, over what period, and the query that counted it so it can be run again
object
How many times it was seen over the period
The span the count covers, as free text, e.g. “2026-04-06 to 2026-06-22”; empty when not stated
The Cypher query that produced the count, so a person can run it again; null when not given
Example rows the query returned, each a map of column name to value; empty when none were kept
object
What was seen, in a sentence, e.g. the habit or the manual act counted
Free text on whether the work can be done with what is installed: the verbs that exist, or what must be built or learned first
Server-assigned identifier, prefixed sg_; kept when an open suggestion of the same name is replaced. Ignored on POST
The work the colleague would take on, in one sentence; required
WORKS for an agent with duties and routines, TALKS for one people converse with (a persona and realms, no duties)
The colleague’s name: the realm agent to adopt, or the name the draft is written under. Lowercase letters, digits and dashes, starting with a letter, 2-40 characters
Id of the user whose world the suggestion is for; set by the server to the caller
One line per duty saying how many rows its view would act on today, or why it could not run; empty until drafted
The scout’s ranking, weighing value and feasibility together; lists are ordered by it, highest first
OPEN until a person decides; then DRAFTED, ADOPTED or DISMISSED. Always OPEN when recorded
What the agent named by adopt does not cover, in a sentence; null when it covers all of the work
Example
{ "suggestion": { "agent": { "authority": { "default": "act", "observe": [ "authority" ], "verbs": { "additionalProperty": "act" } }, "duties": [ { "stage": "off" } ], "identity": { "additionalProperty": "own-account" }, "qos": { "priority": "interactive" }, "routines": [ { "stage": "off" } ], "stage": "off", "state": "draft" }, "kind": "WORKS", "status": "OPEN" }}