Ask an agent to propose a better version of itself from its own record
const url = 'http://localhost:11044/api/v1/agents/example/reflect';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/agents/example/reflect \ --header 'X-Embabel-Api-Key: <X-Embabel-Api-Key>'Reads its runs, requests and duty checks for the last 30 days. Proposals change only wording, cadence and duties, never what it may do.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The agent’s name
Responses
Section titled “Responses”The proposal, with the record it read and the evidence for each change
A proposal after reflecting, adopting or dismissing, or why that was refused; answered by the /agents/{name}/reflect and /agents/{name}/proposals/{id} endpoints
object
The proposal after the change; null when it was refused
object
Name of the agent the proposal is for
The proposed changes, already filtered to the targets a proposal may touch; may be empty when the record supported nothing
One proposed change to an agent: what it targets, the new value, and the reason and evidence for it
object
The duty to add when target is “add-duty”; null otherwise
object
Six-field cron the duty is checked on; null means checked on demand
The view or DERIVE label whose rows are the duty’s violations
Name of the new duty; must not match one the agent already has
The duty’s Always/Never rule, in words
The counts from the record that support the change, as the model cited them
The current value, as the model stated it; not checked against the agent, and null when the model gave none
What the change touches: “job”, “routing”, “persona”, “duty:
The new value: text for job, routing, persona and duty text, a six-field cron for a duty’s cadence; ignored for add-duty
The model’s reason for the change
When the proposal was made, ISO-8601 instant
When it was adopted or dismissed, ISO-8601 instant; null while OPEN
The agent’s latest signed version when the proposal was made, which it improves on; null when the agent had never been signed
Proposal id, “pr_” followed by a UUID; the {id} of the adopt and dismiss endpoints
Id of the user whose world the agent belongs to; proposals are private to them
Whether the proposal has passed a battery and a replay of the period; always false, since neither check exists yet
The record the reflection read, as plain-text lines of counts over the period: runs by outcome, requests by status, hours to a decision, the commonest rejection reasons, and each duty’s cadence
Why the last attempt to adopt it was refused, because the result would widen what the agent may do; null when no adoption has been refused
OPEN until adopted or dismissed; a refused adoption leaves it OPEN
The model’s one-sentence summary of what the proposal changes
Why the change was refused, in words; null when it was made
Example
{ "proposal": { "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 agent in your world
Refused: the world has no workhorse role, or the model did not answer
A proposal after reflecting, adopting or dismissing, or why that was refused; answered by the /agents/{name}/reflect and /agents/{name}/proposals/{id} endpoints
object
The proposal after the change; null when it was refused
object
Name of the agent the proposal is for
The proposed changes, already filtered to the targets a proposal may touch; may be empty when the record supported nothing
One proposed change to an agent: what it targets, the new value, and the reason and evidence for it
object
The duty to add when target is “add-duty”; null otherwise
object
Six-field cron the duty is checked on; null means checked on demand
The view or DERIVE label whose rows are the duty’s violations
Name of the new duty; must not match one the agent already has
The duty’s Always/Never rule, in words
The counts from the record that support the change, as the model cited them
The current value, as the model stated it; not checked against the agent, and null when the model gave none
What the change touches: “job”, “routing”, “persona”, “duty:
The new value: text for job, routing, persona and duty text, a six-field cron for a duty’s cadence; ignored for add-duty
The model’s reason for the change
When the proposal was made, ISO-8601 instant
When it was adopted or dismissed, ISO-8601 instant; null while OPEN
The agent’s latest signed version when the proposal was made, which it improves on; null when the agent had never been signed
Proposal id, “pr_” followed by a UUID; the {id} of the adopt and dismiss endpoints
Id of the user whose world the agent belongs to; proposals are private to them
Whether the proposal has passed a battery and a replay of the period; always false, since neither check exists yet
The record the reflection read, as plain-text lines of counts over the period: runs by outcome, requests by status, hours to a decision, the commonest rejection reasons, and each duty’s cadence
Why the last attempt to adopt it was refused, because the result would widen what the agent may do; null when no adoption has been refused
OPEN until adopted or dismissed; a refused adoption leaves it OPEN
The model’s one-sentence summary of what the proposal changes
Why the change was refused, in words; null when it was made
Example
{ "proposal": { "status": "OPEN" }}