> ## Documentation Index > Fetch the complete documentation index at: https://dialnexa.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Build Agent Configuration > Build Agent Configuration with the DialNexa API. Generates a draft configuration from structured answers. This operation does not save or publish an agent. Read only Build Agent Configuration uses your workspace API key. Generates a draft configuration from structured answers. This operation does not save or publish an agent. ## Before you begin Use a server-side [API key](/docs/api-reference/authentication) for the intended workspace. ## Build Agent Configuration request The request panel lists supported query parameters and body fields. For a request body, the example below supplies the required fields. Replace sample values with your own inputs. ```bash theme={null} curl --request POST 'https://api.dialnexa.com/v1/agent-builder/run' \ --header "Authorization: Bearer $DIALNEXA_API_KEY" \ --header 'Content-Type: application/json' \ --data '{ "structured_input": { "company_and_offering": { "description": "Company and offering", "value": "Acme provides appointment scheduling software." }, "target_customer": { "description": "Target customer", "value": "Small business owners who requested a demo." }, "primary_goal": { "description": "Call goal", "value": "Arrange a product demo." }, "success_criteria": { "description": "Success criteria", "value": "Confirm interest and a preferred callback time." }, "information_to_collect": { "description": "Information to collect", "value": "Name and preferred callback time." }, "objections_and_faqs": { "description": "Questions", "value": "Explain that the demo is free." }, "agent_tone": { "description": "Tone", "value": "Friendly, concise, and professional." }, "additional_context": { "description": "Context", "value": "Do not promise pricing or unavailable appointment slots." } } }' ``` ## Verify the result Expect HTTP `201`. Read the `data` property in the success envelope; the response panel documents its fields. Inspect `data.status`: `needs_input` requires answers to `missingQuestions`; `human_review` requires review of the evaluation; `failed` includes an error. `completed` provides `draftAgent`. Review its configuration, then map the fields into [Create Agent](/docs/api-reference/v1/agents/create). A build never publishes an agent automatically. This operation also accepts the matching `/v1/assistant` path. The request and result contracts are shared. Use one path consistently for your integration. ## Retry safety This operation does not modify workspace resources. Retry after a transient connection failure. ## Errors and recovery * `401`: Missing, expired, or invalid API key. ## Related endpoints * [Get Agent Builder Inventory](/docs/api-reference/v1/agent-builder/inventory) * [Stream Agent Build](/docs/api-reference/v1/agent-builder/stream) * [Generate Agent Objectives](/docs/api-reference/v1/agent-builder/generate-objectives) * [Generate Agent Tone](/docs/api-reference/v1/agent-builder/generate-tone) * [API authentication](/docs/api-reference/authentication) ## OpenAPI ````yaml POST /v1/agent-builder/run openapi: 3.0.0 info: title: DialNexa API description: Public `/v1` REST API for the DialNexa voice AI platform. version: 1.0.0 servers: - url: https://api.dialnexa.com description: DialNexa production API security: - bearer: [] tags: - name: Agents - name: Batch Calls - name: Calls - name: Knowledge Base - name: Languages - name: LLMs - name: Phone Numbers - name: Transcribers - name: Webhooks - name: Voices - name: Workflows - name: Workflow Leads - name: Authentication - name: Agent Builder paths: /v1/agent-builder/run: post: tags: - Agent Builder summary: Build Agent Configuration description: >- Generates a draft configuration from structured answers. This operation does not save or publish an agent. operationId: runAgentBuilder parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RunAgentBuilder' examples: request: value: structured_input: company_and_offering: description: Company and offering value: Acme provides appointment scheduling software. target_customer: description: Target customer value: Small business owners who requested a demo. primary_goal: description: Call goal value: Arrange a product demo. success_criteria: description: Success criteria value: Confirm interest and a preferred callback time. information_to_collect: description: Information to collect value: Name and preferred callback time. objections_and_faqs: description: Questions value: Explain that the demo is free. agent_tone: description: Tone value: Friendly, concise, and professional. additional_context: description: Context value: Do not promise pricing or unavailable appointment slots. responses: '201': description: Builder run completed or needs more input content: application/json: schema: type: object required: - success - error - statusCode - message - data - timestamp properties: success: type: boolean enum: - true error: type: boolean enum: - false statusCode: type: integer example: 201 message: type: string example: Success data: type: object properties: organizationId: type: string structuredInput: type: object properties: company_and_offering: type: object properties: description: type: string value: type: string required: - description - value target_customer: type: object properties: description: type: string value: type: string required: - description - value primary_goal: type: object properties: description: type: string value: type: string required: - description - value success_criteria: type: object properties: description: type: string value: type: string required: - description - value information_to_collect: type: object properties: description: type: string value: type: string required: - description - value objections_and_faqs: type: object properties: description: type: string value: type: string required: - description - value agent_tone: type: object properties: description: type: string value: type: string required: - description - value additional_context: type: object properties: description: type: string value: type: string required: - description - value validation_clarifications: type: object properties: description: type: string value: type: string required: - description - value required: - company_and_offering - target_customer - primary_goal - success_criteria - information_to_collect - objections_and_faqs - agent_tone - additional_context pipeline: type: string enum: - cascaded - s2s targetShape: type: string enum: - spa - cfa - ivr buildAttempt: type: number maxBuildAttempts: type: number agentBrief: type: object properties: agent_name: type: string company_name: type: string agent_role: type: string tone: type: string language_rules: type: string caller_type: type: string call_type: type: string primary_goal: type: string secondary_goals: type: array items: type: string known_variables: type: array items: type: string available_context: type: array items: type: string required_information_to_collect: type: array items: type: string call_flow_steps: type: array items: type: string guardrails: type: array items: type: string special_rules: type: array items: type: string faqs: type: array items: type: string objections: type: array items: type: string success_criteria: type: array items: type: string failure_criteria: type: array items: type: string post_call_fields_requested: type: array items: type: string known_terms: type: array items: type: string unknowns_or_missing_info: type: array items: type: string required: - agent_name - company_name - agent_role - tone - language_rules - caller_type - call_type - primary_goal - secondary_goals - known_variables - available_context - required_information_to_collect - call_flow_steps - guardrails - special_rules - faqs - objections - success_criteria - failure_criteria - post_call_fields_requested - known_terms - unknowns_or_missing_info nullable: true voicePreferences: type: object properties: language: type: string accent: type: string gender: type: string keywords: type: array items: type: string required: - language - accent - gender - keywords nullable: true missingQuestions: type: array items: type: string inventory: type: object properties: llms: type: array items: type: object properties: id: type: string name: type: string model_category: type: string required: - id - name transcribers: type: array items: type: object properties: id: type: string name: type: string provider: type: string model_id: type: string required: - id - name - provider - model_id languages: type: array items: type: object properties: id: type: string name: type: string code: type: string required: - id - name - code required: - llms - transcribers - languages nullable: true technicalProfile: type: object properties: agent_type: type: string enum: - Single_Prompt_Agent - Conversational_Flow_Agent - IVR_Agent pipeline_type: type: string enum: - Cascaded - Speech_To_Speech llm_id: type: string nullable: true llm_name: type: string nullable: true voice_id: type: string nullable: true voice_name: type: string nullable: true voice_model_id: type: string nullable: true transcriber_id: type: string nullable: true transcriber_name: type: string nullable: true language_id: type: string nullable: true language_code: type: string nullable: true boosted_keywords: type: string nullable: true fallback_stt_enabled: type: boolean stt_fallback_transcriber_id: type: string nullable: true stt_fallback_wait_ms: type: number audio_cache_enabled: type: boolean denoising_mode: type: string enum: - remove_noise - remove_noise_and_speech max_call_duration_sec: type: number system_prompt_text: type: string llm_temperature: type: number fallback_llm_enabled: type: boolean llm_fallback_model: type: string nullable: true llm_fallback_model_name: type: string nullable: true llm_fallback_delay_ms: type: number optimization_summary: type: string required: - agent_type - pipeline_type - llm_id - llm_name - voice_id - voice_name - voice_model_id - transcriber_id - transcriber_name - language_id - language_code - boosted_keywords - fallback_stt_enabled - stt_fallback_transcriber_id - stt_fallback_wait_ms - audio_cache_enabled - denoising_mode - max_call_duration_sec - system_prompt_text - llm_temperature - fallback_llm_enabled - llm_fallback_model - llm_fallback_model_name - llm_fallback_delay_ms - optimization_summary nullable: true promptSections: type: object properties: identity: type: string context_and_variables: type: string primary_goal: type: string call_flow: type: string guardrails: type: string faqs_and_objections: type: string closing_rules: type: string ai_identity_if_asked: type: string required: - identity - context_and_variables - primary_goal - call_flow - guardrails - faqs_and_objections - closing_rules - ai_identity_if_asked nullable: true promptText: type: string nullable: true welcomeMessage: type: string nullable: true postcallAnalysis: type: array items: type: object properties: field_name: type: string field_type: type: string enum: - TEXT - SELECTOR - BOOLEAN - NUMBER field_description: type: string additional_fields: type: object additionalProperties: {} required: - field_name - field_type - field_description boostedKeywords: type: string nullable: true simulations: type: array items: type: string evaluation: type: object properties: overall_pass: type: boolean prompt_score: type: number conversation_score: type: number pca_score: type: number technical_fit_score: type: number issues: type: array items: type: string prompt_fixes: type: array items: type: string pca_fixes: type: array items: type: string technical_profile_fixes: type: array items: type: string human_review_required: type: boolean summary: type: string required: - overall_pass - prompt_score - conversation_score - pca_score - technical_fit_score - issues - prompt_fixes - pca_fixes - technical_profile_fixes - human_review_required - summary nullable: true draftAgent: type: object properties: agent_type: type: string enum: - Single_Prompt_Agent - Conversational_Flow_Agent - IVR_Agent pipeline_type: type: string enum: - Cascaded - Speech_To_Speech ivr_menu: type: object additionalProperties: {} nullable: true agent_identity: type: string nullable: true agent_background: type: string nullable: true node_positions: type: string nullable: true title: type: string description: type: string prompt_text: type: string system_prompt_text: type: string welcome_message: type: string default_dynamic_variables: type: object additionalProperties: type: string postcall_analysis: type: array items: type: object properties: field_name: type: string field_type: type: string enum: - TEXT - SELECTOR - BOOLEAN - NUMBER field_description: type: string additional_fields: type: object additionalProperties: {} required: - field_name - field_type - field_description llm_id: type: string nullable: true voice_id: type: string nullable: true voice_model_id: type: string nullable: true transcriber_id: type: string nullable: true language_id: type: string nullable: true boosted_keywords: type: string nullable: true conversation_start_type: type: string llm_temperature: type: number fallback_llm_enabled: type: boolean llm_fallback_model: type: string nullable: true llm_fallback_delay_ms: type: number fallback_stt_enabled: type: boolean stt_fallback_transcriber_id: type: string nullable: true stt_fallback_wait_ms: type: number audio_cache_enabled: type: boolean denoising_mode: type: string enum: - remove_noise - remove_noise_and_speech max_call_duration_sec: type: number required: - agent_type - pipeline_type - ivr_menu - agent_identity - agent_background - node_positions - title - description - prompt_text - system_prompt_text - welcome_message - default_dynamic_variables - postcall_analysis - llm_id - voice_id - voice_model_id - transcriber_id - language_id - boosted_keywords - conversation_start_type - llm_temperature - fallback_llm_enabled - llm_fallback_model - llm_fallback_delay_ms - fallback_stt_enabled - stt_fallback_transcriber_id - stt_fallback_wait_ms - audio_cache_enabled - denoising_mode - max_call_duration_sec nullable: true events: type: array items: type: object properties: node: type: string status: type: string enum: - started - completed - failed message: type: string timestamp: type: string artifact: type: object additionalProperties: {} required: - node - status - message - timestamp status: type: string enum: - needs_input - completed - human_review - failed error: type: string nullable: true required: - organizationId - structuredInput - pipeline - targetShape - buildAttempt - maxBuildAttempts - agentBrief - voicePreferences - missingQuestions - inventory - technicalProfile - promptSections - promptText - welcomeMessage - postcallAnalysis - boostedKeywords - simulations - evaluation - draftAgent - events - status - error timestamp: type: string format: date-time '401': description: Missing, expired, or invalid API key. security: - bearer: [] components: schemas: RunAgentBuilder: type: object properties: structured_input: description: >- Structured blueprint submission - each field has a description (field guidance) and value (user answer) allOf: - $ref: '#/components/schemas/StructuredBlueprintInput' build_attempt: type: number description: >- Build attempt number (1-2). Validation runs only on attempt 1; attempt 2 skips re-validation. minimum: 1 maximum: 2 default: 1 pipeline: type: string description: >- Engine for the generated agent. "s2s" builds the realtime pipeline on the same single-prompt agent; anything else builds the cascaded pipeline. enum: - cascaded - s2s default: cascaded target_shape: type: string description: >- Kind of agent to build. "cfa" writes a conversation-flow document (a step graph), "ivr" writes a touch-tone menu; anything else builds a single-prompt agent. enum: - spa - cfa - ivr default: spa required: - structured_input StructuredBlueprintInput: type: object properties: company_and_offering: $ref: '#/components/schemas/StructuredBlueprintField' target_customer: $ref: '#/components/schemas/StructuredBlueprintField' primary_goal: $ref: '#/components/schemas/StructuredBlueprintField' success_criteria: $ref: '#/components/schemas/StructuredBlueprintField' information_to_collect: $ref: '#/components/schemas/StructuredBlueprintField' objections_and_faqs: $ref: '#/components/schemas/StructuredBlueprintField' agent_tone: $ref: '#/components/schemas/StructuredBlueprintField' additional_context: $ref: '#/components/schemas/StructuredBlueprintField' validation_clarifications: $ref: '#/components/schemas/StructuredBlueprintField' required: - company_and_offering - target_customer - primary_goal - success_criteria - information_to_collect - objections_and_faqs - agent_tone - additional_context StructuredBlueprintField: type: object properties: description: type: string description: User-facing explanation of what this field is asking for example: >- Share your company name and a short description of your product, service, or industry. value: type: string description: User-provided answer for this field example: Acme Corp - we sell B2B payroll software for mid-market HR teams. required: - description - value securitySchemes: bearer: scheme: bearer type: http ````