Integration with an AI agent

When creating a new workflow or editing an existing one, in the management console, under Create workflow / Edit workflow, select Constructor.

From the Integration steps section on the left side of the screen, drag the AI agent element to the appropriate workflow location in the constructor window.

You can drag and drop steps into areas marked by the dotted line in the workflow schema, such as Add a step, etc.

In the workflow schema window, click the added AI agent section to select it.

At the right of the window, on the Settings tab.

1. In the Step name field, enter a name for the workflow step.

2. Under AI agent settings:

   1. In the Model field, select a large language model for the AI agent to use.
   2. In the Role field, describe the role that defines the AI agent's functions and experience, e.g., car parts consultant.
   3. In the Goal section, describe an individual goal that guides the AI agent's decision-making, e.g., help with the choice of parts for the specified vehicle.
   4. Optionally, in the Backstory field, specify a backstory defining the AI agent's personality and enriching the context, e.g., you find the best value for money car parts and briefly explain your choice.
   5. Optionally, under Knowledge sources, click to specify knowledge sources for the AI agent. Select:

      • Text: For a text-based knowledge source.

      • File: For a file-based knowledge source:

        1. Select the type of the knowledge source file.
        2. Select a data source:
           • Public URL: Add a public URL to the file.
           • Object Storage: Specify names of the bucket and object containing your file, e.g., prefix/subprefix/data.json.
   6. Optionally, under Tools, click and add a tool for your AI ​agent to use for obtaining external data when generating a response:

      • In the MCP server address field, enter your MCP server URL, e.g., https://mcp.example.com/sse.

      • In the Transport field, select a transport mechanism type for interacting with the MCP server:

        • STREAMABLE: Your AI ​agent receives updates (events) from the server with no need for a persistent HTTP connection. Data exchange between the AI ​agent and the server is bidirectional.
        • SSE: Your AI ​agent receives updates from the server over a persistent HTTP connection. Data is only transmitted from the server to the AI ​agent.

      • In the Authorization field, specify data required to authorize the AI agent on the MCP server:

        • No authorization: MCP server requires no agent authorization.

        • OAuth token: MCP server requires an OAuth token for agent authorization. Specify the OAuth token or Yandex Lockbox secret that stores the token. Select:

          • Lockbox to store the OAuth token in a secret; in the Secret section, select the secret, its version, and the key used to store the OAuth token.

            If you do not have a Yandex Lockbox secret, click Create to create it.

          • Text to store the OAuth token in the specification as text; enter the OAuth token in the Value field.

            Warning

            It is not safe to store your OAuth token in the specification in plain text.

        • IAM token: MCP server requires an IAM token for agent authorization. The system automatically issues this IAM token for the service account associated with the workflow.

3. Optionally, under Tasks, use to set the tasks the AI agent has to complete:

   • In the Task description field, describe the essence of the task you want the AI agent to perform, e.g., find an oil filter for a BMW 320i.
   • Optionally, in the Expected result field, describe the format you expect to get the result in, e.g., a list of addresses of stores selling the car parts you need.

4. Optionally, in the Timeout, ms field, set the maximum execution time for the current step.

5. Optionally, to set a custom retry policy for a step, expand the Retry policy section and click Retry policy. In the form that appears:

   1. Optionally, in the Initial delay, ms field, set the initial value for a delay between step retries.

   2. Optionally, in the Backoff rate field, set the multiplication factor for delay before each step retry.

   3. Optionally, in the Maximum delay, ms field, set the value for a maximum delay between step retries.

   4. In the Errors field, select the errors for which the step will or will not be retried.

      For detailed information about possible errors, see this section.

   5. Optionally, in the Maximum number of retries field, set the maximum number of step retry attempts.

   6. In the Error selection mode field, select:

      • INCLUDE: Retry executing a step when errors specified in the Errors field occur.
      • EXCLUDE: To retry executing the step on any errors other than those specified in the Errors field.

   If you want to delete a retry policy you created for the step earlier, click and select Delete in the Retry policy row.

   If no custom retry policy is configured for a step, the retry policy set for the whole workflow will apply.

Optionally, navigate to the Input tab and set a jq template to filter the workflow state fed into the step.

Optionally, navigate to the Output tab and set a jq template to filter the step outputs added into the workflow state.

Optionally, add an error transition rule for the step you are creating to handle errors you may get during this step.