telnyx 5.167.0 → 5.168.0

data/rbi/telnyx/models/ai/assistants/update_assistant.rbi

@@ -15,6 +15,25 @@ module Telnyx
               )
             end
 
+          # A2A agents this assistant can delegate to. Tools are not stored here: at the
+          # start of every conversation each agent's card is fetched and one tool is derived
+          # per skill the card advertises, named `a2a_<name>_<skill_id>`. The following
+          # limits are not enforced when the assistant is saved, and anything past them is
+          # dropped when the conversation starts: 64 agents per assistant, 64 skills per
+          # card, 128 derived tools per assistant, and a 6 second budget for all card
+          # fetches combined. An agent whose card cannot be fetched costs the assistant that
+          # capability for the conversation; it does not fail the call. Omit this field to
+          # leave the assistant's agents unchanged; send an empty array to remove them all.
+          sig { returns(T.nilable(T::Array[Telnyx::AI::AssistantA2AAgent])) }
+          attr_reader :a2a_agents
+
+          sig do
+            params(
+              a2a_agents: T::Array[Telnyx::AI::AssistantA2AAgent::OrHash]
+            ).void
+          end
+          attr_writer :a2a_agents
+
           # Conversation flow as supplied by API clients (create / update).
           #
           # A directed graph of `FlowNodeReq` connected by `FlowEdge`s. Validation enforces
@@ -354,6 +373,7 @@ module Telnyx
 
           sig do
             params(
+              a2a_agents: T::Array[Telnyx::AI::AssistantA2AAgent::OrHash],
               conversation_flow: Telnyx::AI::ConversationFlowReq::OrHash,
               description: String,
               dynamic_variables: T::Hash[Symbol, T.anything],
@@ -405,6 +425,16 @@ module Telnyx
             ).returns(T.attached_class)
           end
           def self.new(
+            # A2A agents this assistant can delegate to. Tools are not stored here: at the
+            # start of every conversation each agent's card is fetched and one tool is derived
+            # per skill the card advertises, named `a2a_<name>_<skill_id>`. The following
+            # limits are not enforced when the assistant is saved, and anything past them is
+            # dropped when the conversation starts: 64 agents per assistant, 64 skills per
+            # card, 128 derived tools per assistant, and a 6 second budget for all card
+            # fetches combined. An agent whose card cannot be fetched costs the assistant that
+            # capability for the conversation; it does not fail the call. Omit this field to
+            # leave the assistant's agents unchanged; send an empty array to remove them all.
+            a2a_agents: nil,
             # Conversation flow as supplied by API clients (create / update).
             #
             # A directed graph of `FlowNodeReq` connected by `FlowEdge`s. Validation enforces
@@ -504,6 +534,7 @@ module Telnyx
           sig do
             override.returns(
               {
+                a2a_agents: T::Array[Telnyx::AI::AssistantA2AAgent],
                 conversation_flow: Telnyx::AI::ConversationFlowReq,
                 description: String,
                 dynamic_variables: T::Hash[Symbol, T.anything],

data/rbi/telnyx/models/ai/chat_completion_request.rbi

@@ -56,28 +56,6 @@ module Telnyx
         sig { params(frequency_penalty: Float).void }
         attr_writer :frequency_penalty
 
-        # If specified, the output will be exactly one of the choices.
-        sig { returns(T.nilable(T::Array[String])) }
-        attr_reader :guided_choice
-
-        sig { params(guided_choice: T::Array[String]).void }
-        attr_writer :guided_choice
-
-        # Must be a valid JSON schema. If specified, the output will follow the JSON
-        # schema.
-        sig { returns(T.nilable(T::Hash[Symbol, T.anything])) }
-        attr_reader :guided_json
-
-        sig { params(guided_json: T::Hash[Symbol, T.anything]).void }
-        attr_writer :guided_json
-
-        # If specified, the output will follow the regex pattern.
-        sig { returns(T.nilable(String)) }
-        attr_reader :guided_regex
-
-        sig { params(guided_regex: String).void }
-        attr_writer :guided_regex
-
         # This is used with `use_beam_search` to prefer shorter or longer completions.
         sig { returns(T.nilable(Float)) }
         attr_reader :length_penalty
@@ -187,17 +165,31 @@ module Telnyx
         end
         attr_writer :region
 
-        # Use this is you want to guarantee a JSON output without defining a schema. For
-        # control over the schema, use `guided_json`.
+        # Controls the format of the model output. `json_object` guarantees valid JSON
+        # output without defining a schema; `json_schema` constrains the output to the
+        # JSON schema you supply via the `json_schema` property and is the supported way
+        # to get guaranteed structured output on Telnyx-hosted models.
         sig do
-          returns(T.nilable(Telnyx::AI::ChatCompletionRequest::ResponseFormat))
+          returns(
+            T.nilable(
+              T.any(
+                Telnyx::AI::ChatCompletionRequest::ResponseFormat::ResponseFormatText,
+                Telnyx::AI::ChatCompletionRequest::ResponseFormat::ResponseFormatJsonObject,
+                Telnyx::AI::ChatCompletionRequest::ResponseFormat::ResponseFormatJsonSchemaParam
+              )
+            )
+          )
         end
         attr_reader :response_format
 
         sig do
           params(
             response_format:
-              Telnyx::AI::ChatCompletionRequest::ResponseFormat::OrHash
+              T.any(
+                Telnyx::AI::ChatCompletionRequest::ResponseFormat::ResponseFormatText::OrHash,
+                Telnyx::AI::ChatCompletionRequest::ResponseFormat::ResponseFormatJsonObject::OrHash,
+                Telnyx::AI::ChatCompletionRequest::ResponseFormat::ResponseFormatJsonSchemaParam::OrHash
+              )
           ).void
         end
         attr_writer :response_format
@@ -329,9 +321,6 @@ module Telnyx
             early_stopping: T::Boolean,
             enable_thinking: T::Boolean,
             frequency_penalty: Float,
-            guided_choice: T::Array[String],
-            guided_json: T::Hash[Symbol, T.anything],
-            guided_regex: String,
             length_penalty: Float,
             logprobs: T::Boolean,
             max_tokens: Integer,
@@ -344,7 +333,11 @@ module Telnyx
               Telnyx::AI::ChatCompletionRequest::ReasoningEffort::OrSymbol,
             region: Telnyx::AI::ChatCompletionRequest::Region::OrSymbol,
             response_format:
-              Telnyx::AI::ChatCompletionRequest::ResponseFormat::OrHash,
+              T.any(
+                Telnyx::AI::ChatCompletionRequest::ResponseFormat::ResponseFormatText::OrHash,
+                Telnyx::AI::ChatCompletionRequest::ResponseFormat::ResponseFormatJsonObject::OrHash,
+                Telnyx::AI::ChatCompletionRequest::ResponseFormat::ResponseFormatJsonSchemaParam::OrHash
+              ),
             seed: Integer,
             service_tier: String,
             stop: Telnyx::AI::ChatCompletionRequest::Stop::Variants,
@@ -385,13 +378,6 @@ module Telnyx
           enable_thinking: nil,
           # Higher values will penalize the model from repeating the same output tokens.
           frequency_penalty: nil,
-          # If specified, the output will be exactly one of the choices.
-          guided_choice: nil,
-          # Must be a valid JSON schema. If specified, the output will follow the JSON
-          # schema.
-          guided_json: nil,
-          # If specified, the output will follow the regex pattern.
-          guided_regex: nil,
           # This is used with `use_beam_search` to prefer shorter or longer completions.
           length_penalty: nil,
           # Whether to return log probabilities of the output tokens or not. If true,
@@ -428,8 +414,10 @@ module Telnyx
           # provider never passes through Telnyx model routing, so a region cannot be
           # enforced for it. Omit for today's latency-based routing.
           region: nil,
-          # Use this is you want to guarantee a JSON output without defining a schema. For
-          # control over the schema, use `guided_json`.
+          # Controls the format of the model output. `json_object` guarantees valid JSON
+          # output without defining a schema; `json_schema` constrains the output to the
+          # JSON schema you supply via the `json_schema` property and is the supported way
+          # to get guaranteed structured output on Telnyx-hosted models.
           response_format: nil,
           # If specified, the system will make a best effort to sample deterministically,
           # such that repeated requests with the same `seed` and parameters should return
@@ -478,9 +466,6 @@ module Telnyx
               early_stopping: T::Boolean,
               enable_thinking: T::Boolean,
               frequency_penalty: Float,
-              guided_choice: T::Array[String],
-              guided_json: T::Hash[Symbol, T.anything],
-              guided_regex: String,
               length_penalty: Float,
               logprobs: T::Boolean,
               max_tokens: Integer,
@@ -493,7 +478,11 @@ module Telnyx
                 Telnyx::AI::ChatCompletionRequest::ReasoningEffort::OrSymbol,
               region: Telnyx::AI::ChatCompletionRequest::Region::OrSymbol,
               response_format:
-                Telnyx::AI::ChatCompletionRequest::ResponseFormat,
+                T.any(
+                  Telnyx::AI::ChatCompletionRequest::ResponseFormat::ResponseFormatText,
+                  Telnyx::AI::ChatCompletionRequest::ResponseFormat::ResponseFormatJsonObject,
+                  Telnyx::AI::ChatCompletionRequest::ResponseFormat::ResponseFormatJsonSchemaParam
+                ),
               seed: Integer,
               service_tier: String,
               stop: Telnyx::AI::ChatCompletionRequest::Stop::Variants,
@@ -848,76 +837,219 @@ module Telnyx
           end
         end
 
-        class ResponseFormat < Telnyx::Internal::Type::BaseModel
-          OrHash =
+        # Controls the format of the model output. `json_object` guarantees valid JSON
+        # output without defining a schema; `json_schema` constrains the output to the
+        # JSON schema you supply via the `json_schema` property and is the supported way
+        # to get guaranteed structured output on Telnyx-hosted models.
+        module ResponseFormat
+          extend Telnyx::Internal::Type::Union
+
+          Variants =
             T.type_alias do
               T.any(
-                Telnyx::AI::ChatCompletionRequest::ResponseFormat,
-                Telnyx::Internal::AnyHash
+                Telnyx::AI::ChatCompletionRequest::ResponseFormat::ResponseFormatText,
+                Telnyx::AI::ChatCompletionRequest::ResponseFormat::ResponseFormatJsonObject,
+                Telnyx::AI::ChatCompletionRequest::ResponseFormat::ResponseFormatJsonSchemaParam
               )
             end
 
-          sig do
-            returns(
-              Telnyx::AI::ChatCompletionRequest::ResponseFormat::Type::OrSymbol
-            )
-          end
-          attr_accessor :type
+          class ResponseFormatText < Telnyx::Internal::Type::BaseModel
+            OrHash =
+              T.type_alias do
+                T.any(
+                  Telnyx::AI::ChatCompletionRequest::ResponseFormat::ResponseFormatText,
+                  Telnyx::Internal::AnyHash
+                )
+              end
 
-          # Use this is you want to guarantee a JSON output without defining a schema. For
-          # control over the schema, use `guided_json`.
-          sig do
-            params(
-              type:
-                Telnyx::AI::ChatCompletionRequest::ResponseFormat::Type::OrSymbol
-            ).returns(T.attached_class)
-          end
-          def self.new(type:)
-          end
+            sig { returns(Symbol) }
+            attr_accessor :type
 
-          sig do
-            override.returns(
-              {
-                type:
-                  Telnyx::AI::ChatCompletionRequest::ResponseFormat::Type::OrSymbol
-              }
-            )
-          end
-          def to_hash
+            # Plain text output.
+            sig { params(type: Symbol).returns(T.attached_class) }
+            def self.new(type: :text)
+            end
+
+            sig { override.returns({ type: Symbol }) }
+            def to_hash
+            end
           end
 
-          module Type
-            extend Telnyx::Internal::Type::Enum
+          class ResponseFormatJsonObject < Telnyx::Internal::Type::BaseModel
+            OrHash =
+              T.type_alias do
+                T.any(
+                  Telnyx::AI::ChatCompletionRequest::ResponseFormat::ResponseFormatJsonObject,
+                  Telnyx::Internal::AnyHash
+                )
+              end
 
-            TaggedSymbol =
+            sig { returns(Symbol) }
+            attr_accessor :type
+
+            # JSON mode: the model output is valid JSON, without a schema.
+            sig { params(type: Symbol).returns(T.attached_class) }
+            def self.new(type: :json_object)
+            end
+
+            sig { override.returns({ type: Symbol }) }
+            def to_hash
+            end
+          end
+
+          class ResponseFormatJsonSchemaParam < Telnyx::Internal::Type::BaseModel
+            OrHash =
               T.type_alias do
-                T.all(
-                  Symbol,
-                  Telnyx::AI::ChatCompletionRequest::ResponseFormat::Type
+                T.any(
+                  Telnyx::AI::ChatCompletionRequest::ResponseFormat::ResponseFormatJsonSchemaParam,
+                  Telnyx::Internal::AnyHash
                 )
               end
-            OrSymbol = T.type_alias { T.any(Symbol, String) }
 
-            TEXT =
-              T.let(
-                :text,
-                Telnyx::AI::ChatCompletionRequest::ResponseFormat::Type::TaggedSymbol
-              )
-            JSON_OBJECT =
-              T.let(
-                :json_object,
-                Telnyx::AI::ChatCompletionRequest::ResponseFormat::Type::TaggedSymbol
+            # The JSON schema configuration, required when `type` is `json_schema`. Matches
+            # the
+            # [OpenAI structured outputs](https://platform.openai.com/docs/guides/structured-outputs)
+            # `json_schema` response format.
+            sig do
+              returns(
+                Telnyx::AI::ChatCompletionRequest::ResponseFormat::ResponseFormatJsonSchemaParam::JsonSchema
               )
+            end
+            attr_reader :json_schema
+
+            sig do
+              params(
+                json_schema:
+                  Telnyx::AI::ChatCompletionRequest::ResponseFormat::ResponseFormatJsonSchemaParam::JsonSchema::OrHash
+              ).void
+            end
+            attr_writer :json_schema
+
+            sig { returns(Symbol) }
+            attr_accessor :type
+
+            # Structured output: the model output is constrained to the JSON schema supplied
+            # in `json_schema`.
+            sig do
+              params(
+                json_schema:
+                  Telnyx::AI::ChatCompletionRequest::ResponseFormat::ResponseFormatJsonSchemaParam::JsonSchema::OrHash,
+                type: Symbol
+              ).returns(T.attached_class)
+            end
+            def self.new(
+              # The JSON schema configuration, required when `type` is `json_schema`. Matches
+              # the
+              # [OpenAI structured outputs](https://platform.openai.com/docs/guides/structured-outputs)
+              # `json_schema` response format.
+              json_schema:,
+              type: :json_schema
+            )
+            end
 
             sig do
               override.returns(
-                T::Array[
-                  Telnyx::AI::ChatCompletionRequest::ResponseFormat::Type::TaggedSymbol
-                ]
+                {
+                  json_schema:
+                    Telnyx::AI::ChatCompletionRequest::ResponseFormat::ResponseFormatJsonSchemaParam::JsonSchema,
+                  type: Symbol
+                }
               )
             end
-            def self.values
+            def to_hash
             end
+
+            class JsonSchema < Telnyx::Internal::Type::BaseModel
+              OrHash =
+                T.type_alias do
+                  T.any(
+                    Telnyx::AI::ChatCompletionRequest::ResponseFormat::ResponseFormatJsonSchemaParam::JsonSchema,
+                    Telnyx::Internal::AnyHash
+                  )
+                end
+
+              # The name of the response format. Used for clarity only.
+              sig { returns(String) }
+              attr_accessor :name
+
+              # A description of what the response format is for, typically used to guide the
+              # model.
+              sig { returns(T.nilable(String)) }
+              attr_reader :description
+
+              sig { params(description: String).void }
+              attr_writer :description
+
+              # The JSON schema the model output must conform to. A valid
+              # [JSON Schema](https://json-schema.org) object, e.g. a Pydantic
+              # `model_json_schema()` export.
+              sig { returns(T.nilable(T::Hash[Symbol, T.anything])) }
+              attr_reader :schema
+
+              sig { params(schema: T::Hash[Symbol, T.anything]).void }
+              attr_writer :schema
+
+              # Enables strict schema adherence when supported by the model. If the generated
+              # output does not match the provided schema, the request fails instead of
+              # returning non-conformant output.
+              sig { returns(T.nilable(T::Boolean)) }
+              attr_reader :strict
+
+              sig { params(strict: T::Boolean).void }
+              attr_writer :strict
+
+              # The JSON schema configuration, required when `type` is `json_schema`. Matches
+              # the
+              # [OpenAI structured outputs](https://platform.openai.com/docs/guides/structured-outputs)
+              # `json_schema` response format.
+              sig do
+                params(
+                  name: String,
+                  description: String,
+                  schema: T::Hash[Symbol, T.anything],
+                  strict: T::Boolean
+                ).returns(T.attached_class)
+              end
+              def self.new(
+                # The name of the response format. Used for clarity only.
+                name:,
+                # A description of what the response format is for, typically used to guide the
+                # model.
+                description: nil,
+                # The JSON schema the model output must conform to. A valid
+                # [JSON Schema](https://json-schema.org) object, e.g. a Pydantic
+                # `model_json_schema()` export.
+                schema: nil,
+                # Enables strict schema adherence when supported by the model. If the generated
+                # output does not match the provided schema, the request fails instead of
+                # returning non-conformant output.
+                strict: nil
+              )
+              end
+
+              sig do
+                override.returns(
+                  {
+                    name: String,
+                    description: String,
+                    schema: T::Hash[Symbol, T.anything],
+                    strict: T::Boolean
+                  }
+                )
+              end
+              def to_hash
+              end
+            end
+          end
+
+          sig do
+            override.returns(
+              T::Array[
+                Telnyx::AI::ChatCompletionRequest::ResponseFormat::Variants
+              ]
+            )
+          end
+          def self.variants
           end
         end
 

data/rbi/telnyx/models/ai/inference_embedding.rbi

@@ -31,6 +31,24 @@ module Telnyx
         sig { returns(String) }
         attr_accessor :name
 
+        # A2A agents this assistant can delegate to. Tools are not stored here: at the
+        # start of every conversation each agent's card is fetched and one tool is derived
+        # per skill the card advertises, named `a2a_<name>_<skill_id>`. The following
+        # limits are not enforced when the assistant is saved, and anything past them is
+        # dropped when the conversation starts: 64 agents per assistant, 64 skills per
+        # card, 128 derived tools per assistant, and a 6 second budget for all card
+        # fetches combined. An agent whose card cannot be fetched costs the assistant that
+        # capability for the conversation; it does not fail the call.
+        sig { returns(T.nilable(T::Array[Telnyx::AI::AssistantA2AAgent])) }
+        attr_reader :a2a_agents
+
+        sig do
+          params(
+            a2a_agents: T::Array[Telnyx::AI::AssistantA2AAgent::OrHash]
+          ).void
+        end
+        attr_writer :a2a_agents
+
         # Conversation flow as returned by the API.
         sig { returns(T.nilable(Telnyx::AI::ConversationFlow)) }
         attr_reader :conversation_flow
@@ -332,6 +350,7 @@ module Telnyx
             instructions: String,
             model: String,
             name: String,
+            a2a_agents: T::Array[Telnyx::AI::AssistantA2AAgent::OrHash],
             conversation_flow: Telnyx::AI::ConversationFlow::OrHash,
             description: String,
             dynamic_variables: T::Hash[Symbol, T.anything],
@@ -395,6 +414,15 @@ module Telnyx
           # provided, Telnyx applies the default model.
           model:,
           name:,
+          # A2A agents this assistant can delegate to. Tools are not stored here: at the
+          # start of every conversation each agent's card is fetched and one tool is derived
+          # per skill the card advertises, named `a2a_<name>_<skill_id>`. The following
+          # limits are not enforced when the assistant is saved, and anything past them is
+          # dropped when the conversation starts: 64 agents per assistant, 64 skills per
+          # card, 128 derived tools per assistant, and a 6 second budget for all card
+          # fetches combined. An agent whose card cannot be fetched costs the assistant that
+          # capability for the conversation; it does not fail the call.
+          a2a_agents: nil,
           # Conversation flow as returned by the API.
           conversation_flow: nil,
           description: nil,
@@ -490,6 +518,7 @@ module Telnyx
               instructions: String,
               model: String,
               name: String,
+              a2a_agents: T::Array[Telnyx::AI::AssistantA2AAgent],
               conversation_flow: Telnyx::AI::ConversationFlow,
               description: String,
               dynamic_variables: T::Hash[Symbol, T.anything],

data/rbi/telnyx/models/ai/telephony_settings.rbi

@@ -26,6 +26,19 @@ module Telnyx
         sig { params(disable_dtmf: T::Boolean).void }
         attr_writer :disable_dtmf
 
+        # Destination number or SIP URI to transfer the caller to when the AI conversation
+        # ends abnormally, for example because of an assistant-side error, so the caller
+        # is not left in dead air. This only fires for abnormal ends: it does not fire
+        # when the conversation ends on purpose (the caller hung up, the assistant
+        # completed normally, the caller hung up after a relay handoff, or voicemail was
+        # detected), and it does not fire when the assistant already transferred or
+        # bridged the call.
+        sig { returns(T.nilable(String)) }
+        attr_reader :fallback_destination
+
+        sig { params(fallback_destination: String).void }
+        attr_writer :fallback_destination
+
         # The noise suppression engine to use. Use 'disabled' to turn off noise
         # suppression.
         sig do
@@ -149,6 +162,7 @@ module Telnyx
           params(
             default_texml_app_id: String,
             disable_dtmf: T::Boolean,
+            fallback_destination: String,
             noise_suppression:
               Telnyx::AI::TelephonySettings::NoiseSuppression::OrSymbol,
             noise_suppression_config:
@@ -172,6 +186,14 @@ module Telnyx
           # configured anywhere on the assistant — on the main tool array or on any workflow
           # node — enforced at write time.
           disable_dtmf: nil,
+          # Destination number or SIP URI to transfer the caller to when the AI conversation
+          # ends abnormally, for example because of an assistant-side error, so the caller
+          # is not left in dead air. This only fires for abnormal ends: it does not fire
+          # when the conversation ends on purpose (the caller hung up, the assistant
+          # completed normally, the caller hung up after a relay handoff, or voicemail was
+          # detected), and it does not fire when the assistant already transferred or
+          # bridged the call.
+          fallback_destination: nil,
           # The noise suppression engine to use. Use 'disabled' to turn off noise
           # suppression.
           noise_suppression: nil,
@@ -222,6 +244,7 @@ module Telnyx
             {
               default_texml_app_id: String,
               disable_dtmf: T::Boolean,
+              fallback_destination: String,
               noise_suppression:
                 Telnyx::AI::TelephonySettings::NoiseSuppression::OrSymbol,
               noise_suppression_config: