> ## Documentation Index > Fetch the complete documentation index at: https://docs.beam.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create a complete agent graph > Creates a new agent with its complete graph structure including nodes, edges, and tool configurations. Both an active/published graph and a draft graph are created. ## OpenAPI ````yaml post /agent-graphs/complete openapi: 3.0.0 info: title: Public API description: Public endpoints to interact with agents and orchestrate tasks version: '1.0' contact: {} servers: - url: https://api.beamstudio.ai security: [] tags: [] paths: /agent-graphs/complete: post: tags: - Complete Agent Graph summary: Create a complete agent graph description: >- Creates a new agent with its complete graph structure including nodes, edges, and tool configurations. Both an active/published graph and a draft graph are created. operationId: CompleteAgentGraphController_createAgentGraph parameters: - name: current-workspace-id in: header required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AgentGraphCompleteDto' responses: '201': description: Agent and graph created successfully content: application/json: schema: $ref: '#/components/schemas/CreateAgentGraphResponseDto' '400': description: Bad Request - Invalid input data '404': description: Tool not found and no originalTool data provided '409': description: Conflict - Invalid tool type provided security: - x-api-key: [] components: schemas: AgentGraphCompleteDto: type: object properties: agentName: type: string description: >- The name of the agent to be created. This will be displayed in the UI and used to identify the agent example: Bitcoin Price Agent agentDescription: type: string description: A detailed description of what the agent does and its capabilities example: >- An AI agent that fetches real-time cryptocurrency prices and provides market insights settings: description: >- Configuration settings for the agent including personality, restrictions, and suggested prompts allOf: - $ref: '#/components/schemas/AgentSettingsDto' nodes: description: >- The complete list of nodes that make up the agent workflow graph. Nodes are connected by edges to form the execution flow. Must include at least one entry node (isEntryNode: true). Each node can have a tool configuration and is connected to other nodes via edges type: array items: $ref: '#/components/schemas/CompleteAgentGraphNodeDto' required: - agentName - nodes CreateAgentGraphResponseDto: type: object properties: agentId: type: string description: UUID of the created agent example: f47ac10b-58cc-4372-a567-0e02b2c3d479 format: uuid agentName: type: string description: Name of the created agent example: My AI Agent activeGraphId: type: string description: UUID of the active/published graph example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 format: uuid draftGraphId: type: string description: UUID of the draft graph example: b2c3d4e5-f6a7-8901-bcde-f12345678901 format: uuid required: - agentId - agentName - activeGraphId - draftGraphId AgentSettingsDto: type: object properties: prompts: description: >- List of suggested prompts shown to users as conversation starters. These help users understand what the agent can do example: - What is the current Bitcoin price? - Can you fetch the latest cryptocurrency rates? type: array items: type: string CompleteAgentGraphNodeDto: type: object properties: id: type: string description: >- Unique identifier (UUID). This ID is used to reference the node in edge connections (sourceAgentGraphNodeId/targetAgentGraphNodeId) example: d2cbeb35-9110-426c-967a-c0dba38289a9 objective: type: string description: >- The goal or purpose of this node - what the AI should accomplish when it reaches this step. This is the main instruction for the node example: >- Fetch the current Bitcoin price and return it to the user in a friendly format evaluationCriteria: description: >- List of criteria used to evaluate if the node executed successfully. Each criterion is checked after node execution example: - The response contains a valid price number - The price is greater than 0 type: array items: type: string isEntryNode: type: boolean description: >- When true, this is the starting node of the graph. The agent begins execution here. Each graph must have exactly one entry node example: true isExitNode: type: boolean description: >- When true, reaching this node ends the graph execution. A graph can have multiple exit nodes for different outcomes example: false nodeType: enum: - executionNode - conditionNode - waitingNode - entryNode - exitNode - loopingNode type: string description: The type of node (executionNode, conditionNode, entryNode, exitNode) example: executionNode nodeConfigurations: description: Configuration options for condition nodes (conditionType, llmModel) allOf: - $ref: '#/components/schemas/NodeConfigurationsDto' xCoordinate: type: number description: >- Horizontal position (in pixels) of the node in the visual graph editor UI example: 116 yCoordinate: type: number description: >- Vertical position (in pixels) of the node in the visual graph editor UI example: 150 isEvaluationEnabled: type: boolean description: >- When true, the node output is evaluated against the evaluationCriteria after each execution example: false isAttachmentDataPulledIn: type: boolean description: >- When true, any file attachments in the conversation are made available to this node during execution example: true onError: type: string description: >- Defines what happens when the node encounters an error. Options: "STOP" (halt execution), "CONTINUE" (proceed to next node) example: STOP autoRetryWhenAccuracyLessThan: type: number description: >- When enableAutoRetryWhenAccuracyIsLow is true, the node will retry if the accuracy score falls below this threshold (0-100) example: 80 autoRetryLimitWhenAccuracyIsLow: type: number description: >- Maximum number of retry attempts when the accuracy is below the threshold example: 1 autoRetryCountWhenFailure: type: number description: >- Maximum number of retry attempts when the node execution fails with an error example: 1 autoRetryWaitTimeWhenFailureInMs: type: number description: >- Time to wait (in milliseconds) between retry attempts after a failure example: 1000 enableAutoRetryWhenAccuracyIsLow: type: boolean description: >- When true, automatically retry the node if the accuracy score is below autoRetryWhenAccuracyLessThan example: false enableAutoRetryWhenFailure: type: boolean description: >- When true, automatically retry the node if execution fails with an error example: false toolConfiguration: description: >- The tool configuration for this node. If the node needs to execute a specific tool (like calling an API), configure it here. Nodes without tools are handled by the AI directly allOf: - $ref: '#/components/schemas/CompleteAgentGraphNodeToolConfigurationDto' parentNodeId: type: string nullable: true description: >- The customId of the parent loop node when this node is a child inside a loop. Used to associate loop body nodes with their parent loop. example: d2cbeb35-9110-426c-967a-c0dba38289a9 childEdges: description: >- List of edges that go OUT from this node to other nodes. Each edge defines a possible path the agent can take after completing this node type: array items: $ref: '#/components/schemas/CompleteAgentGraphEdgeDto' parentEdges: description: >- List of edges that come IN to this node from other nodes. These represent the paths that lead to this node from previous steps type: array items: $ref: '#/components/schemas/CompleteAgentGraphEdgeDto' required: - id - objective - evaluationCriteria - isEntryNode - isExitNode - xCoordinate - yCoordinate - isEvaluationEnabled - isAttachmentDataPulledIn - onError - autoRetryWhenAccuracyLessThan - autoRetryLimitWhenAccuracyIsLow - autoRetryCountWhenFailure - autoRetryWaitTimeWhenFailureInMs - enableAutoRetryWhenAccuracyIsLow - enableAutoRetryWhenFailure - childEdges - parentEdges NodeConfigurationsDto: type: object properties: conditionType: enum: - llm_based - rule_based type: string description: Type of condition evaluation (llm_based or rule_based) example: llm_based llmModel: type: string description: The LLM model to use for condition evaluation example: GPT40 fallbackModels: type: string pattern: /^[^\s]*$/ description: Comma-separated fallback models for condition evaluation example: GPT40,GPT4OMINI waitType: enum: - time_based - condition_based type: string description: Type of wait (time_based or condition_based) example: time_based timeToWaitValue: type: number description: The duration value to wait example: 5 timeToWaitUnit: enum: - minutes - hours - days - months type: string description: The unit of time for the wait duration example: minutes linkedAgentGraphNodeId: type: string description: >- Custom id of the node linked to this node (e.g., source node for a variable-based loop, or the node a waiting node is linked to). The server resolves it to the persisted node id. rule: type: string description: Rule expression for condition-based waiting conditions: description: Condition groups for condition-based waiting type: array items: $ref: '#/components/schemas/AgentTriggerConfigurationFiltersGroup' timeoutType: enum: - no_timeout - set_timeout type: string description: Timeout type for the waiting node example: no_timeout timeoutValue: type: number description: Timeout duration value timeoutUnit: enum: - minutes - hours - days - months type: string description: The unit of time for the timeout duration onTimeout: enum: - continue - fail type: string description: Action to take when timeout is reached (continue or fail) example: continue iterationCount: type: number description: Number of iterations for a count-based loop (looping node only). linkedVariableId: type: string nullable: true description: >- Output parameter to loop over for a variable-based loop (looping node only). Supply as ":"; the server resolves it to the output param id. example: d2cbeb35-9110-426c-967a-c0dba38289a9:items alias: type: string description: Alias for nodes inside a looping node. CompleteAgentGraphNodeToolConfigurationDto: type: object properties: toolFunctionName: type: string description: The unique function name used to invoke this tool example: GPTAction_Custom_BitcoinPriceFetcher_xjUR toolName: type: string description: The display name of the tool shown in the UI example: Bitcoin Price Fetcher iconSrc: type: string nullable: true description: URL to the tool icon image example: null description: type: string description: Brief explanation of what this tool does example: >- Fetches the current Bitcoin price from CoinGecko API and returns the USD value requiresConsent: type: boolean description: >- When true, the agent will ask for user confirmation before executing this tool example: false isMemoryTool: type: boolean description: >- When true, this tool can access and search the agent memory/knowledge base example: false memoryLookupInstruction: type: string description: Instructions for how to search the memory when isMemoryTool is true example: '' isBackgroundTool: type: boolean description: >- When true, the tool runs in the background without blocking the conversation flow example: false isBatchExecutionEnabled: type: boolean description: >- When true, the tool can process multiple items in a single execution (batch mode) example: false accuracyScore: type: number nullable: true description: >- A score (0-100) indicating the historical accuracy/success rate of this tool. Null if not yet measured example: null preferredModel: type: string nullable: true description: >- The preferred AI model to use when executing this tool. If not specified, the system default model will be used. Common values: "gpt-4", "gpt-4o", "gpt-3.5-turbo" example: gpt-4o fallbackModels: type: string nullable: true pattern: /^[^\s]*$/ description: Comma-separated list of fallback models. No spaces allowed. example: DEEP_SEEK,BEDROCK_CLAUDE_3_7_SONNET,BEDROCK_CLAUDE_OPUS_4_5 prompt: type: string nullable: true description: >- The prompt template that guides the AI when executing this tool. This defines how the AI should process inputs and generate outputs. Required for custom GPT tools example: >- You are a helpful assistant. Given the input parameters, fetch the current Bitcoin price and return it in a user-friendly format. inputParams: description: >- List of input parameters that define what data this tool needs to execute. These can be filled by AI, static values, user input, or linked from previous node outputs type: array items: $ref: '#/components/schemas/AgentGraphNodeToolConfigurationInputParamDto' outputParams: description: >- List of output parameters that this tool produces after execution. These outputs can be linked to input parameters of subsequent nodes in the graph type: array items: $ref: '#/components/schemas/AgentGraphNodeToolConfigurationOutputParamDto' required: - toolFunctionName - toolName - description - requiresConsent - isMemoryTool - memoryLookupInstruction - isBackgroundTool - isBatchExecutionEnabled - inputParams - outputParams CompleteAgentGraphEdgeDto: type: object properties: sourceAgentGraphNodeId: type: string description: >- The UUID source node where this edge originates from (the "from" node) example: d2cbeb35-9110-426c-967a-c0dba38289a9 targetAgentGraphNodeId: type: string description: The UUID of the target node where this edge leads to (the "to" node) example: 22b6aa40-7d7c-449f-b151-0229834b48ba condition: type: string description: >- A condition expression that must evaluate to true for the agent to follow this edge. Empty string means unconditional transition example: price > 50000 isAttachmentDataPulledIn: type: boolean description: >- When true, any file attachments from the conversation are passed along this edge to the next node example: true conditionGroups: description: Condition groups for rule-based condition evaluation type: array items: $ref: '#/components/schemas/ConditionGroupDto' required: - sourceAgentGraphNodeId - targetAgentGraphNodeId - condition - isAttachmentDataPulledIn AgentTriggerConfigurationFiltersGroup: type: object properties: operator: enum: - AND - OR type: string conditions: type: array items: $ref: '#/components/schemas/AgentTriggerConfigurationFiltersConditions' required: - operator - conditions AgentGraphNodeToolConfigurationInputParamDto: type: object properties: fillType: type: string description: >- Determines how the parameter value is populated. Options: "ai_fill" (AI determines value), "static" (fixed value), "linked" (from previous node output), "user_input" (user provides value) example: ai_fill position: type: number description: >- The display order position of this parameter (0-indexed). Lower numbers appear first in the UI example: 0 question: type: string nullable: true description: >- When fillType is "user_input", this question is displayed to prompt the user for input example: What API endpoint URL should be used? linkedOutputParamNodeId: type: string nullable: true description: >- When fillType is "linked", this is the node ID that contains the output parameter to link to example: d2cbeb35-9110-426c-967a-c0dba38289a9 linkedOutputParamName: type: string nullable: true description: >- When fillType is "linked", this is the name of the output parameter from the referenced node to link to example: bitcoin_price_usd staticValue: type: string nullable: true description: >- When fillType is "static", this is the fixed value that will always be used for this parameter example: https://api.example.com/data required: type: boolean description: >- Whether this parameter must be provided for the tool to execute. Required parameters must have a value example: true dataType: type: string description: >- The expected data type for this parameter. Common types: string, number, boolean, object, array example: string outputExample: type: string nullable: true description: >- An example value showing the expected format, helpful for AI or users when providing input example: https://api.coingecko.com/api/v3/simple/price reloadProps: type: boolean description: >- When true, changing this parameter value triggers a reload of dependent parameters or options example: false remoteOptions: type: boolean description: >- When true, the available options for this parameter are fetched from an external API rather than being static example: false options: nullable: true description: >- For dropdown/select parameters, the list of available options to choose from type: array items: $ref: '#/components/schemas/ParamOptionDto' paramName: type: string description: >- The technical name/key of this parameter, used in API calls and data mapping example: api_url paramDescription: type: string description: >- Human-readable description explaining what this parameter is for and what value is expected example: The URL of the API endpoint to call paramTip: type: string nullable: true description: >- Additional helpful tip or hint displayed in the UI to guide users when filling this parameter example: Make sure to include the full URL with protocol (https://) linkedOutputParamRules: description: Array of linked output param rules for conditional input resolution type: array items: $ref: '#/components/schemas/LinkedOutputParamRuleDto' linkedParamRulePrompt: type: string description: Prompt for the linked param rule (used with LLM-based conditions) linkedParamConfigurations: description: Configuration for linked param condition (conditionType, llmModel) allOf: - $ref: '#/components/schemas/ParamRuleConditionConfig' required: - fillType - position - required - dataType - reloadProps - remoteOptions - paramName - paramDescription AgentGraphNodeToolConfigurationOutputParamDto: type: object properties: isArray: type: boolean description: >- Whether this output parameter returns an array of values rather than a single value example: false paramName: type: string description: >- The technical name/key of this output parameter, used when accessing the value in subsequent nodes example: bitcoin_price_usd position: type: number description: >- The display order position of this parameter (0-indexed). Lower numbers appear first in the UI example: 0 paramDescription: type: string description: >- Human-readable description explaining what this output contains and how it can be used example: The current price of Bitcoin in USD, extracted from the API response parentId: type: string nullable: true description: >- For nested/hierarchical outputs, the UUID of the parent parameter. Null for top-level parameters example: null paramPath: type: string nullable: true description: >- JSON path showing where this value is located in a nested response structure example: data.bitcoin.usd outputExample: type: string description: Example value demonstrating the expected output format example: '94523.50' dataType: type: string description: >- The data type of this output. Common types: string, number, boolean, object, array example: number typeOptions: type: object nullable: true description: >- Additional type configuration (e.g., enum values, format specifications, nested structure definitions) example: format: currency precision: 2 required: - isArray - paramName - position - paramDescription - dataType ConditionGroupDto: type: object properties: rules: description: Rules within this condition group type: array items: $ref: '#/components/schemas/ConditionRuleDto' nextGroupOperator: enum: - AND - OR type: string description: Logical operator to connect to the next group (AND/OR) required: - rules AgentTriggerConfigurationFiltersConditions: type: object properties: condition: enum: - is - is_not - contain - does_not_contain - any - all - less_than - GREATER_than - count - exist - does_not_exist type: string operator: enum: - AND - OR type: string property: type: string value: type: string required: - condition - operator - property - value ParamOptionDto: type: object properties: label: type: string description: >- Display label shown to users when selecting this option in a dropdown or selection UI example: United States value: type: string description: >- The actual value submitted when this option is selected, typically used in API calls or data processing example: US required: - label - value LinkedOutputParamRuleDto: type: object properties: elementKey: type: string description: Element key for the rule. operator: enum: - equals - not_equals - greater_than - less_than - contains - does_not_contain - starts_with - ends_with - is_empty - is_not_empty type: string description: Comparison operator for the rule. comparisonValueType: enum: - static - output_param type: string description: Type of the comparison value. comparisonValue: type: string nullable: true description: Value to compare against. nextRuleOperator: enum: - AND - OR type: string description: Logical operator linking to the next rule. required: - elementKey - operator - comparisonValueType ParamRuleConditionConfig: type: object properties: conditionType: type: string enum: - llm_based - rule_based ConditionRuleDto: type: object properties: sourceNodeId: type: string description: The node ID containing the source output parameter example: d2cbeb35-9110-426c-967a-c0dba38289a9 sourceOutputParamName: type: string description: The name of the source output parameter to compare example: status operator: enum: - equals - not_equals - greater_than - less_than - contains - does_not_contain - starts_with - ends_with - is_empty - is_not_empty type: string description: The comparison operator example: equals comparisonValueType: enum: - static - output_param type: string description: Type of comparison value (static or output_param) example: static comparisonValue: type: string description: Static value to compare against (when comparisonValueType is static) example: success comparisonNodeId: type: string description: >- Node ID containing the output param to compare against (when comparisonValueType is output_param) example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 comparisonOutputParamName: type: string description: >- Output param name to compare against (when comparisonValueType is output_param) example: expectedStatus nextRuleOperator: enum: - AND - OR type: string description: Logical operator to connect to the next rule (AND/OR) required: - sourceNodeId - sourceOutputParamName - operator - comparisonValueType securitySchemes: x-api-key: type: apiKey in: header name: x-api-key ````