agents

Upsert Agent

Create an Agent or update it with a new version if it already exists.

Agents are identified by the ID or their path. The parameters (i.e. the template, temperature, model etc.) and tools determine the versions of the Agent.

You can provide version_name and version_description to identify and describe your versions. Version names must be unique within an Agent - attempting to create a version with a name that already exists will result in a 409 Conflict error.

post/agents

Request

  • Base URL: https://api.humanloop.com/v5
  • URL: https://api.humanloop.com/v5/agents
  • Auth: API key in header X-API-KEY

Request body

pathstring

Path of the Agent, including the name. This locates the Agent in the Humanloop filesystem and is used as as a unique identifier. For example: folder/name or just name.

idstring

ID for an existing Agent.

modelstring required

The model instance used, e.g. gpt-4. See supported models

endpoint'complete' | 'chat' | 'edit'

Supported model provider endpoints.

template_language'default' | 'jinja'

Template engine to use for rendering templates.

provider'anthropic' | 'bedrock' | 'cohere' | 'deepseek' | 'google' | 'groq' | 'mock' | 'openai' | 'openai_azure' | 'replicate'

Supported model providers.

max_tokensinteger

The maximum number of tokens to generate. Provide max_tokens=-1 to dynamically calculate the maximum number of tokens to generate given the length of the prompt

temperaturenumber double

What sampling temperature to use when making a generation. Higher values means the model will be more creative.

top_pnumber double

An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass.

presence_penaltynumber double

Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the generation so far.

frequency_penaltynumber double

Number between -2.0 and 2.0. Positive values penalize new tokens based on how frequently they appear in the generation so far.

otherobject

Other parameter values to be passed to the provider call.

seedinteger

If specified, model will make a best effort to sample deterministically, but it is not guaranteed.

attributesobject

Additional fields to describe the Prompt. Helpful to separate Prompt versions from each other with details on how they were created or used.

max_iterationsinteger

The maximum number of iterations the Agent can run. This is used to limit the number of times the Agent model is called.

version_namestring

Unique name for the Prompt version. Each Prompt can only have one version with a given name.

version_descriptionstring

Description of the Version.

descriptionstring

Description of the Prompt.

tagsstring[]

List of tags associated with this prompt.

readmestring

Long description of the Prompt.

Response

Successful Response

pathstring required

Path of the Agent, including the name, which is used as a unique identifier.

idstring required

Unique identifier for the Agent.

directory_idstring

ID of the directory that the file is in on Humanloop.

modelstring required

The model instance used, e.g. gpt-4. See supported models

endpoint'complete' | 'chat' | 'edit'

Supported model provider endpoints.

template_language'default' | 'jinja'

Template engine to use for rendering templates.

provider'anthropic' | 'bedrock' | 'cohere' | 'deepseek' | 'google' | 'groq' | 'mock' | 'openai' | 'openai_azure' | 'replicate'

Supported model providers.

max_tokensinteger

The maximum number of tokens to generate. Provide max_tokens=-1 to dynamically calculate the maximum number of tokens to generate given the length of the prompt

temperaturenumber double

What sampling temperature to use when making a generation. Higher values means the model will be more creative.

top_pnumber double

An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass.

presence_penaltynumber double

Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the generation so far.

frequency_penaltynumber double

Number between -2.0 and 2.0. Positive values penalize new tokens based on how frequently they appear in the generation so far.

otherobject

Other parameter values to be passed to the provider call.

seedinteger

If specified, model will make a best effort to sample deterministically, but it is not guaranteed.

attributesobject

Additional fields to describe the Prompt. Helpful to separate Prompt versions from each other with details on how they were created or used.

max_iterationsinteger

The maximum number of iterations the Agent can run. This is used to limit the number of times the Agent model is called.

version_namestring

Unique name for the Agent version. Version names must be unique for a given Agent.

version_descriptionstring

Description of the version, e.g., the changes made in this version.

descriptionstring

Description of the Agent.

tagsstring[]

List of tags associated with the file.

readmestring

Long description of the file.

namestring required

Name of the Agent.

schemaobject

The JSON schema for the Prompt.

version_idstring required

Unique identifier for the specific Agent Version. If no query params provided, the default deployed Agent Version is returned.

type'agent'
created_atstring date-time required
updated_atstring date-time required
created_byunknown
committed_byunknown
committed_atstring date-time

The date and time the Agent Version was committed.

status'uncommitted' | 'committed' | 'deleted' required

An enumeration.

last_used_atstring date-time required
version_logs_countinteger required

The number of logs that have been generated for this Agent Version

total_logs_countinteger required

The number of logs that have been generated across all Agent Versions

raw_file_contentstring

The raw content of the Agent. Corresponds to the .agent file.

Changes

No recorded changes to this operation across all 1 revision of this API.