Skip to content

Find or create an agent version

POST
/api/v1/agent_version
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.

AgentVersion_DetailsForCreate
object
agent_id
Agent_Id

A valid agent ID

string
Example
013xrzp12g3nqk8ns6jadrqmpgrjkeny
agent_schema_version_id
One of:
AgentSchemaVersion_Id

A valid agent schema version ID

string
Example
013xrzp12g3nqk8ns6jadrqmpgrjkeny
description
One of:

Deprecated. Accepted for backward compatibility; ignored. Use agents/update to set the agent description.

string
execution_mode
One of:
string
Allowed values: hosted remote
Example
hosted
external_identifier
string
hosted_configuration
One of:
AgentVersion_HostedConfiguration
object
enabled_tools

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

Array<string>
unique items
Allowed values: current_time knowledgebases
Example
[
"current_time"
]
judge_criterion

Criterion rendered into the system prompt when a hosted run starts. Omitted when the system prompt is used as written

string
Example
Decide whether the agent completed every request.
llm_provider_model_id
required
LlmProviderModel_Id

A valid LLM provider model ID

string
Example
013xrzp12g3nqk8ns6jadrqmpgrjkeny
mode
required

Hosted run mode: one model turn, or a conversation

string
Allowed values: single_turn conversation
Example
conversation
system_prompt
required

System prompt for each hosted run. When judge_criterion is set, this is a Liquid template and criterion is its only variable

string
Example
You are a helpful assistant.
id
One of:
AgentVersion_Id

A valid agent version ID

string
Example
013xrzp12g3nqk8ns6jadrqmpgrjkeny
name
One of:

Deprecated. Accepted for backward compatibility; ignored. Use agents/update to set the agent name.

string
runtime_environment
One of:
AgentVersion_RuntimeEnvironment
object
agent_sdk
One of:

List of package name and version strings (e.g. “package@1.0.0”)

Array<string>
os
One of:

Operating system (e.g. “linux”)

string
prefactor_sdk
One of:

List of package name and version strings (e.g. “package@1.0.0”)

Array<string>
runtime
One of:

Language runtime version (e.g. “python@3.12”)

string

Success

Media typeapplication/json
object
details
required
AgentVersion_Details
object
account_id
required
Account_Id

A valid account ID

string
agent_id
required
Agent_Id

A valid agent ID

string
agent_risk_version_id
required
One of:
AgentRiskVersion_Id

A valid agent risk version ID

string
agent_schema_version_id
required
AgentSchemaVersion_Id

A valid agent schema version ID

string
current_agent_deployment_refs
required

Agent deployments that pin this version as their current version (empty if none).

Array<string>
execution_mode
required

Whether Prefactor executes this version (hosted) or an external agent reports telemetry (remote)

string
Allowed values: hosted remote
external_identifier
required

External identifier for the agent version

string
external_identifier_repeats
required

Count of rows sharing this external identifier (helps distinguish duplicates).

integer
hosted_configuration
required
One of:
AgentVersion_HostedConfiguration
object
enabled_tools

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

Array<string>
unique items
Allowed values: current_time knowledgebases
judge_criterion

Criterion rendered into the system prompt when a hosted run starts. Omitted when the system prompt is used as written

string
llm_provider_model_id
required
LlmProviderModel_Id

A valid LLM provider model ID

string
mode
required

Hosted run mode: one model turn, or a conversation

string
Allowed values: single_turn conversation
system_prompt
required

System prompt for each hosted run. When judge_criterion is set, this is a Liquid template and criterion is its only variable

string
id
required
AgentVersion_Id

A valid agent version ID

string
inserted_at
required

When the agent version was created

string format: date-time
observed_classification
One of:
string
Allowed values: unknown public internal confidential restricted secret
runtime_environment
required
One of:
AgentVersion_RuntimeEnvironment
object
agent_sdk
One of:

List of package name and version strings (e.g. “package@1.0.0”)

Array<string>
os
One of:

Operating system (e.g. “linux”)

string
prefactor_sdk
One of:

List of package name and version strings (e.g. “package@1.0.0”)

Array<string>
runtime
One of:

Language runtime version (e.g. “python@3.12”)

string
type
required

Type of resource (always ‘agent_version’)

string
Allowed values: agent_version
updated_at
required

When the agent version was last updated

string format: date-time
status
required
string
Allowed values: success
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"
}

Error

Media typeapplication/json
One of:
object
code
required
string
Allowed values: bad_request bad_authtoken not_authenticated not_permitted not_implemented unknown not_found unexpected_ref_type unexpected invalid_action invalid_state alert_unknown alert_already_cleared invalid_value required_value idempotency_key_already_used temporarily_unavailable conflict
message
required
string
status
required
string
Allowed values: error
Example
{
"code": "bad_request",
"status": "error"
}