Find or create an agent version
const url = 'https://app.prefactorai.com/api/v1/agent_version';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"agent_id":"013xrzp12g3nqk8ns6jadrqmpgrjkeny","agent_schema_version_id":"013xrzp12g3nqk8ns6jadrqmpgrjkeny","description":null,"execution_mode":"hosted","external_identifier":"example","hosted_configuration":null,"id":"013xrzp12g3nqk8ns6jadrqmpgrjkeny","name":null,"runtime_environment":null}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://app.prefactorai.com/api/v1/agent_version \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "agent_id": "013xrzp12g3nqk8ns6jadrqmpgrjkeny", "agent_schema_version_id": "013xrzp12g3nqk8ns6jadrqmpgrjkeny", "description": null, "execution_mode": "hosted", "external_identifier": "example", "hosted_configuration": null, "id": "013xrzp12g3nqk8ns6jadrqmpgrjkeny", "name": null, "runtime_environment": null }'Returns the matching agent version if one already exists for this agent with the same external identifier, schema version, runtime environment, execution mode, and hosted configuration. Otherwise creates a new version. When hosted_configuration.judge_criterion is set, hosted_configuration.system_prompt must be a Liquid template whose only variable is criterion.
Authorizations
Section titled “Authorizations”Request Body
Section titled “Request Body”object
A valid agent ID
Example
013xrzp12g3nqk8ns6jadrqmpgrjkenyA valid agent schema version ID
Example
013xrzp12g3nqk8ns6jadrqmpgrjkenyNull
object
Built-in tools each hosted run receives: current_time and knowledgebases. knowledgebases gives each run kb_list, kb_read and kb_search over the agent’s active linked knowledgebases. A run gets those tools only when the agent has active linked knowledgebases when the run starts, and the tool list does not change during the run. The list must not repeat a tool. Omit or send an empty list for no tools
Example
[ "current_time"]Criterion rendered into the system prompt when a hosted run starts. Omitted when the system prompt is used as written
Example
Decide whether the agent completed every request.A valid LLM provider model ID
Example
013xrzp12g3nqk8ns6jadrqmpgrjkenyHosted run mode: one model turn, or a conversation
Example
conversationSystem prompt for each hosted run. When judge_criterion is set, this is a Liquid template and criterion is its only variable
Example
You are a helpful assistant.Null
A valid agent version ID
Example
013xrzp12g3nqk8ns6jadrqmpgrjkenyNull
object
List of package name and version strings (e.g. “package@1.0.0”)
Null
List of package name and version strings (e.g. “package@1.0.0”)
Null
Null
Responses
Section titled “Responses”Success
object
object
A valid account ID
A valid agent ID
A valid agent risk version ID
Null
A valid agent schema version ID
Agent deployments that pin this version as their current version (empty if none).
Whether Prefactor executes this version (hosted) or an external agent reports telemetry (remote)
External identifier for the agent version
Count of rows sharing this external identifier (helps distinguish duplicates).
object
Built-in tools each hosted run receives: current_time and knowledgebases. knowledgebases gives each run kb_list, kb_read and kb_search over the agent’s active linked knowledgebases. A run gets those tools only when the agent has active linked knowledgebases when the run starts, and the tool list does not change during the run. The list must not repeat a tool. Omit or send an empty list for no tools
Criterion rendered into the system prompt when a hosted run starts. Omitted when the system prompt is used as written
A valid LLM provider model ID
Hosted run mode: one model turn, or a conversation
System prompt for each hosted run. When judge_criterion is set, this is a Liquid template and criterion is its only variable
Null
A valid agent version ID
When the agent version was created
object
List of package name and version strings (e.g. “package@1.0.0”)
Null
List of package name and version strings (e.g. “package@1.0.0”)
Null
Null
Type of resource (always ‘agent_version’)
When the agent version was last updated
Example
{ "details": { "account_id": "013xrzp12g3nqk8ns6jadrqmpgrjkeny", "agent_id": "013xrzp12g3nqk8ns6jadrqmpgrjkeny", "agent_risk_version_id": "013xrzp12g3nqk8ns6jadrqmpgrjkeny", "agent_schema_version_id": "013xrzp12g3nqk8ns6jadrqmpgrjkeny", "current_agent_deployment_refs": [ "013xrzp12g3nqk8ns6jadrqmpgrjkeny" ], "execution_mode": "hosted", "external_identifier": "v1.0.0", "hosted_configuration": null, "id": "013xrzp12g3nqk8ns6jadrqmpgrjkeny", "inserted_at": "2024-01-01T00:00:00Z", "observed_classification": "unknown", "runtime_environment": null, "type": "agent_version", "updated_at": "2024-01-01T00:00:00Z" }, "status": "success"}default
Section titled “default”Error
object
object
object
object
Milliseconds until the client may retry.
object
A valid knowledgebase document revision ID
Example
{ "code": "bad_request", "status": "error"}