Interaction Protocol and Configuration Design Guide for AI Agent Executors

I. Why AI Agent Executors Need Specialized Interaction Design

Traditional conversational systems typically follow a linear flow: “user input — model generation — user continues input.” AI agent executors operate differently. They not only generate natural language but also plan steps, invoke capabilities, read context, handle exceptions, and actively pause to wait for user decisions at specific nodes.

For example, when performing data processing, file modifications, task publishing, or permission-sensitive operations, an agent should not proceed solely based on model judgment. Instead, it must send a clear confirmation request to the user. At this point, the system control flow switches from “continuous server-side execution” to “execution pause — wait for input — resume task.”

Therefore, an agent executor ready for real-world deployment must address at least the following challenges:

1. How to load and validate agent configurations;
2. How to define the message protocol between the model, executor, and frontend;
3. How to express user queries as structured interactions like single-choice, multiple-choice, or confirmation;
4. How to maintain state consistency when a user is unresponsive, responds repeatedly, or submits invalid responses;
5. How to set authorization boundaries and audit trails for high-risk actions;
6. How to support task interruption, resumption, retry, and timeout reclamation.

These issues collectively form the infrastructure of an AI agent executor, extending far beyond simple prompt engineering.

---

II. Overall Architecture and Responsibility Division

A universal AI agent execution system can be divided into five layers.

1. Configuration Layer

The configuration layer defines the agent’s basic identity, task boundaries, available capabilities, runtime policies, and security rules. Its goal is to unify scattered environment variables, file configurations, database records, and admin panel settings into a cohesive executable object.

Common configuration items include:

• Agent name and description;
• System instructions and role constraints;
• List of invocable capabilities;
• Input/output format constraints;
• Session state persistence strategy;
• Maximum execution rounds;
• Timeout thresholds;
• Whether user interruptions are allowed;
• Whether sensitive operations require confirmation;
• Logging and audit levels.

The configuration layer should do more than just “read a dictionary.” It must also handle default value population, field validation, version compatibility, and security restriction injection.

2. Orchestration Layer

The orchestration layer determines how the task progresses to the next step. For example:

• Requesting the model to generate a plan based on the current context;
• Selecting a capability to invoke based on the plan;
• Determining whether user confirmation is required;
• Processing the results of capability invocations;
• Translating exceptions into understandable recovery strategies;
• Outputting the final result when completion conditions are met.

The orchestration layer should avoid tight coupling with specific transport protocols. It only cares about abstract actions like “ask a question,” “receive an answer,” “pause execution,” and “resume execution.”

3. Interaction Protocol Layer

The interaction protocol layer standardizes the data exchange format between the server and the frontend. Its core function is to allow the frontend to identify whether a message is text output, execution progress, a tool result, a user query, an exception notification, or a task completion signal.

The protocol layer should feature:

• Clear message types;
• Stable field semantics;
• Support for version evolution;
• Task and session association;
• Resilience to disconnections;
• Prevention of duplicate submissions and out-of-order processing.

4. State Management Layer

Agent tasks frequently span multiple request cycles. Especially when waiting for user responses, the executor must persist intermediate states to prevent task loss due to service restarts, network fluctuations, or delayed user replies.

It is recommended to split the state into:

• Session state: User context, message history, preference info;
• Task state: Current step, execution rounds, run results;
• Interaction state: Pending questions, selected answers, expiration times;
• Capability state: Invocation records, input parameters, output summaries;
• Audit state: Authorization info, operation timestamps, accountable entities.

5. Presentation and Control Layer

The frontend should not guess the meaning of the model’s text. Instead, it should render different components based on the structured protocol. For example:

• Plain text uses message bubbles;
• Single-choice questions use radio buttons;
• Multiple-choice questions use checkboxes;
• High-risk operations use a secondary confirmation dialog;
• Execution steps use a progress panel;
• Exception info uses a retryable prompt;
• Task completion displays a result summary and execution log.

This reduces the cost of parsing complex text on the frontend and improves interaction consistency.

---

III. Configuration Assembly: From Raw Input to Executable Config

1. Goals of the Configuration Assembler

The configuration assembler integrates information from multiple sources into a unified execution configuration. Typical sources include:

• Agent definitions maintained in the admin console;
• Environment-level default configurations;
• User-level preference settings;
• Temporary parameters carried in the current request;
• Limitations injected by the security policy module;
• System built-in fallback configurations.

Configuration priority must be clearly defined. A common rule is: “System defaults < Environment config < Agent config < Session config < Current request parameters < Security policy restrictions.” Security policies have the highest binding force and cannot be bypassed by the caller.

2. Recommended Data Structure

Below is a neutralized schematic structure:

AgentConfig {
  identity: {
    name: string,
    description: string,
    instruction: string
  },
  runtime: {
    max_steps: integer,
    timeout_seconds: integer,
    allow_interrupt: boolean,
    resume_enabled: boolean
  },
  interaction: {
    confirmation_required: boolean,
    question_timeout_seconds: integer,
    max_options_per_question: integer
  },
  capabilities: [
    {
      name: string,
      description: string,
      input_schema: object,
      permission_level: string
    }
  ],
  observability: {
    log_level: string,
    audit_enabled: boolean,
    trace_enabled: boolean
  }
}

The key here is not the number of fields, but that each field must have a deterministic semantic meaning. For example, max_steps should limit the maximum number of consecutive execution rounds to prevent infinite loops caused by planning errors; question_timeout_seconds should control the lifespan of a pending user response state to prevent invalid tasks from consuming resources indefinitely.

3. Configuration Validation Principles

Once assembled, the configuration should be validated before task launch:

• Name, description, and system instructions cannot be empty;
• Maximum execution steps must be a positive integer;
• Timeout values must fall within a reasonable range;
• Capability names must be unique;
• Each capability must declare an input format;
• High-privilege capabilities must have confirmation rules configured;
• The number of question options must be limited;
• User-visible text must not contain sensitive info like internal keys, file paths, or stack traces.

Configuration errors should be exposed during the startup phase, not during task execution.

---

IV. Two-Way Interaction Message Protocol Design

1. Why Pure Text Transmission is Insufficient

If the server only outputs natural language, the frontend struggles to reliably determine if a sentence is:

• A general explanation;
• A request for confirmation;
• A waiting state for user selection;
• An in-progress prompt;
• An error message;
• The final answer.

Relying on text keyword parsing introduces ambiguity and fails to meet the needs of multi-language support, version upgrades, and complex interactions. Therefore, a structured protocol using a “Message Envelope + Business Payload” is recommended.

2. Generic Message Envelope

Each message can contain the following common fields:

MessageEnvelope {
  protocol_version: string,
  message_id: string,
  session_id: string,
  task_id: string,
  sequence: integer,
  type: string,
  timestamp: string,
  payload: object
}

Field descriptions:

• protocol_version: Supports protocol evolution;
• message_id: Used for deduplication and tracing;
• session_id: Identifies the user session;
• task_id: Identifies an independent execution task;
• sequence: Ensures ordered processing within the same task;
• type: Identifies the message category;
• timestamp: Facilitates logging and auditing;
• payload: Specific content for different message types.

3. Recommended Message Types

Message types can be categorized as follows:

Type	Purpose
task_started	Task has been created and execution has started
progress	Execution progress or phase description
text_delta	Streaming text fragments
capability_started	A specific capability has started executing
capability_result	A specific capability has returned a result
question	Requesting the user to answer a question
authorization_request	Requesting user authorization for a high-risk operation
task_paused	Task paused due to waiting for input
task_resumed	Execution resumed after receiving input
warning	Non-fatal warning
error	Execution exception
task_completed	Task finished normally
task_cancelled	Task cancelled or closed due to timeout

By explicitly defining types, the frontend can directly match the corresponding rendering and interaction logic.

---

V. Structured Modeling for Single-Choice, Multiple-Choice, and Confirmation Questions

1. Unified Question Object

Whether dealing with single-choice, multiple-choice, or confirmation actions, they can be abstracted into a unified question object:

QuestionPayload {
  question_id: string,
  title: string,
  description: string,
  question_type: string,
  options: [
    {
      option_id: string,
      label: string,
      description: string,
      disabled: boolean
    }
  ],
  required: boolean,
  min_selections: integer,
  max_selections: integer,
  default_values: [string],
  expires_at: string
}

Here, question_type can be:

• single_choice: Select only one option;
• multiple_choice: Select multiple options;
• confirmation: Confirm or cancel;
• free_text: Fill in supplementary text;
• structured_input: Fill in data conforming to specific field rules.

2. Single-Choice Question Design

Single-choice questions are suitable for scenarios requiring explicit branching, such as:

• Selecting an execution mode;
• Confirming the processing scope;
• Choosing an output format;
• Specifying a priority;
• Selecting one from several candidate plans.

When designing single-choice questions, note:

1. Options should be mutually exclusive, avoiding semantic overlap;
2. The number of options should not be excessive;
3. The text for each option should be expressed in business language understandable to the user;
4. Do not cram complex explanations entirely into the option name;
5. Add extra descriptions for high-risk options;
6. Provide an “Other” or “Do not execute for now” option if no suitable choice exists.

Example:

Question: Please select the execution mode for this task
Type: single_choice
Options:
- Generate execution plan only
- Generate plan and wait for confirmation
- Execute automatically within allowed limits

3. Multiple-Choice Question Design

Multiple-choice questions apply when users need to combine configurations, such as:

• Selecting data categories to process;
• Selecting output content;
• Choosing the scope of capabilities allowed for the agent;
• Selecting roles to notify;
• Selecting multiple checks to execute.

The key to multiple-choice design is defining constraints clearly. If at least one selection is required, set min_selections; if limitations due to cost, permissions, or processes prevent too many selections, set max_selections.

For example:

Question: Please select the content you want to include in the inspection scope
Type: multiple_choice
Minimum selections: 1
Maximum selections: 3
Options:
- Configuration integrity check
- Input format check
- Permission boundary check
- Execution log check

The frontend should provide immediate feedback when a user’s selection is out of bounds, while the server must still perform secondary validation and not fully trust client-side input.

4. High-Risk Operation Confirmation

Confirmation questions should not be treated simply as ordinary single-choice queries. For actions involving the following, it is recommended to use an independent authorization request type:

• Deleting or overwriting content;
• Modifying access permissions;
• Submitting data to external systems;
• Triggering batch executions;
• Using sensitive information;
• Changing production environment configurations.

An authorization request should include:

• The proposed action;
• The scope of impacted objects;
• Irreversible risk descriptions;
• Available alternative solutions;
• Authorization validity period;
• Authorizer and timestamp records.

The system must not treat “no response” as default authorization, nor should it induce user confirmation through vague prompts.

---

VI. Execution Pause and Resume Mechanism

1. State Machine Design

It is recommended to abstract the task execution process as a finite state machine:

created
  ↓
running
  ↓
waiting_for_user
  ↓
resuming
  ↓
running
  ↓
completed / failed / cancelled / expired

Here, waiting_for_user is the most critical state for interactive agents. When entering this state, the executor should perform the following actions:

1. Generate a unique question identifier;
2. Save the current execution context;
3. Record the pending question;
4. Send the question message to the frontend;
5. Send a task pause notification;
6. Halt subsequent capability calls;
7. Start timeout management.

2. User Response Validation Flow

After a user submits an answer, the server cannot resume execution directly. It must perform strict validation:

1. Verify if the task is still in a waiting state;
2. Verify if the question ID matches the current pending question;
3. Verify if the respondent has operational permissions for the task;
4. Verify if the answer format complies with question constraints;
5. Verify if the task has expired, been cancelled, or completed;
6. Apply idempotent processing for duplicate submissions;
7. Write to the audit log before resuming execution.

Pseudocode illustration:

function submitAnswer(taskId, questionId, answer):
    task = loadTask(taskId)
    if task.status != "waiting_for_user":
        return reject("Task does not accept answers currently")
    if task.pending_question.id != questionId:
        return reject("Question ID does not match")
    validateAnswer(task.pending_question, answer)
    saveAnswer(taskId, questionId, answer)
    updateTaskStatus(taskId, "resuming")
    enqueueResume(taskId)
    return accepted()

3. Idempotency and Out-of-Order Handling

Network environments may experience duplicate submissions, frontend retries, or message delays. To prevent the same answer from being consumed multiple times, provide a request identifier for each response and save the processing result on the server.

If a task has already received a valid answer, subsequent identical requests can directly return the previous result; if the answer differs, the system should prompt that “this question has already been processed,” preventing later requests from overwriting earlier ones.

---

VII. Prompts and Executor Boundaries

Prompts can be used to guide the model to ask questions in appropriate scenarios, but they cannot replace system-level process constraints.

For example, system instructions can specify:

• Prioritize asking questions when information is insufficient; do not make unauthorized assumptions;
• Must request authorization for irreversible operations;
• Single-choice questions should provide limited, clear, and mutually exclusive options;
• Multiple-choice questions should specify the minimum and maximum number of selections;
• Sensitive parameters must not be exposed directly to the user;
• High-risk actions must not execute before user confirmation.

However, relying solely on these textual rules is insufficient. The executor must perform hard checks before capability invocations. For example, if a capability is flagged as “requires confirmation,” even if the model fails to initiate a prompt proactively, the system should intercept the call and generate an authorization request.

This embodies the design principle: “The model suggests, the system constrains.”

---

VIII. Observability, Security, and Testing Recommendations

1. Record Key Events

It is recommended to log the following key events:

• Task creation time;
• Configuration version;
• Task state transitions;
• Question creation and answer content summaries;
• Capability invocation names and result statuses;
• Authorization requests and confirmation records;
• Exception categories and retry counts;
• Task completion, cancellation, or timeout reasons.

Logs should avoid recording plain text sensitive data. For user inputs, invocation parameters, and execution results, strategies like desensitization, summarization, or tiered storage can be applied.

2. Set Resource Boundaries

The agent executor must prevent infinite loops and resource exhaustion. At a minimum, it should set:

• Maximum execution rounds;
• Maximum runtime per task;
• Maximum wait time per question;
• Maximum context length;
• Concurrent tasks per session;
• Maximum capability invocations per task;
• Maximum response size limit.

When a limit is reached, the task should end with a clear status, and the user should be informed of the next actionable steps, such as narrowing the task scope, providing additional info, or restarting.

3. Build a Test Matrix

Testing should not only cover “normal responses.” It is recommended to verify at least:

• Legal single-choice submissions;
• Minimum and maximum boundaries for multiple-choice;
• Empty answers and illegal options;
• Duplicate submissions;
• Expired question submissions;
• User task cancellation;
• Task resume failures;
• State recovery after service restart;
• High-risk operation unauthorized interception;
• Out-of-order messages and duplicate delivery;
• Missing or conflicting configuration fields.

Through state machine testing and protocol contract testing, production interaction anomalies can be significantly reduced.

---

IX. Conclusion

The core challenge of an AI agent executor is not making the model “talk,” but enabling the system to reliably pause, ask, authorize, resume, and terminate within complex tasks. Configuration assembly ensures consistent runtime rules, the message protocol ensures frontend-backend coordination, structured questions ensure controllable user interactions, the state machine ensures trackable task lifecycles, and security and audit mechanisms ensure automated capabilities do not cross boundaries.

In practical implementation, it is recommended to first establish a stable configuration model and message protocol, then gradually expand capability invocations, complex orchestration, and multi-task collaboration. Only when the execution process possesses explicit states, verifiable inputs, recoverable contexts, and auditable records can an AI agent transition from a demo-level conversational capability to a reliable engineering application.