# Run an agent Source: https://docs.finic.io/api-reference/endpoint/run-agent POST /run-agent/{agent_id} Creates a new session and starts execution of the specified agent # Get session status Source: https://docs.finic.io/api-reference/endpoint/session GET /session/{session_id} Retrieves details of a specific session by its ID # Development Source: https://docs.finic.io/development/development How build new automations using Finic. These are instructions for how to builds a new automation from scratching using Finic. See [Finic Recorder](/development/finic-recorder) for how to automatically generate an automation with the Finic chrome extension. ## Initializing a new project Install Finic globally with `pip install finic` or `pipx install finic`. Then run the following command to create a new Finic automation in the current directory. ```bash theme={null} $ finic init ``` This automatically sets up your project structure, including some boilerplate code. Your code should go in `main.py`. ## Providing inputs Most automations will require input varibles to be provided at runtime. This can include auth secrets like usernames and passwords, variables that define the automation's behavior, or values that should be input into form fields. ### Local You can include input values in a file called `finic_input.json` in the root directory of your project. This automaticaly gets picked up by Finic and passed into your `main` function. ### Production In production, you can specify inputs for a task when running it manually from the Finic dashboard, or by specifying it in a `task_input` parameter in the request body when triggering a task from the API. ## Defining selectors Selectors should be placed in `selectors.yaml` (see the example below). Both XPath and CSS selectors are supported. They can then be accessed directly from the Finic client, assuming the `selector_source` is set to `file`. ```python theme={null} finic = Finic(selector_source='file') finic.selectors.get('email_field') ``` Selectors can also be defined directly in your code, although this approach makes your code harder to read and less modular. ## Example Here's an example of a basic automation. ```python main.py theme={null} from playwright.sync_api import Playwright from finic_py import Finic @Finic.entrypoint() def main(input: Dict): finic = Finic(selector_source='file') page, context = finic.launch_browser_sync(headless=False, slow_mo=500) page.goto("https://practicetestautomation.com/practice-test-login/") if page.locator(finic.selectors.get('username_field')).count() > 0: page.locator(finic.selectors.get('username_field')).fill(input.get('username_field')) page.locator(finic.selectors.get('password_field')).fill(input.get('password_field')) page.locator(finic.selectors.get('login_button')).click() context.close() ``` ```yaml selectors.py theme={null} username_field: //input[@name="username"] password_field: //input[@name="password"] login_button: //button[@name="submit"] ``` ```json finic_input.json theme={null} { "username_field": "example_username", "password_field": "password1234" } ``` # Finic Recorder Source: https://docs.finic.io/development/finic-recorder How to record and replay traces using Finic's Chrome Extension. Finic has a Chrome Extension that greatly simplifies the process of developing new automations by recording all DOM interactions on a page, and generating code and selectors to reproduce those interactions. # Recording a flow Download the Finic Recorder Chrome extension [here](). To install it in Chrome, go to Extensions -> Manage Extensions and enable Developer Mode in the top right. Then click "Load unpacked". Select the `dist` directory from the zip file. Once the extension is installed, enable it from any page by click on the extension. When the sidebar appears, the Finic Recorder will automatically be in "Record" mode. Now you can start interacting with the page and the recorder will automatically capture your interactions and convert it into Typescript or Python code, in real-time. GIF here ## Switching between modes There are two basic modes in the Finic Recorder: * **Record**: Your interactions on the page will be captured and added to the automation script. * **Edit**: Interactions on the page are no longer captured, allowing you to edit the automation script directly. Toggle between the two modes with the "Switch Mode" button in the top bar. ## Basic interactions Playwright locators are automatically generated for clicks and inputs. Sometimes, the selector might not be ideal, for example if a label is not available and it uses an attribute or text that is not guaranteed to exist when the automation runs automatically. You can change the selector used in the `Locator` tab at the bottom of the extension. ## Control Flow Most automations require more than just simple clicks and inputs in order to reproduce human behavior. The Finic Recorder includes built-in support for loops, if statements, error handling, and branching flows. You can find the Control Flow menu at the bottom of the Recorder UI. ### Loops Select the container of the element you want to loop through. Select "Loop" from the Control Flow menu and pick one of the child elements you want to loop through. Double check that the selector returns all child elements. You can go into Edit mode and add a log statement for each element to verify that the loop is working as expected. ### Conditional Logic Select "Conditional Statement" from the Control Flow menu. Add branches to your statement. In the "If..." field, enter a natural language prompt describing the conditions of this branch. Click on the "Then..." field to record a series of interactions on the page. ## Error Handling There are multiple ways to handle errors: ### Selector timeouts By default, Playwright locators time out after 30 seconds, after which the automation will terminate. If you know a particular step is flaky or can have multiple outcomes, handle it gracefully. ### # Testing a recorded flow Once you're finished recording a flow, replay the automation by going back to the original page. Ensure that the state of the application is the same as when you started. For example, if you started while logged out, log out first. If there are forms that are partially filled out, reset those forms. Then click the "Resume" button to run the automation end to end, or the "Step over" button to run it step by step. # Deploying an automation Your automation script is automatically synced with Finic Cloud as you work. Once you've tested and verified it's working, go to the [Finic dashboard](https://app.finic.io) and navigate to the "Deploy" page. The Finic Recorder is built on top of Playwright's [codegen](https://playwright.dev/docs/codegen) and [trace](https://playwright.dev/docs/trace-viewer-intro) modules. # Reuse Auth State Source: https://docs.finic.io/development/reuse_auth How to preserve authenticated status across sessions. For any web service that requires authentication, you'll want to save your cookies and local storage and re-use them for every session. Otherwise, you'll need to log in each time, and each execution will be treated as a new browser by the service. This slows your automation down, and can lead to rate rate limits or other obstacles if the service detects many logins from different browsers in a short period of time. In order to save the browser state, call `finic.save_browser_state()` each time after your automation completes a login attempt. Example: ```python theme={null} from playwright.sync_api import Playwright from finic_py import Finic finic = Finic(selector_source='file') page, context = finic.launch_browser_sync(headless=False, slow_mo=500) page.goto("https://practicetestautomation.com/practice-test-login/") if page.locator(finic.selectors.get('username_field')).count() > 0: page.locator(finic.selectors.get('username_field')).fill(input.get('username_field')) page.locator(finic.selectors.get('password_field')).fill(input.get('password_field')) page.locator(finic.selectors.get('login_button')).click() page.wait_for_load_state('load') finic.save_browser_state() context.close() ``` This saves your browser state to `browser_state.json`. The next time the automation runs, it will check for `browser_state.json` and if it exists, will load the cookies and local storage objects into memory. For most websites, this means the automation does not need to login in again unless the session has been invalidated by the service. # Deployment Source: https://docs.finic.io/production/deployment How deploy and run Finic automations. Deploying a Finic automation is easy. Simply run `finic deploy` from your command line in any project that's a valid Finic project. All you need is a Finic API key, which you can find [here](https://app.finic.io/settings). Once an automation is deployed, you can find it at [https://app.finic.io/automations](https://app.finic.io/automations). ## Running an automation ### Dashboard You can run automations manually from the dashboard by clicking on any automation to open it, then clicking the "Run" button. ### API You can invoke automations programatically by sending a request to the `run-agent` endpoint. See the [API reference](/api-reference/endpoint/run-agent) for more information. ## Options You can provide the following options both in the dashboard and via API: * **max\_retries:** The number of times to retry this automation if it fails. Helps account for non-deterministic issues that cause flakiness, like network issues or temporary downtime. * **browser\_id:** A unique identifer for the browser you'd like to use. Useful for preserving cookies and local storage accross sessions to avoid having to authenticate each time. # Monitoring Source: https://docs.finic.io/production/monitoring How to view logs and recordings from your automations. You can view logs and recordings of each time your automation has run, directly from the [Finic dashboard](https://app.finic.io). Click on any automation, then select any execution to view its metadata. ### Status Shows you if this execution succeeded, failed, or is still running. ### Results Any results returned by the automation, in JSON format. ### Logs Logs from the instance that ran this automation. Any print statements or other logging tools will all dump into these logs. ### Session Recording A video recording of the session, assuming the automation was not running in headless mode. Useful for debuggin issues and seeing where the automation failed. # Getting Results Source: https://docs.finic.io/production/results How to get results from your automations. Some automations include a scraping or data collection component. If your automation returns any data, you can retrieve it in three ways. ## Webhook The best way to retrieve results from your automation is to provide a webhook URL. Once an automation is finished running, we send the results to this endpoint. ## API Polling If you don't have a webhook set up, you can poll our endpoints for results. When you call the `run-agent` endpoint, you will receive a `session_id`. You can then call the `session` endpoint with this ID to check the status of the automation. If the `status` property is `success`, you can find the results in the `results` property. See the [API reference](/api-reference/endpoints/session) for more information. ## Dashboard You can view results directly in the Finic dashboard by clicking on any automation, selecting the execution, then clicking on the "View Results" button.