Architecture Design and Implementation Practice for Integrating Instant Messaging with AI Agents

1. From Message Forwarding to a Complete Agent Interaction System

Allowing users to invoke local agents via an instant messaging (IM) window seems straightforward: receive a message and send back the execution result. However, in practice, this pipeline crosses multiple boundaries, including communication protocols, backend services, process management, and tool execution.

For instance, when a user sends “Analyze the code in this directory,” the system must not only parse the message but also answer a series of questions: Does the user have access to the target directory? Which conversation does this message belong to? If a previous task is still running, should the new message wait or cancel the old task? Will the same instruction be executed repeatedly if the connection drops?

Therefore, this type of system is better defined as a “remote message-driven agent execution gateway” rather than a simple chatbot. Its core objective is to establish a controllable, traceable, and recoverable task pipeline between the communication channel and the local execution environment.

2. Confirm Access Conditions Before Technical Implementation

1. Separate Protocol Capabilities from Implementation Assumptions

During the research phase, the first step is to verify whether the target communication channel provides authorized bot or message access capabilities, and the scope of these capabilities. You cannot assume that just because a sample app can send and receive messages, all account types, deployment environments, and business scenarios will work the same way.

It is recommended to create a capability checklist:

Research Item	Questions to Confirm
Authentication	What authorization flows are supported, and how are credentials refreshed and revoked?
Message Receiving	Does it use event push, long polling, or other mechanisms?
Message Sending	What message types are supported, and are there length or frequency limits?
Session Association	What fields (confirmed by documentation) are used to identify users and sessions?
Status Indication	Are “in-progress” indicators supported, and what are the trigger conditions?
Media Processing	How are attachments downloaded, verified, decrypted, and access-controlled?
Exception Recovery	How are credential failures, duplicate deliveries, and connection drops handled?

These items are research dimensions and do not imply that every channel supports them. The actual implementation should be based on valid documentation, authorized scopes, and verified results.

2. Build Evidence for Key Conclusions

Using AI coding assistants to analyze code and draft plans can reduce initial research costs, but their generated explanations still need verification. Login credentials, message cursors, session identifiers, and encryption flows should never be implemented based solely on natural language summaries.

A more reliable approach is to categorize conclusions into three types:

• Confirmed Facts: Provable from documentation or actual execution results.
• Assumptions to be Verified: Inferred from examples but not yet tested.
• Design Choices: Determined by the system itself, such as queue strategy and log retention period.

This distinction prevents confusing “how it should be done” with “how the API actually works.”

3. Adopt a Layered Architecture to Avoid Coupling Protocol with Execution Logic

It is recommended to divide the system into four main components:

User Message
   ↓
Communication Adapter Layer
   ↓
Session and Task Scheduling Layer
   ↓
Agent Execution Layer
   ↓
Output Formatting and Message Sending Layer

A backend daemon coordinates these layers, managing lifecycles, persisting state, and monitoring runtime.

1. Communication Adapter Layer

This layer only handles channel protocol-related work, including authentication, receiving/sending messages, and handling protocol errors. It should convert external messages of various formats into unified internal events, preventing business logic from directly depending on raw payloads.

The internal event can adopt the following structure. These fields are internal design examples, not actual parameters of any external API:

MessageEvent
  channel_id
  sender_id
  conversation_id
  message_id
  received_at
  content_type
  content

If the channel requires additional reply context, it should be stored as protected routing metadata. It should not be directly concatenated into the user prompt, nor written as plain text into logs.

2. Session and Task Scheduling Layer

The scheduling layer converts messages into tasks and determines when and where tasks execute. Here, three identifiers must be distinguished:

• User Identifier: Used for authorization and resource isolation.
• Session Identifier: Used to associate context and reply destinations.
• Task Identifier: Used to record a specific execution and its status.

Do not conflate the three. A single user may have multiple sessions, and a single session may generate multiple sequential tasks.

3. Agent Execution Layer

The execution layer starts or invokes the agent, passes task inputs, parses structured outputs, and manages timeouts, cancellations, and exit states.

To reduce future replacement costs, define a unified execution adapter interface, such as “start task,” “read event,” “cancel task,” and “query status.” Whether the underlying mechanism uses a standalone process or a resident service depends on the runtime environment and the agent’s actual capabilities.

4. Message Receiving: Reliability Outweighs Polling Loops

1. Proper Use of Long Polling

If the channel supports long polling, the client can initiate a request that allows the server to wait for new messages. After receiving a result or timing out, it sends the next request.

Note that a normal wait timeout and a network failure are different events. A normal timeout simply means there are no messages yet; connection failures, authentication failures, and abnormal response formats should enter different handling branches.

During network anomalies, a backoff strategy with random jitter is recommended to prevent multiple instances from continuously retrying simultaneously. For authentication failures, prioritize checking the credential status rather than infinitely retrying the same invalid request.

2. Reliably Enqueue Before Advancing the Receive Position

Assuming the channel supports cursors or acknowledgment mechanisms, the following processing order is recommended:

1. Receive the message and complete basic validation.
2. Write the message or task to persistent storage.
3. Confirm successful write.
4. Advance the cursor or acknowledge receipt according to protocol rules.

If you advance the receive position before writing the task, a process crash between the two steps could lose the message. Even so, you cannot assume the system has an end-to-end “exactly-once” execution guarantee; message redelivery, send timeouts, and external tool side effects still need individual handling.

3. Use Deduplication Records to Protect Execution Entry

If the channel provides a stable message identifier, you can combine the channel, session, and message ID to generate a deduplication key. Existing tasks should not be restarted due to redelivery.

If there is no stable message ID, using only a content hash for deduplication carries a false-positive risk, as users might genuinely send the same instruction repeatedly. In this case, clearly define the limitations of the deduplication strategy rather than claiming to completely eliminate duplicate executions.

5. Queues and Session Isolation: Keeping Concurrency Under Control

For coding agents, serial execution is usually the default for a single session. This is because tasks may share context, file directories, and tool states; concurrent execution can easily lead to file overwrites or context corruption.

Different sessions can run in parallel, but parallelism must be constrained by resource limits. It is recommended to set:

• Global running task limit;
• Per-user pending task limit;
• Per-session queue length limit;
• Per-task execution time limit;
• Output and attachment size limit.

When a queue is full, explicitly notify the user that the task was not accepted, rather than silently dropping the message.

Task states can be designed as:

Received → Queued → Executing → Completed
                            ├→ Failed
                            ├→ Canceled
                            └→ Timeout

“Task Completed” and “Reply Sent Successfully” should be recorded separately. If a task is completed but the reply fails to send, the system should retry delivering the result, not rerun the entire task.

6. Local Process Bridging: Structured Events Over Text Guessing

When an agent supports non-interactive invocation, you can pass tasks via standard input and read events via standard output. However, before implementation, you must confirm the actual input formats, output modes, and process lifecycles it supports. Do not assume all command-line programs can be integrated this way.

1. Do Not Concatenate Messages into Command Strings

When starting a subprocess, use a fixed program path and a clear argument list, passing user content as input data to avoid shell interpretation and execution.

Additionally, restrict the working directory, inherited environment variables, and credentials accessible to the process. The communication service’s authentication info usually does not need to be exposed to the agent subprocess.

2. Correctly Handle Streaming Data Boundaries

A chunk of bytes read from standard output does not necessarily correspond to a complete event. One event might be split across multiple reads, or one read might contain multiple events.

Therefore, the parser must maintain a buffer based on the confirmed event protocol. If the output uses a line-by-line structured format, reassemble line boundaries first, then parse individual records.

Standard error output should be collected separately for diagnostics and should not be sent directly to users. Internal paths, environment info, and sensitive configurations might appear in error content.

3. Distinguish Process Events from Final Results

Agent output may contain incremental text, tool call statuses, error messages, and final results. The system should determine the display method based on the event type, rather than forwarding all content as-is.

For users, it is usually only necessary to present essential progress, actions requiring confirmation, and final results. Internal debug events should be kept in controlled logs.

7. Streaming Replies: Balancing Timely Feedback and Message Integrity

Agents may generate text fragments at high frequencies, while communication channels usually have limits on message length, send frequency, and format. Therefore, it is not advisable to send a message immediately upon receiving a single fragment.

A “buffer, merge, segment” output strategy can be adopted:

1. Append incremental text to the task buffer.
2. Determine whether to send based on paragraph boundaries, buffer size, and wait time.
3. Prioritize splitting at natural paragraphs or list items.
4. Send remaining content when the task ends.

These thresholds should be determined through testing, not by treating sample values as channel guarantees.

Rich text also needs a degradation strategy. If the channel cannot fully support headings, tables, or code blocks, convert them to readable plain text. For long code snippets, pay special attention to integrity after segmentation; if necessary, send a summary first, then provide the full content via authorized attachment capabilities.

If the channel supports “in-progress” indicators, update them at a reasonable frequency; if not, use regular status messages. Regardless of the method, status indicators cannot replace task timeout and failure feedback.

8. Security Boundaries: Remote Chat Input Must Not Directly Gain Execution Permissions

A verified communication account only proves that the message source meets certain authentication conditions; it does not mean the message should have full permissions in the local environment.

1. Set Up an Independent User Authorization Layer

It is recommended to separate identity authentication from operation authorization. After receiving a valid message, you should still check whether the user is allowed to invoke the agent, and which workspaces and tools they can access.

Authorization policies should deny by default to prevent new users from automatically gaining execution permissions.

2. Implement Confirmation Mechanisms for High-Risk Operations

Reading code, modifying files, executing commands, and deleting resources carry different risks and should not use the same approval rules.

Operations involving deletion, data exfiltration, accessing credentials, or modifying system configurations should require explicit confirmation. The confirmation content must be bound to the specific operation and task, and have an expiration time, preventing a vague “agree” from being reused for other actions.

3. Treat External Content as Untrusted Input

Webpages, documents, attachments, and code comments may contain prompt injection instructions. Even if submitted by legitimate users, they should not gain elevated privileges.

Model-level prompt constraints only serve as an auxiliary measure. True boundaries must be enforced through directory permissions, tool whitelists, network access policies, and resource quotas.

9. Attachment Handling and Credential Protection

Attachment integration should be built as an independent capability progressively, rather than being included in the text message flow by default. Before processing, check the actual file size, file type, and allowed ranges to avoid relying solely on extensions for security.

Attachments should be stored in an isolated directory with lifecycle management. For media requiring decryption, strictly follow confirmed protocols; do not guess encryption methods, key meanings, or data layouts.

Authentication credentials, session routing information, and attachment access URLs should also be graded for protection:

• Restrict access permissions during storage;
• Mask sensitive data in logs by default;
• Pass only to components that truly need them;
• Support cleanup after revocation and invalidation;
• Do not include sensitive metadata directly into the model context.

10. Testing and Observability Determine Long-Term System Viability

Successfully completing a single Q&A only proves the basic pipeline works; it does not prove the system is reliable.

Testing should cover at least the following scenarios:

• Duplicate delivery of the same message: Does it only create one task?
• Multiple consecutive messages in the same session: Is the order as expected?
• Two users accessing the system simultaneously: Are context and directories isolated?
• Subprocess abnormal exit: Can the task enter a clear failed state?
• User cancels task: Do related processes and subsequent outputs stop?
• Execution completed but send timeout: Is duplicate execution avoided?
• Service restart: How are pending tasks and abnormally interrupted tasks recovered?
• Long text, special characters, and incomplete events: Do they cause parsing exceptions?

Run logs should link reception, queuing, execution, and reply via the task ID, but do not need to record full conversations and file contents by default. Monitoring can focus on queue length, wait time, execution duration, failure rate, send retries, and process abnormal exits.

For tasks with external side effects, recovery strategies must be particularly cautious. After a service restart, do not blindly replay all “executing” tasks; instead, check the task results and side effect states first.

11. Recommended Phased Implementation Path

Phase 1: Complete the text message closed loop: limit users, limit directories, execute single tasks, and provide clear success/failure feedback.

Phase 2: Add session mapping, persistent queues, message deduplication, and task cancellation so the system can handle basic concurrency and restart recovery.

Phase 3: Add incremental output, content segmentation, status indicators, and attachment support to improve the interactive experience.

Phase 4: Improve permission approvals, resource isolation, audit logs, and fault drills before expanding usage scope.

AI coding assistants are suitable for code implementation and test generation in each phase. However, each development task should provide clear input/output contracts, exception scenarios, and acceptance criteria. Asking the assistant to restate the architecture and boundaries before writing the implementation usually makes it easier to spot misunderstandings than directly asking it to “build the whole feature.”

Conclusion

Integrating instant messaging with AI agents truly requires solving the combination of communication reliability and execution security: messages cannot be lost arbitrarily, tasks cannot be unintentionally repeated, users cannot cross wires, and tool permissions cannot run out of control just because the entry point is convenient.

Starting from protocol verification, advancing through layered adaptation, reliable queuing, structured event parsing, and controlled execution, you can build a demo-level remote Q&A into an engineering system with sustainable maintenance value.