Developer documentation > API reference > Agents

Agents¶

The following endpoints outline how to manage agents.

Request chat completion by custom model ID¶

Operation path: POST /api/v2/genai/agents/fromCustomModel/{customModelId}/chat/

Authentication requirements: BearerAuth

Create a chat completion request for an agent using a custom model.

Body parameter¶

{
  "additionalProperties": true,
  "description": "Represents a chat completion request for an agent.",
  "properties": {
    "messages": {
      "description": "A list of messages comprising the conversation so far.",
      "items": {
        "additionalProperties": true,
        "description": "Represents a message in a chat conversation.",
        "properties": {
          "content": {
            "anyOf": [
              {
                "maxLength": 50000,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "The contents of the message.",
            "title": "content"
          },
          "role": {
            "description": "The role of the author of this message.",
            "title": "role",
            "type": "string"
          }
        },
        "required": [
          "role"
        ],
        "title": "AgentMessage",
        "type": "object"
      },
      "title": "messages",
      "type": "array"
    },
    "model": {
      "anyOf": [
        {
          "maxLength": 5000,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "The model identifier to use for completion following OpenAI API notation.",
      "title": "model"
    },
    "tracingContext": {
      "anyOf": [
        {
          "description": "Represents a custom tracing context for a chat completion request.",
          "properties": {
            "attributes": {
              "anyOf": [
                {
                  "additionalProperties": {
                    "type": "string"
                  },
                  "type": "object"
                },
                {
                  "type": "null"
                }
              ],
              "description": "The attributes of the tracing context.",
              "title": "attributes"
            },
            "entityId": {
              "description": "The ID of the entity in context of which the agent request is performed. Should be an entity which user has access to.",
              "title": "entityId",
              "type": "string"
            },
            "entityType": {
              "description": "Type of an entity in context of which the agent request is performed.",
              "enum": [
                "deployment",
                "use_case"
              ],
              "title": "TracingContextEntityType",
              "type": "string"
            }
          },
          "required": [
            "entityId",
            "entityType",
            "attributes"
          ],
          "title": "AgentTracingContext",
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "description": "Optional tracing context for the chat completion request."
    }
  },
  "required": [
    "messages"
  ],
  "title": "AgentChatCompletionRequest",
  "type": "object"
}

Parameters

Name	In	Type	Required	Description
customModelId	path	string	true	The ID of a custom model to use for the chat completion.
body	body	AgentChatCompletionRequest	true	none

Example responses¶

202 Response

{}

Responses¶

Status	Meaning	Description	Schema
202	Accepted	Successful Response	Inline
422	Unprocessable Entity	Validation Error	HTTPValidationErrorResponse

Response Schema¶

Obtain chat completion response by custom model ID¶

Operation path: GET /api/v2/genai/agents/fromCustomModel/{customModelId}/chat/{chatCompletionId}/

Authentication requirements: BearerAuth

Obtain chat completion response for a given chat completion ID.

Parameters

Name	In	Type	Required	Description
customModelId	path	string	true	The ID of a custom model to use for the chat completion.
chatCompletionId	path	string	true	The ID of a chat completion object.

Example responses¶

200 Response

{
  "additionalProperties": true,
  "description": "Chat completion response from an agent.",
  "properties": {
    "choices": {
      "anyOf": [
        {
          "items": {
            "additionalProperties": true,
            "description": "Represents a single choice in the chat completion response.",
            "properties": {
              "message": {
                "additionalProperties": true,
                "description": "Represents a message in a chat conversation.",
                "properties": {
                  "content": {
                    "anyOf": [
                      {
                        "maxLength": 50000,
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "description": "The contents of the message.",
                    "title": "content"
                  },
                  "role": {
                    "description": "The role of the author of this message.",
                    "title": "role",
                    "type": "string"
                  }
                },
                "required": [
                  "role"
                ],
                "title": "AgentMessage",
                "type": "object"
              }
            },
            "required": [
              "message"
            ],
            "title": "AgentChoice",
            "type": "object"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "description": "A list of agent choices. Can be more than one. None when failed.",
      "title": "choices"
    },
    "errorDetails": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Detailed error information if the chat completion failed.",
      "title": "errorDetails"
    },
    "errorMessage": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Error message if the chat completion failed.",
      "title": "errorMessage"
    }
  },
  "title": "AgentChatCompletionResponse",
  "type": "object"
}

Responses¶

Status	Meaning	Description	Schema
200	OK	Successful Response	AgentChatCompletionResponse
422	Unprocessable Entity	Validation Error	HTTPValidationErrorResponse

Schemas¶

AgentChatCompletionRequest

{
  "additionalProperties": true,
  "description": "Represents a chat completion request for an agent.",
  "properties": {
    "messages": {
      "description": "A list of messages comprising the conversation so far.",
      "items": {
        "additionalProperties": true,
        "description": "Represents a message in a chat conversation.",
        "properties": {
          "content": {
            "anyOf": [
              {
                "maxLength": 50000,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "The contents of the message.",
            "title": "content"
          },
          "role": {
            "description": "The role of the author of this message.",
            "title": "role",
            "type": "string"
          }
        },
        "required": [
          "role"
        ],
        "title": "AgentMessage",
        "type": "object"
      },
      "title": "messages",
      "type": "array"
    },
    "model": {
      "anyOf": [
        {
          "maxLength": 5000,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "The model identifier to use for completion following OpenAI API notation.",
      "title": "model"
    },
    "tracingContext": {
      "anyOf": [
        {
          "description": "Represents a custom tracing context for a chat completion request.",
          "properties": {
            "attributes": {
              "anyOf": [
                {
                  "additionalProperties": {
                    "type": "string"
                  },
                  "type": "object"
                },
                {
                  "type": "null"
                }
              ],
              "description": "The attributes of the tracing context.",
              "title": "attributes"
            },
            "entityId": {
              "description": "The ID of the entity in context of which the agent request is performed. Should be an entity which user has access to.",
              "title": "entityId",
              "type": "string"
            },
            "entityType": {
              "description": "Type of an entity in context of which the agent request is performed.",
              "enum": [
                "deployment",
                "use_case"
              ],
              "title": "TracingContextEntityType",
              "type": "string"
            }
          },
          "required": [
            "entityId",
            "entityType",
            "attributes"
          ],
          "title": "AgentTracingContext",
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "description": "Optional tracing context for the chat completion request."
    }
  },
  "required": [
    "messages"
  ],
  "title": "AgentChatCompletionRequest",
  "type": "object"
}

AgentChatCompletionRequest

Properties¶

Name	Type	Required	Restrictions	Description
messages	[AgentMessage]	true		A list of messages comprising the conversation so far.
model	any	false		The model identifier to use for completion following OpenAI API notation.

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	string	false	maxLength: 5000	none

or

Name	Type	Required	Restrictions	Description
» anonymous	null	false		none

continued

Name	Type	Required	Restrictions	Description
tracingContext	any	false		Optional tracing context for the chat completion request.

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	AgentTracingContext	false		Represents a custom tracing context for a chat completion request.

or

Name	Type	Required	Restrictions	Description
» anonymous	null	false		none

AgentChatCompletionResponse

{
  "additionalProperties": true,
  "description": "Chat completion response from an agent.",
  "properties": {
    "choices": {
      "anyOf": [
        {
          "items": {
            "additionalProperties": true,
            "description": "Represents a single choice in the chat completion response.",
            "properties": {
              "message": {
                "additionalProperties": true,
                "description": "Represents a message in a chat conversation.",
                "properties": {
                  "content": {
                    "anyOf": [
                      {
                        "maxLength": 50000,
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "description": "The contents of the message.",
                    "title": "content"
                  },
                  "role": {
                    "description": "The role of the author of this message.",
                    "title": "role",
                    "type": "string"
                  }
                },
                "required": [
                  "role"
                ],
                "title": "AgentMessage",
                "type": "object"
              }
            },
            "required": [
              "message"
            ],
            "title": "AgentChoice",
            "type": "object"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "description": "A list of agent choices. Can be more than one. None when failed.",
      "title": "choices"
    },
    "errorDetails": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Detailed error information if the chat completion failed.",
      "title": "errorDetails"
    },
    "errorMessage": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Error message if the chat completion failed.",
      "title": "errorMessage"
    }
  },
  "title": "AgentChatCompletionResponse",
  "type": "object"
}

AgentChatCompletionResponse

Properties¶

Name	Type	Required	Restrictions	Description
choices	any	false		A list of agent choices. Can be more than one. None when failed.

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	[AgentChoice]	false		[Represents a single choice in the chat completion response.]

or

Name	Type	Required	Restrictions	Description
» anonymous	null	false		none

continued

Name	Type	Required	Restrictions	Description
errorDetails	any	false		Detailed error information if the chat completion failed.

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	string	false		none

or

Name	Type	Required	Restrictions	Description
» anonymous	null	false		none

continued

Name	Type	Required	Restrictions	Description
errorMessage	any	false		Error message if the chat completion failed.

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	string	false		none

or

Name	Type	Required	Restrictions	Description
» anonymous	null	false		none

AgentChoice

{
  "additionalProperties": true,
  "description": "Represents a single choice in the chat completion response.",
  "properties": {
    "message": {
      "additionalProperties": true,
      "description": "Represents a message in a chat conversation.",
      "properties": {
        "content": {
          "anyOf": [
            {
              "maxLength": 50000,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "The contents of the message.",
          "title": "content"
        },
        "role": {
          "description": "The role of the author of this message.",
          "title": "role",
          "type": "string"
        }
      },
      "required": [
        "role"
      ],
      "title": "AgentMessage",
      "type": "object"
    }
  },
  "required": [
    "message"
  ],
  "title": "AgentChoice",
  "type": "object"
}

AgentChoice

Properties¶

Name	Type	Required	Restrictions	Description
message	AgentMessage	true		The message content of the choice.

AgentMessage

{
  "additionalProperties": true,
  "description": "Represents a message in a chat conversation.",
  "properties": {
    "content": {
      "anyOf": [
        {
          "maxLength": 50000,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "The contents of the message.",
      "title": "content"
    },
    "role": {
      "description": "The role of the author of this message.",
      "title": "role",
      "type": "string"
    }
  },
  "required": [
    "role"
  ],
  "title": "AgentMessage",
  "type": "object"
}

AgentMessage

Properties¶

Name	Type	Required	Restrictions	Description
content	any	false		The contents of the message.

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	string	false	maxLength: 50000	none

or

Name	Type	Required	Restrictions	Description
» anonymous	null	false		none

continued

Name	Type	Required	Restrictions	Description
role	string	true		The role of the author of this message.

AgentTracingContext

{
  "description": "Represents a custom tracing context for a chat completion request.",
  "properties": {
    "attributes": {
      "anyOf": [
        {
          "additionalProperties": {
            "type": "string"
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "description": "The attributes of the tracing context.",
      "title": "attributes"
    },
    "entityId": {
      "description": "The ID of the entity in context of which the agent request is performed. Should be an entity which user has access to.",
      "title": "entityId",
      "type": "string"
    },
    "entityType": {
      "description": "Type of an entity in context of which the agent request is performed.",
      "enum": [
        "deployment",
        "use_case"
      ],
      "title": "TracingContextEntityType",
      "type": "string"
    }
  },
  "required": [
    "entityId",
    "entityType",
    "attributes"
  ],
  "title": "AgentTracingContext",
  "type": "object"
}

AgentTracingContext

Properties¶

Name	Type	Required	Restrictions	Description
attributes	any	true		The attributes of the tracing context.

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	object	false		none
»» additionalProperties	string	false		none

or

Name	Type	Required	Restrictions	Description
» anonymous	null	false		none

continued

Name	Type	Required	Restrictions	Description
entityId	string	true		The ID of the entity in context of which the agent request is performed. Should be an entity which user has access to.
entityType	TracingContextEntityType	true		The type of an entity in context of which the agent request is performed. Should be an entity which user has access to.

HTTPValidationErrorResponse

{
  "properties": {
    "detail": {
      "items": {
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "integer"
                }
              ]
            },
            "title": "loc",
            "type": "array"
          },
          "msg": {
            "title": "msg",
            "type": "string"
          },
          "type": {
            "title": "type",
            "type": "string"
          }
        },
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError",
        "type": "object"
      },
      "title": "detail",
      "type": "array"
    }
  },
  "title": "HTTPValidationErrorResponse",
  "type": "object"
}

HTTPValidationErrorResponse

Properties¶

Name	Type	Required	Restrictions	Description
detail	[ValidationError]	false		none

TracingContextEntityType

{
  "description": "Type of an entity in context of which the agent request is performed.",
  "enum": [
    "deployment",
    "use_case"
  ],
  "title": "TracingContextEntityType",
  "type": "string"
}

TracingContextEntityType

Properties¶

Name	Type	Required	Restrictions	Description
TracingContextEntityType	string	false		Type of an entity in context of which the agent request is performed.

Enumerated Values¶

Property	Value
TracingContextEntityType	[`deployment`, `use_case`]

ValidationError

{
  "properties": {
    "loc": {
      "items": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "integer"
          }
        ]
      },
      "title": "loc",
      "type": "array"
    },
    "msg": {
      "title": "msg",
      "type": "string"
    },
    "type": {
      "title": "type",
      "type": "string"
    }
  },
  "required": [
    "loc",
    "msg",
    "type"
  ],
  "title": "ValidationError",
  "type": "object"
}

ValidationError

Properties¶

Name	Type	Required	Restrictions	Description
loc	[anyOf]	true		none

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	string	false		none

or

Name	Type	Required	Restrictions	Description
» anonymous	integer	false		none

continued

Name	Type	Required	Restrictions	Description
msg	string	true		none
type	string	true		none