Skip to main content
A Programmable Agent can be invoked in two ways:
  • From the Paradime API, using triggerDinoaiAgentRun. See API Reference.
  • From a Bolt schedule, using the Run DinoAI Background Agent command type. This page.
Use Bolt when you want the agent to run on a cron schedule, after another schedule completes, on a PR merge, or as part of a Turbo CI run. Use the API when you want to embed agent runs in a workflow you orchestrate yourself (Airflow, Lambda, webhooks, etc.).

​
Prerequisites

  • A programmable agent definition, either committed to your repository under .dinoai/agents/<name>.yml (see YAML Configuration) or built in the app from the Agents page (see Creating Agents in the App).
  • A connected git repository. A schedule that only runs agents doesn’t need a data warehouse connection or a dbt™ project, so Bolt works in workspaces set up only for agents.
No API keys required. Bolt runs the agent natively inside your workspace, so there are no credentials to configure on the schedule. Existing schedules that still set PARADIME_API_ENDPOINT, PARADIME_API_KEY, PARADIME_API_SECRET, or PARADIME_WORKSPACE_UID as environment variables keep working unchanged, and you can safely remove those variables. API keys are only needed when you trigger agents from outside Paradime (API, SDK, or CLI).

​
Option 1: Configure from the Bolt UI

In the Bolt schedule editor, click Add command and pick Run DinoAI Background Agent:
  1. Agent Name: pick the agent from the dropdown. The list includes agents from .dinoai/agents/*.yml on the configured git branch as well as agents built in the app.
  2. Task: describe the task you want the agent to complete. This becomes the agent’s opening user message.
  3. Save Command, then configure the trigger type (cron, on-merge, on-completion, etc.) and deploy.
You can also start from the agent itself: on the Agents page, click Schedule on an agent’s row. This opens a new Bolt schedule with the Run DinoAI Background Agent command already added and the agent pre-selected, so you only need to write the task.
See the full UI walkthrough at Bolt Command Settings: Run DinoAI Background Agent.

​
Option 2: Configure from schedules-as-code YAML

The UI just writes a paradime dinoai CLI invocation into the schedule’s commands: list. If you manage your Bolt schedules with YAML, add the same command directly:
The arguments mirror the UI fields: See Configuration Reference for the full schedule YAML schema.

​
Lifecycle of a Bolt-triggered run

The command runs natively inside Paradime: when the trigger fires, Bolt dispatches the agent run directly, without going through the public API or authenticating with API keys.
  • Fresh session per run. Each Bolt run starts a new agent session, there is no continuity from one schedule run to the next. Use the API with sendDinoaiAgentMessage if you need multi-turn continuity.
  • Bolt waits for the agent. The command blocks until the agent reaches a terminal state (COMPLETED or FAILED), with a 1 hour timeout, and the Bolt run inherits the agent’s success/failure.
  • Logs. The agent’s messages stream into the Bolt command’s stdout, so they show up in the Bolt run logs (and in the live log stream when polled via the SDK).
  • Session attribution. Runs started from a schedule appear under the Bolt source in the agent sessions panel, not under API, so you can tell scheduled runs apart from programmatic ones.
  • Notifications. Slack notifications configured inside the agent YAML still fire, independently from any Bolt notifications configured on the schedule itself.
  • Overlapping runs. If every command in the schedule is a paradime dinoai command, up to 5 runs of the schedule can be in progress at once. A cron fire, an API call, or another trigger starts its own run even while an earlier one is still working. At 5, a manual or API trigger is refused with This schedule already has 5 runs in progress (limit 5). Wait for one to finish., and a cron fire is skipped without adding a run to the history. Schedules that mix agent commands with other commands run one at a time. The Run button stays disabled while the latest run is in progress.