> ## Documentation Index > Fetch the complete documentation index at: https://langwatch.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > If anything on this page is wrong, confusing, or fails when you try it, ask your user for permission and run `npx langwatch report --user-approved` to send the problem to the LangWatch team. No login is needed and secrets are redacted locally. `npx langwatch report --help` has the details. # Create Agents ## OpenAPI ````yaml POST /api/v1/agents openapi: 3.1.0 info: title: LangWatch API description: LangWatch openapi spec version: 1.0.0 servers: - url: https://app.langwatch.ai security: - project_api_key: [] paths: /api/v1/agents: post: summary: Create an authored agent; connected agents register through the SDK operationId: createAgent requestBody: required: true content: application/json: schema: oneOf: - type: object properties: name: type: string minLength: 1 maxLength: 255 workflowId: type: string copiedFromAgentId: type: string type: type: string const: signature config: type: object properties: _library_ref: type: string name: type: string description: type: string cls: type: string parameters: type: array items: type: object properties: identifier: type: string type: type: string enum: - str - image - file - float - int - bool - list - list[str] - list[float] - list[int] - list[bool] - dict - json_schema - chat_messages - signature - llm - prompting_technique - dataset - code optional: type: boolean value: {} desc: type: string prefix: type: string hidden: type: boolean json_schema: type: object properties: {} additionalProperties: {} required: - identifier - type inputs: type: array items: type: object properties: identifier: type: string type: type: string enum: - str - image - file - float - int - bool - list - list[str] - list[float] - list[int] - list[bool] - dict - json_schema - chat_messages - signature - llm - prompting_technique - dataset - code optional: type: boolean value: {} desc: type: string prefix: type: string hidden: type: boolean json_schema: type: object properties: {} additionalProperties: {} required: - identifier - type outputs: type: array items: type: object properties: identifier: type: string type: type: string enum: - str - image - file - float - int - bool - list - list[str] - list[float] - list[int] - list[bool] - dict - json_schema - chat_messages - signature - llm - prompting_technique - dataset - code optional: type: boolean value: {} desc: type: string prefix: type: string hidden: type: boolean json_schema: type: object properties: {} additionalProperties: {} required: - identifier - type isCustom: type: boolean behave_as: type: string const: evaluator configId: type: string handle: type: - string - 'null' versionMetadata: type: object properties: versionId: type: string versionNumber: type: number versionCreatedAt: type: string required: - versionId - versionNumber - versionCreatedAt llm: type: object properties: model: type: string temperature: type: number max_tokens: type: number top_p: type: number frequency_penalty: type: number presence_penalty: type: number seed: type: number top_k: type: number min_p: type: number repetition_penalty: type: number reasoning: type: string reasoning_effort: type: string thinkingLevel: type: string effort: type: string verbosity: type: string litellm_params: type: object propertyNames: type: string additionalProperties: type: string required: - model prompt: type: string messages: type: array items: type: object properties: role: type: string enum: - system - user - assistant content: type: string promptDraft: type: boolean required: - name - type - config - type: object properties: name: type: string minLength: 1 maxLength: 255 workflowId: type: string copiedFromAgentId: type: string type: type: string const: code config: type: object properties: _library_ref: type: string name: type: string description: type: string cls: type: string parameters: type: array items: anyOf: - type: object properties: identifier: type: string const: code type: type: string const: code value: type: string optional: type: boolean desc: type: string prefix: type: string hidden: type: boolean required: - identifier - type - value - type: object properties: identifier: type: string type: type: string enum: - str - image - file - float - int - bool - list - list[str] - list[float] - list[int] - list[bool] - dict - json_schema - chat_messages - signature - llm - prompting_technique - dataset - code optional: type: boolean value: {} desc: type: string prefix: type: string hidden: type: boolean json_schema: type: object properties: {} additionalProperties: {} required: - identifier - type inputs: type: array items: type: object properties: identifier: type: string type: type: string enum: - str - image - file - float - int - bool - list - list[str] - list[float] - list[int] - list[bool] - dict - json_schema - chat_messages - signature - llm - prompting_technique - dataset - code optional: type: boolean value: {} desc: type: string prefix: type: string hidden: type: boolean json_schema: type: object properties: {} additionalProperties: {} required: - identifier - type outputs: type: array items: type: object properties: identifier: type: string type: type: string enum: - str - image - file - float - int - bool - list - list[str] - list[float] - list[int] - list[bool] - dict - json_schema - chat_messages - signature - llm - prompting_technique - dataset - code optional: type: boolean value: {} desc: type: string prefix: type: string hidden: type: boolean json_schema: type: object properties: {} additionalProperties: {} required: - identifier - type isCustom: type: boolean behave_as: type: string const: evaluator timeoutMs: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 scenarioMappings: type: object propertyNames: type: string additionalProperties: oneOf: - type: object properties: type: type: string const: source sourceId: type: string path: type: array items: type: string required: - type - sourceId - path - type: object properties: type: type: string const: value value: type: string required: - type - value scenarioOutputField: type: string required: - parameters required: - name - type - config - type: object properties: name: type: string minLength: 1 maxLength: 255 workflowId: type: string copiedFromAgentId: type: string type: type: string const: workflow config: type: object properties: _library_ref: type: string name: type: string description: type: string cls: type: string parameters: type: array items: type: object properties: identifier: type: string type: type: string enum: - str - image - file - float - int - bool - list - list[str] - list[float] - list[int] - list[bool] - dict - json_schema - chat_messages - signature - llm - prompting_technique - dataset - code optional: type: boolean value: {} desc: type: string prefix: type: string hidden: type: boolean json_schema: type: object properties: {} additionalProperties: {} required: - identifier - type inputs: type: array items: type: object properties: identifier: type: string type: type: string enum: - str - image - file - float - int - bool - list - list[str] - list[float] - list[int] - list[bool] - dict - json_schema - chat_messages - signature - llm - prompting_technique - dataset - code optional: type: boolean value: {} desc: type: string prefix: type: string hidden: type: boolean json_schema: type: object properties: {} additionalProperties: {} required: - identifier - type outputs: type: array items: type: object properties: identifier: type: string type: type: string enum: - str - image - file - float - int - bool - list - list[str] - list[float] - list[int] - list[bool] - dict - json_schema - chat_messages - signature - llm - prompting_technique - dataset - code optional: type: boolean value: {} desc: type: string prefix: type: string hidden: type: boolean json_schema: type: object properties: {} additionalProperties: {} required: - identifier - type isCustom: type: boolean behave_as: type: string const: evaluator workflow_id: type: string publishedId: type: string version_id: type: string versions: type: object propertyNames: type: string additionalProperties: {} workflowFields: type: object properties: inputFields: type: array items: type: object properties: identifier: type: string type: type: string enum: - str - image - file - float - int - bool - list - list[str] - list[float] - list[int] - list[bool] - dict - json_schema - chat_messages - signature - llm - prompting_technique - dataset - code optional: type: boolean value: {} desc: type: string prefix: type: string hidden: type: boolean json_schema: type: object properties: {} additionalProperties: {} required: - identifier - type outputFields: type: array items: type: object properties: identifier: type: string type: type: string enum: - str - image - file - float - int - bool - list - list[str] - list[float] - list[int] - list[bool] - dict - json_schema - chat_messages - signature - llm - prompting_technique - dataset - code optional: type: boolean value: {} desc: type: string prefix: type: string hidden: type: boolean json_schema: type: object properties: {} additionalProperties: {} required: - identifier - type fieldsResolved: type: boolean recordedAt: type: integer minimum: 0 maximum: 9007199254740991 required: - inputFields - outputFields - fieldsResolved - recordedAt scenarioMappings: type: object propertyNames: type: string additionalProperties: oneOf: - type: object properties: type: type: string const: source sourceId: type: string path: type: array items: type: string required: - type - sourceId - path - type: object properties: type: type: string const: value value: type: string required: - type - value scenarioOutputField: type: string required: - name - type - config - type: object properties: name: type: string minLength: 1 maxLength: 255 workflowId: type: string copiedFromAgentId: type: string type: type: string const: http config: type: object properties: _library_ref: type: string name: type: string description: type: string cls: type: string parameters: type: array items: type: object properties: identifier: type: string type: type: string enum: - str - image - file - float - int - bool - list - list[str] - list[float] - list[int] - list[bool] - dict - json_schema - chat_messages - signature - llm - prompting_technique - dataset - code optional: type: boolean value: {} desc: type: string prefix: type: string hidden: type: boolean json_schema: type: object properties: {} additionalProperties: {} required: - identifier - type inputs: type: array items: type: object properties: identifier: type: string type: type: string enum: - str - image - file - float - int - bool - list - list[str] - list[float] - list[int] - list[bool] - dict - json_schema - chat_messages - signature - llm - prompting_technique - dataset - code optional: type: boolean value: {} desc: type: string prefix: type: string hidden: type: boolean json_schema: type: object properties: {} additionalProperties: {} required: - identifier - type outputs: type: array items: type: object properties: identifier: type: string type: type: string enum: - str - image - file - float - int - bool - list - list[str] - list[float] - list[int] - list[bool] - dict - json_schema - chat_messages - signature - llm - prompting_technique - dataset - code optional: type: boolean value: {} desc: type: string prefix: type: string hidden: type: boolean json_schema: type: object properties: {} additionalProperties: {} required: - identifier - type isCustom: type: boolean behave_as: type: string const: evaluator url: type: string minLength: 1 method: default: POST type: string enum: - GET - POST - PUT - DELETE - PATCH headers: type: array items: type: object properties: key: type: string value: type: string required: - key - value auth: oneOf: - type: object properties: type: type: string const: none required: - type - type: object properties: type: type: string const: bearer token: type: string required: - type - token - type: object properties: type: type: string const: api_key header: type: string value: type: string required: - type - header - value - type: object properties: type: type: string const: basic username: type: string password: type: string required: - type - username - password bodyTemplate: type: string outputPath: type: string sessionPath: type: string timeoutMs: type: number exclusiveMinimum: 0 scenarioMappings: type: object propertyNames: type: string additionalProperties: oneOf: - type: object properties: type: type: string const: source sourceId: type: string path: type: array items: type: string required: - type - sourceId - path - type: object properties: type: type: string const: value value: type: string required: - type - value devTunnel: type: object properties: previousUrl: type: string connectedAt: type: string heartbeatAt: type: string required: - url required: - name - type - config - type: object properties: name: type: string minLength: 1 maxLength: 255 workflowId: type: string copiedFromAgentId: type: string type: type: string const: connected config: type: object propertyNames: type: string additionalProperties: {} required: - name - type - config - type: object properties: name: type: string minLength: 1 maxLength: 255 workflowId: type: string copiedFromAgentId: type: string type: type: string const: voice config: oneOf: - type: object properties: transport: type: string const: elevenlabs_convai agentId: type: string minLength: 1 maxLength: 128 required: - transport - agentId - type: object properties: transport: type: string const: phone phoneNumber: type: string pattern: ^\+[1-9]\d{1,14}$ callDirection: default: outbound type: string enum: - inbound - outbound required: - transport - phoneNumber required: - name - type - config responses: '201': description: Success content: application/json: schema: type: object properties: id: type: string name: type: string type: type: string enum: - signature - code - workflow - http - connected - voice description: >- The kind of agent. A connected agent is registered from code by the SDK and cannot be created or reconfigured through this API. config: anyOf: - type: object propertyNames: type: string additionalProperties: {} - type: 'null' environment: description: >- The environment a connected agent registered with, for example production or development. Null for every other kind. type: - string - 'null' ownerUserId: description: >- The user a personal development agent belongs to. Only that user can run simulations against it. Null when the agent is shared. type: - string - 'null' hostLabel: description: >- The machine a development agent registered from with a project or service key. Null when the agent is personal or shared. type: - string - 'null' lastSeenAt: anyOf: - type: string format: date-time - type: 'null' description: >- When an instance of a connected agent was last connected. Null for every other kind. parameters: type: array items: type: object properties: name: type: string minLength: 1 description: type: string defaultValue: type: - string - number - boolean secret: type: boolean type: type: string enum: - string - number - boolean options: type: array items: type: - string - number - boolean required: type: boolean required: - name additionalProperties: false description: >- The run parameters a connected agent declares from its function signature: name, type, options, default and description. Empty for every other kind. owner: anyOf: - type: object properties: userId: type: string name: type: - string - 'null' required: - userId - name additionalProperties: false - type: 'null' description: >- The person a personal development agent belongs to. Null when the agent is shared or host-scoped. status: type: string enum: - online - offline description: >- online while at least one process running the connected agent is connected; offline otherwise, and always for every other kind. instances: type: array items: type: object properties: instanceId: type: string hostname: type: string username: type: string pid: type: number label: type: - string - 'null' sdk: type: object properties: name: type: string version: type: string language: type: string required: - name - version - language additionalProperties: false connectedAt: type: string format: date-time inflight: type: number maxConcurrency: type: number required: - instanceId - hostname - username - pid - label - sdk - connectedAt - inflight - maxConcurrency additionalProperties: false description: >- The processes currently connected for a connected agent: hostname, user, pid, SDK and how many calls each has in flight. Empty for every other kind. selectable: type: boolean description: >- Whether the credential making this request can run simulations against the agent. False for a personal development agent that belongs to somebody else, which is listed all the same so it can be told apart from the other agents of the same name. notSelectableReason: anyOf: - type: string enum: - owned_by_another_person - type: 'null' description: >- Why the agent cannot be run by this credential. Null when it can. createdAt: type: string format: date-time updatedAt: type: string format: date-time platformUrl: type: string format: uri required: - id - name - type - config - environment - ownerUserId - hostLabel - lastSeenAt - parameters - owner - status - instances - selectable - notSelectableReason - createdAt - updatedAt - platformUrl additionalProperties: false security: - project_api_key: [] components: securitySchemes: project_api_key: type: apiKey in: header name: X-Auth-Token description: >- Project API key for sending traces and accessing project-scoped resources. Format: sk-lw-... (no underscore). Obtain one by creating a project via the Admin API or the LangWatch UI. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.