# 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: ```json { "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: ```json { "event": "external_resource_response", "resource_type": "user_input", "input": "user@example.com", "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** ```json { "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** ```json { "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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://assisfy.gitbook.io/assisfy.ai/getting-started/quickstart/running-your-first-agent/handling-external-resource-requests.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.