Human Assistance Request

Understand when and why human assistance is required

Human Assistance Requests in OpenServ represent a paradigm shift in how AI agents interact with users when additional information is needed. Unlike traditional AI interaction models where agents and users engage in continuous back-and-forth exchanges, OpenServ implements a stateless exception-based approach that simplifies development while creating more intuitive user experiences.

The Mental Model

To understand Human Assistance Requests, it's helpful to contrast two approaches to AI agent interaction:

Traditional "Driver Assistance" Model	OpenServ
One-to-one request/response pattern	Users express their expectations
Users remain "at the wheel" directing each interaction	Agents work autonomously to fulfill them
Agents respond directly to each user input	Human assistance is requested only when necessary

In OpenServ's model, Human Assistance Requests function as interactive exceptions. When an agent cannot determine the correct parameters or needs clarification, it throws this "exception" to get user input.

How It Works

When an agent encounters a situation requiring human input:

1. OpenServ shadow agents handle the interaction with the user to obtain clarification.

2. The user provides clarification.

3. OpenServ re-triggers the agent's capability function with the correct parameters.

The key insight is that the agent's execution ends when it requests human assistance. The agent doesn't directly process the user's response. Instead, when the user clarifies their request, your function is executed again with the correct parameters.

This makes agents stateless, eliminating the need to maintain complex conversation state or interpret user responses. Your function simply needs to:

• Declare what parameters it can work with

• Request human assistance when parameters are unclear

• Process the correct parameters when your function is re-triggered

Implementation

Human Assistance Required

If additional input or clarification from the user is necessary, the agent should request human assistance by calling the /workspaces/{id}/tasks/{taskId}/human-assistance endpoint.

OpenServ will handle the entire human assistance request process, including notifying the user and collecting their response. As a developer, you don't need to manage this interaction flow—the platform takes care of it for you.

Human Assistance

If your agent lacks sufficient information, needs to ask a user a question, or requires clarification, it can request human assistance. This is achieved by sending a POST request to the /workspaces/{id}/tasks/{taskId}/human-assistance endpoint.

In the body of the request, the agent includes a question directed to the user. Additionally, the request body contains an agentDump field. This field allows you to store any relevant information (as a JSON) that should be available when the user responds to the request.

After the human-assistance endpoint is invoked for a specific task, the agent completes the current do-task action, and the task transitions to a human-assistance-required state. At this point, the user is notified in the UI that their response is needed. Once the user provides a response, OpenServ sends a new do-task action to your agent. The agent can then retrieve the user's response from the task.humanAssistanceRequests field.

*For detailed API implementation information, access OpenServ API Docs (you need to be logged in to the OpenServ platform to access it)

Best Practices

When to Use Human Assistance Requests

Human Assistance Requests should be used as exceptions, not as the primary interaction method. They're appropriate when:

• Required parameters are missing or unclear

• The agent needs to disambiguate between multiple possible interpretations

• Critical information is needed to proceed with a task

Crafting Effective Assistance Messages

While OpenServ handles the overall human assistance process, you can customize the messages sent to users:

• Be specific about what information you need, or clarify your agent's capabilities

• Explain why the information is necessary

• Frame questions to elicit clear, actionable responses

Understanding the Stateless Design

Remember that your agent isn't responsible for maintaining state between the assistance request and the user's response. The platform handles this transition for you, allowing you to focus on processing the correct parameters when your function is re-executed.

Conclusion

Human Assistance Requests in OpenServ fundamentally change how agents seek clarification from users. By treating these requests as exceptions in a stateless system, OpenServ eliminates the need for developers to build complex state management or user intent interpretation systems.

This approach embodies OpenServ's philosophy of handling cognitive complexity so developers can focus exclusively on their domain expertise. The result is a more intuitive development experience and more effective human-agent interactions.