Enterprise-Grade AI Agentic Workflow Schema (v1.0.0)

This document presents a comprehensive, production-ready, standardized JSON Schema for orchestrating complex, multi-agent AI systems. This schema supports Directed Acyclic Graph (DAG) execution, custom agent definitions, multi-tool binding, dynamic routing, human-in-the-loop (HITL) checkpoints, custom User Interfaces (UI), and structured state management.

Following the schema definition is a production-grade, end-to-end example implementing an Automated Customer Support Triaging, Verification, and Escalation Pipeline.

1. The JSON Schema Specification

{ "$schema": "http://json-schema.org/draft-07/schema#", "title": "AIAgenticWorkflowSchema", "description": "A production-grade JSON schema for defining multi-agent AI workflows, encompassing execution graphs, state management, tool integration, and human-in-the-loop interfaces.", "type": "object", "required": [ "schema_version", "metadata", "variables", "agents", "tools", "workflow" ], "additionalProperties": false, "properties": { "schema_version": { "type": "string", "description": "Semantic versioning of the workflow schema.", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$" }, "metadata": { "type": "object", "description": "Metadata attributes for cataloging and managing the workflow.", "required": [ "id", "name", "description", "version", "author", "created_at", "updated_at" ], "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Unique UUIDv4 identifier for the workflow.", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[4][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$" }, "name": { "type": "string", "description": "Human-readable name of the workflow.", "minLength": 3, "maxLength": 100 }, "description": { "type": "string", "description": "Detailed summary explaining the workflow's purpose.", "minLength": 10, "maxLength": 1000 }, "version": { "type": "string", "description": "Version tracking identifier of this specific workflow instance.", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$" }, "author": { "type": "string", "description": "The creator or system that designed the workflow." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO 8601 UTC timestamp of creation." }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO 8601 UTC timestamp of the last update." }, "tags": { "type": "array", "description": "Arbitrary labels used for organization and filtering.", "items": { "type": "string" }, "uniqueItems": true } } }, "variables": { "type": "object", "description": "Global state definitions, environment properties, or secrets shared across the workflow execution lifecycle.", "additionalProperties": { "$ref": "#/$defs/variable_definition" } }, "agents": { "type": "object", "description": "A registry of reusable AI agents (personas, LLM backends, configurations, memories) instantiated within this workflow.", "additionalProperties": { "$ref": "#/$defs/agent_definition" } }, "tools": { "type": "object", "description": "A registry of tools and capabilities that agents or direct execution steps can invoke.", "additionalProperties": { "$ref": "#/$defs/tool_definition" } }, "workflow": { "type": "object", "description": "The actual execution structure containing the start condition, steps, and execution graph.", "required": [ "trigger", "steps", "edges" ], "additionalProperties": false, "properties": { "trigger": { "$ref": "#/$defs/trigger_definition" }, "steps": { "type": "object", "description": "A map of independent processing nodes executing tasks, using their unique step IDs as keys.", "additionalProperties": { "$ref": "#/$defs/step_definition" } }, "edges": { "type": "array", "description": "Directed links (transitions) between steps defining the execution flow, including conditional routing logic.", "items": { "$ref": "#/$defs/edge_definition" }, "uniqueItems": true } } } }, "$defs": { "variable_definition": { "type": "object", "required": [ "type", "description" ], "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "string", "number", "boolean", "object", "array" ] }, "description": { "type": "string", "maxLength": 500 }, "default": { "description": "Default value when the variable is not provided at runtime." }, "is_secret": { "type": "boolean", "description": "Indicates if the value must be masked and secured (e.g., API keys, database credentials).", "default": false } } }, "agent_definition": { "type": "object", "required": [ "name", "role", "goal", "backstory", "llm_config" ], "additionalProperties": false, "properties": { "name": { "type": "string" }, "role": { "type": "string", "description": "The specific objective or function the agent serves (e.g., Lead Quality Analyst)." }, "goal": { "type": "string", "description": "What the agent aims to accomplish within its role." }, "backstory": { "type": "string", "description": "Persona and contextual framing injected into the system prompt to guide agent behavior and tone." }, "llm_config": { "type": "object", "required": [ "provider", "model" ], "additionalProperties": false, "properties": { "provider": { "type": "string", "enum": [ "openai", "anthropic", "cohere", "huggingface", "ollama", "azure", "google", "aws_bedrock" ] }, "model": { "type": "string" }, "temperature": { "type": "number", "minimum": 0, "maximum": 2, "default": 0.7 }, "max_tokens": { "type": "integer", "minimum": 1 }, "top_p": { "type": "number", "minimum": 0, "maximum": 1 }, "frequency_penalty": { "type": "number", "minimum": -2, "maximum": 2 }, "presence_penalty": { "type": "number", "minimum": -2, "maximum": 2 }, "system_prompt_override": { "type": "string", "description": "Alternative system instructions that bypass default persona generation." }, "api_key_ref": { "type": "string", "description": "A pointer to the global secret variable holding the required API credential.", "pattern": "^variables\\.[a-zA-Z0-9_-]+$" } } }, "tools": { "type": "array", "description": "Array of tool keys matching the global registry that this agent is authorized to use.", "items": { "type": "string" } }, "memory_config": { "type": "object", "required": [ "enabled" ], "additionalProperties": false, "properties": { "enabled": { "type": "boolean" }, "type": { "type": "string", "enum": [ "short_term", "long_term", "vector_db_semantic" ] }, "window_size": { "type": "integer", "description": "Maximum previous conversation turns retained in memory context.", "minimum": 1 } } } } }, "tool_definition": { "type": "object", "required": [ "name", "description", "type", "configuration" ], "additionalProperties": false, "properties": { "name": { "type": "string" }, "description": { "type": "string", "description": "Explanation of the tool's purpose, used by LLMs to determine routing/invocation." }, "type": { "type": "string", "enum": [ "rest_api", "python_interpreter", "sql_query", "vector_search", "custom_code" ] }, "configuration": { "type": "object", "description": "Parameters unique to the execution type of this tool." }, "input_schema": { "type": "object", "description": "JSON Schema (Draft-07) detailing required arguments for invoking this tool." }, "output_schema": { "type": "object", "description": "JSON Schema (Draft-07) detailing structured payloads returned by this tool." } } }, "trigger_definition": { "type": "object", "required": [ "type", "configuration" ], "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "manual", "webhook", "schedule", "event_bridge" ] }, "configuration": { "type": "object", "description": "Configuration object for the trigger (e.g., cron schedules or webhook path limits)." }, "input_schema": { "type": "object", "description": "Data payload shape emitted by the trigger to initialize the workflow state." } } }, "step_definition": { "type": "object", "required": [ "name", "type" ], "additionalProperties": false, "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "type": { "type": "string", "enum": [ "agent_task", "llm_call", "tool_execution", "conditional", "loop", "parallel_fork", "parallel_join", "human_intervention", "state_update" ] }, "agent_ref": { "type": "string", "description": "References an agent in the registry. Mandatory if type is 'agent_task'." }, "tool_ref": { "type": "string", "description": "References a tool in the registry. Mandatory if type is 'tool_execution'." }, "inputs": { "type": "object", "description": "Key-value input parameters mapping values using static declarations, global variables, or JSONPath references from earlier steps.", "additionalProperties": { "$ref": "#/$defs/parameter_mapping" } }, "outputs": { "type": "object", "description": "Defines what structure this step produces and exports to the execution state.", "additionalProperties": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string" }, "description": { "type": "string" } } } }, "ui_config": { "type": "object", "description": "Layout configurations for human-facing screens when executing this step (especially within human_intervention).", "required": [ "component_type" ], "additionalProperties": false, "properties": { "component_type": { "type": "string", "enum": [ "chat_box", "data_form", "markdown_display", "comparative_split_screen", "table_editor", "file_viewer" ] }, "title": { "type": "string" }, "interactive": { "type": "boolean", "default": false }, "custom_props": { "type": "object", "description": "Custom configuration keys for the front-end rendering framework." } } }, "error_handling": { "type": "object", "additionalProperties": false, "properties": { "max_retries": { "type": "integer", "minimum": 0, "default": 3 }, "retry_backoff_ms": { "type": "integer", "minimum": 0, "default": 1000 }, "on_failure": { "type": "string", "enum": [ "abort_workflow", "continue_with_defaults", "route_to_fallback" ], "default": "abort_workflow" }, "fallback_step_ref": { "type": "string", "description": "Name of the fallback step if on_failure is set to 'route_to_fallback'." } } }, "timeout_ms": { "type": "integer", "description": "Hard limit on execution duration for this specific step.", "minimum": 1 } } }, "parameter_mapping": { "type": "object", "required": [ "source_type" ], "additionalProperties": false, "properties": { "source_type": { "type": "string", "enum": [ "static", "variable_ref", "step_output_ref", "composite_template" ] }, "value": { "description": "Direct, hardcoded payload when source_type is 'static'." }, "path": { "type": "string", "description": "JSONPath expression to resolve the property (e.g. '$.steps.triage_ticket.outputs.categorization' or '$.variables.api_base')." }, "template": { "type": "string", "description": "Text template string utilizing variable placeholders like: 'Hello {{$.steps.fetch_user.outputs.name}}, please review.'" } } }, "edge_definition": { "type": "object", "required": [ "id", "source_step_id", "target_step_id" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "source_step_id": { "type": "string", "description": "The executing node's unique ID." }, "target_step_id": { "type": "string", "description": "The recipient node's unique ID to process next." }, "condition": { "type": "object", "description": "Conditional expression evaluating whether this transition path must be taken.", "required": [ "left_operand", "operator", "right_operand" ], "additionalProperties": false, "properties": { "left_operand": { "type": "string", "description": "JSONPath pointing to runtime state element or dynamic evaluation value." }, "operator": { "type": "string", "enum": [ "equals", "not_equals", "greater_than", "less_than", "contains", "matches_regex", "is_empty", "is_not_empty", "always" ] }, "right_operand": { "description": "Static value or array of values used for the conditional logical assertion." } } } } } } }

2. Production Example: Automated SaaS Support Pipeline

This instance conforms to the schema above. It manages incoming technical support tickets, routes them based on sentiment and urgency, runs test cases using an isolated code execution environment, coordinates a Human-in-the-Loop review for edge cases, and posts resolutions to an external system.

{ "schema_version": "1.0.0", "metadata": { "id": "e674b9f2-fc74-4b92-9112-a16f6b5b5c77", "name": "Automated SaaS Customer Support & Technical Escalation Pipeline", "description": "An advanced agentic workflow designed to intercept high-priority technical tickets, extract code snippets, verify errors in an execution sandbox, draft responses, and prompt support staff for final verification.", "version": "1.0.4", "author": "Enterprise Systems Engineering team", "created_at": "2023-11-20T08:30:00Z", "updated_at": "2023-11-23T14:45:00Z", "tags": [ "CustomerSupport", "LLM-Agents", "Automation", "SandboxedCodeExecution", "HITL" ] }, "variables": { "openai_api_key": { "type": "string", "description": "API credential token for accessing OpenAI endpoints.", "is_secret": true }, "crm_auth_token": { "type": "string", "description": "Authorization token for posting finalized solutions back to our CRM API.", "is_secret": true }, "sandbox_url": { "type": "string", "description": "Target endpoint URL of the isolated code execution runtime environments.", "default": "https://sandbox-engine.internal.net/v1/execute" } }, "agents": { "triage_bot": { "name": "Triage Agent (T-800)", "role": "Ticket Ingestion and Categorization Specialist", "goal": "Analyze user tickets to extract key problem elements, categorizing systems, overall sentiment, and embedded code blocks.", "backstory": "You are a highly efficient, deterministic sorting and classification agent. You analyze support text, extract operational parameters, and output highly structured JSON data.", "llm_config": { "provider": "openai", "model": "gpt-4o", "temperature": 0.1, "max_tokens": 500, "api_key_ref": "variables.openai_api_key" }, "tools": [], "memory_config": { "enabled": false } }, "code_debugger_agent": { "name": "Debugger Agent (De-Bugger)", "role": "Virtual Senior Software Architect", "goal": "Examine failed execution logs, compare stack traces against technical specs, and write an ideal fix.", "backstory": "You possess 15+ years of software debugging experience. You analyze raw code snippets, find optimization vectors, and formulate structural recommendations.", "llm_config": { "provider": "anthropic", "model": "claude-3-5-sonnet", "temperature": 0.3, "max_tokens": 1500, "api_key_ref": "variables.openai_api_key" }, "tools": [ "kb_semantic_search" ], "memory_config": { "enabled": true, "type": "short_term", "window_size": 10 } }, "response_composer": { "name": "Drafting Agent (Composer)", "role": "Customer Relationship Communications Specialist", "goal": "Transform dense, dry technical solutions into helpful, friendly, and accessible customer responses.", "backstory": "You are empathetic, clear, and professional. Your goal is to deliver clear, technical instructions to customers with varying degrees of technical proficiency.", "llm_config": { "provider": "openai", "model": "gpt-4o", "temperature": 0.7, "max_tokens": 1000, "api_key_ref": "variables.openai_api_key" }, "tools": [], "memory_config": { "enabled": true, "type": "short_term", "window_size": 4 } } }, "tools": { "kb_semantic_search": { "name": "Knowledge Base Vector Search", "description": "Searches internal wikis, documentation, and historical resolution logs for relevant solutions.", "type": "vector_search", "configuration": { "vector_database": "pinecone", "index_name": "kb-embeddings", "embedding_model": "text-embedding-3-small", "top_k": 3 }, "input_schema": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string" } } }, "output_schema": { "type": "object", "required": [ "documents" ], "properties": { "documents": { "type": "array", "items": { "type": "object", "required": [ "id", "title", "text_content", "relevance_score" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "text_content": { "type": "string" }, "relevance_score": { "type": "number" } } } } } } }, "python_sandbox_executor": { "name": "Python Safe Execution Sandbox", "description": "Executes Python code blocks in an isolated, secure kernel environment to verify compilation and capture stdout/stderr runtime errors.", "type": "python_interpreter", "configuration": { "execution_endpoint": "variables.sandbox_url", "resource_limits": { "max_cpu_seconds": 5, "max_memory_mb": 128, "network_enabled": false } }, "input_schema": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" } } }, "output_schema": { "type": "object", "required": [ "exit_code", "stdout", "stderr" ], "properties": { "exit_code": { "type": "integer" }, "stdout": { "type": "string" }, "stderr": { "type": "string" } } } }, "crm_api_updater": { "name": "CRM Ticket Updater", "description": "Posts final responses, sets ticket statuses, and updates work logs within the CRM database.", "type": "rest_api", "configuration": { "url": "https://api.crm-provider.internal/v2/tickets/update", "method": "POST", "headers": { "Content-Type": "application/json", "Authorization": "variables.crm_auth_token" } }, "input_schema": { "type": "object", "required": [ "ticket_id", "status", "comment_body" ], "properties": { "ticket_id": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "pending", "solved" ] }, "comment_body": { "type": "string" } } }, "output_schema": { "type": "object", "required": [ "success", "transaction_id" ], "properties": { "success": { "type": "boolean" }, "transaction_id": { "type": "string" } } } } }, "workflow": { "trigger": { "type": "webhook", "configuration": { "path": "/webhooks/tickets", "allowed_ips": [ "10.150.22.0/24" ] }, "input_schema": { "type": "object", "required": [ "ticket_id", "customer_email", "subject", "body" ], "properties": { "ticket_id": { "type": "string" }, "customer_email": { "type": "string", "format": "email" }, "subject": { "type": "string" }, "body": { "type": "string" } } } }, "steps": { "triage_ticket": { "name": "Triage Ticket Analysis", "description": "Assess the ticket body to identify sentiment, system categories, and check for the presence of code snippets.", "type": "agent_task", "agent_ref": "triage_bot", "inputs": { "ticket_text": { "source_type": "step_output_ref", "path": "$.trigger.body" } }, "outputs": { "priority": { "type": "string", "description": "Calculated urgency ranking: 'low', 'normal', 'high', 'urgent'." }, "contains_code": { "type": "boolean", "description": "Flags whether a code snippet is embedded in the support request." }, "target_code": { "type": "string", "description": "Extracted code string (if contains_code is true)." } }, "error_handling": { "max_retries": 2, "retry_backoff_ms": 500, "on_failure": "continue_with_defaults" } }, "route_by_code_presence": { "name": "Route by Code Presence", "description": "Evaluates whether the ticket contains code that requires sandboxed execution.", "type": "conditional", "inputs": { "code_detected": { "source_type": "step_output_ref", "path": "$.steps.triage_ticket.outputs.contains_code" } }, "outputs": { "route_branch": { "type": "string", "description": "Stores the branch taken: 'execution_path' or 'standard_path'." } } }, "run_code_sandbox": { "name": "Execute Code in Sandbox", "description": "Passes the extracted user code to an isolated container to identify exact compile-time and runtime failures.", "type": "tool_execution", "tool_ref": "python_sandbox_executor", "inputs": { "code": { "source_type": "step_output_ref", "path": "$.steps.triage_ticket.outputs.target_code" } }, "outputs": { "exit_code": { "type": "integer" }, "stdout": { "type": "string" }, "stderr": { "type": "string" } }, "error_handling": { "max_retries": 1, "retry_backoff_ms": 1000, "on_failure": "route_to_fallback", "fallback_step_ref": "bypass_sandbox" } }, "bypass_sandbox": { "name": "Bypass Code Sandbox", "description": "State fallback step when sandbox services are offline or experience an execution timeout.", "type": "state_update", "inputs": { "exit_code": { "source_type": "static", "value": -1 }, "stdout": { "source_type": "static", "value": "" }, "stderr": { "source_type": "static", "value": "Execution environment unavailable." } }, "outputs": { "exit_code": { "type": "integer" }, "stdout": { "type": "string" }, "stderr": { "type": "string" } } }, "debug_code_errors": { "name": "Debug Code Failures", "description": "Analyze errors generated in the sandbox alongside knowledge base resources to resolve code issues.", "type": "agent_task", "agent_ref": "code_debugger_agent", "inputs": { "broken_code": { "source_type": "step_output_ref", "path": "$.steps.triage_ticket.outputs.target_code" }, "runtime_stdout": { "source_type": "step_output_ref", "path": "$.steps.run_code_sandbox.outputs.stdout" }, "runtime_stderr": { "source_type": "step_output_ref", "path": "$.steps.run_code_sandbox.outputs.stderr" } }, "outputs": { "code_root_cause": { "type": "string", "description": "Detailed explanation of why the customer's code failed." }, "code_correction": { "type": "string", "description": "Optimized, corrected code block resolving the crash." } } }, "draft_general_response": { "name": "Draft Support Response", "description": "Draft an empathetic response to the customer. Incorporates standard advice for non-code tickets, or code resolutions for technical tickets.", "type": "agent_task", "agent_ref": "response_composer", "inputs": { "original_issue": { "source_type": "step_output_ref", "path": "$.trigger.body" }, "code_root_cause": { "source_type": "step_output_ref", "path": "$.steps.debug_code_errors.outputs.code_root_cause" }, "code_correction": { "source_type": "step_output_ref", "path": "$.steps.debug_code_errors.outputs.code_correction" } }, "outputs": { "draft_email_body": { "type": "string", "description": "Fully composed email response draft containing help instructions." } } }, "human_review_checkpoint": { "name": "Expert Support Review", "description": "Interrupts the automated pipeline, requesting a support representative to review the drafted response.", "type": "human_intervention", "inputs": { "proposed_reply": { "source_type": "step_output_ref", "path": "$.steps.draft_general_response.outputs.draft_email_body" } }, "outputs": { "approved": { "type": "boolean", "description": "Whether the agent-generated response is approved for delivery." }, "revisions": { "type": "string", "description": "Edits made by the human reviewer before sending." } }, "ui_config": { "component_type": "comparative_split_screen", "title": "Review Support Email Draft", "interactive": true, "custom_props": { "left_side_panel": { "title": "Original Problem Ticket", "data_source_path": "$.trigger.body" }, "right_side_panel": { "title": "Generated Resolution Draft", "data_source_path": "$.steps.draft_general_response.outputs.draft_email_body" }, "approval_control": { "field_name": "approved", "label": "Authorize immediate dispatch of this resolution?" }, "manual_overwrite_field": { "field_name": "revisions", "label": "Manual Edits & Tweaks" } } }, "timeout_ms": 86400000 }, "update_external_crm": { "name": "Write Resolution to CRM", "description": "Post the approved message to the ticket thread and update its status.", "type": "tool_execution", "tool_ref": "crm_api_updater", "inputs": { "ticket_id": { "source_type": "step_output_ref", "path": "$.trigger.ticket_id" }, "status": { "source_type": "static", "value": "solved" }, "comment_body": { "source_type": "step_output_ref", "path": "$.steps.human_review_checkpoint.outputs.revisions" } }, "outputs": { "success": { "type": "boolean" }, "transaction_id": { "type": "string" } }, "error_handling": { "max_retries": 5, "retry_backoff_ms": 3000, "on_failure": "abort_workflow" } } }, "edges": [ { "id": "e_trigger_to_triage", "source_step_id": "trigger", "target_step_id": "triage_ticket" }, { "id": "e_triage_to_router", "source_step_id": "triage_ticket", "target_step_id": "route_by_code_presence" }, { "id": "e_router_to_sandbox", "source_step_id": "route_by_code_presence", "target_step_id": "run_code_sandbox", "condition": { "left_operand": "$.steps.triage_ticket.outputs.contains_code", "operator": "equals", "right_operand": true } }, { "id": "e_router_to_draft", "source_step_id": "route_by_code_presence", "target_step_id": "draft_general_response", "condition": { "left_operand": "$.steps.triage_ticket.outputs.contains_code", "operator": "equals", "right_operand": false } }, { "id": "e_sandbox_to_debugger", "source_step_id": "run_code_sandbox", "target_step_id": "debug_code_errors" }, { "id": "e_debugger_to_draft", "source_step_id": "debug_code_errors", "target_step_id": "draft_general_response" }, { "id": "e_bypass_to_debugger", "source_step_id": "bypass_sandbox", "target_step_id": "debug_code_errors" }, { "id": "e_draft_to_human", "source_step_id": "draft_general_response", "target_step_id": "human_review_checkpoint" }, { "id": "e_human_to_crm", "source_step_id": "human_review_checkpoint", "target_step_id": "update_external_crm" } ] } }