Handling External Resource Requests

In this section, we’ll discuss how to handle external resource requests generated by your agent during its session. An external resource request occurs when the agent requires additional input from an external source, such as the user, before proceeding with an action. This might include filling out a form field, confirming a decision, or providing necessary details that the agent cannot determine by itself.

Assisfy allows your agent to emit a special event, external_resource_requested, to request this input. You, as the developer, need to listen for this event, process the request, and then respond with the required information.

---

Step 1: External Resource Request Event

During the session, the agent might trigger an external_resource_requested event if it requires some input from you. This event includes details about the request, such as what resource is needed (e.g., a user’s email, a text input, etc.) and the reason for the request.

Example of an External Resource Requested Event

When your agent triggers this event, you will receive a WebSocket message with the following JSON structure:

{
  "event": "external_resource_requested",
  "resource_type": "user_input",
  "reason": "The agent needs the user’s email address to proceed with registration.",
  "field_name": "email",
  "additional_info": {
    "placeholder": "Please enter your email address"
  }
}

Here’s what the fields represent:

• event: Always external_resource_requested to indicate this event type.

• resource_type: The type of resource being requested (e.g., user_input, file_upload, etc.).

• reason: A brief description of why this resource is being requested (helps the user understand why they need to provide the input).

• field_name: The name of the field or resource the agent is waiting for (e.g., email, username, etc.).

• additional_info: Additional information that might help the user provide the correct input, like a placeholder text or format.

Step 2: Responding to the External Resource Request

Once you receive an external_resource_requested event, you will need to respond with the requested input in a structured format. You can respond by emitting a message back to Assisfy, which will continue the session with the provided resource.

The response to the external resource request should include the resource_type (to specify the type of response), input (the actual user-provided value), and a confirmation that the resource was granted.

Example Response

If the agent requests an email input from the user, you can respond with the following JSON:

{
  "event": "external_resource_response",
  "resource_type": "user_input",
  "input": "[e-mail]",
  "session_id": "session_12345",
  "action_session_id": "action_12345",
  "status": "granted"
}

Here’s a breakdown of the fields:

• event: The event type is external_resource_granted, indicating that you are responding to the request.

• input: The value that you are providing in response to the request (e.g., the email the agent was asking for).

• session_id: The ID of the session that initiated the request.

• action_session_id: The ID of the specific action session that triggered the request.

• granted: Indicates whether the resource has been successfully granted. You can use values like true or false.

Step 3: Error Handling and Denial of Resource

In some cases, you might need to deny the resource request or handle errors. For example, if the user refuses to provide their email or the data is invalid, you can respond with a denied status.

Example Denied Response

{
  "event": "external_resource_granted",
  "granted": false,
  "input": null,
  "session_id": "session_12345",
  "action_session_id": "action_12345",
  "error_message": "User refused to provide the email."
}

In this response:

• input: Can be null to indicate no value was provided.

• error_message: An optional field to explain why the resource request was denied.

Step 4: Monitoring the Response

After responding to an external resource request, Assisfy will continue processing the session based on the input you provided. If everything is valid, the agent will proceed with the next action.

Sample Response Upon Success

{
  "event": "action_run",
  "action_session_id": "action_12345",
  "name": "click"
}

The agent will proceed to perform the action specified, like clicking a button, and you will receive further events to monitor the progress of the session.

---

Summary

Handling external resource requests in Assisfy is a straightforward process where your agent sends a request for additional input and waits for your response. This interaction allows the agent to dynamically adapt to real-world situations where human input is required, such as filling out forms, confirming choices, or uploading files.

• The agent will trigger an external_resource_requested event.

• You respond with an external_resource_granted event, providing the requested resource.

• If needed, you can deny the request by sending a denied status along with an error message.

By properly managing external resource requests, you ensure that your agent can operate effectively in a variety of real-world scenarios, enhancing its ability to interact with users and systems in a flexible and efficient way.