Skip to main content

Routines

Agents don't have to wait for someone to message them. A routine runs an agent on its own: every Monday morning, whenever new documents land in a collection, or when one of your systems calls a webhook.

Some things people build with routines:

  • A daily digest of yesterday's customer conversations, emailed to the team
  • An agent that processes every invoice the moment it's imported
  • A weekly report generated from your latest data and sent as a document

Find routines in your application: Agents, pick an agent, then open its Routines tab.

For an employee, these saved jobs also appear as Responsibilities on the team card and in the preparation sidebar. Select either summary to open Work history, review all of the employee's routines and follow Manage routine to the same editor. The employee view labels schedules in UTC and includes paused responsibilities, so you can see what has been planned before it starts running.

Create a routine​

  1. Click New Routine
  2. Name it and write the prompt the agent receives on each run, like "Summarize all conversations from the last 24 hours and email the summary to support-leads"
  3. Add one or more triggers:
    • On a schedule: use the time picker or a cron expression. Cron values are stored in UTC, so 0 9 * * MON means Monday at 09:00 UTC. Check the next-run preview in your local timezone.
    • When a document arrives: choose the collections to watch. The routine runs when a document finishes importing.
    • API Trigger: use the run URL with a Docana API key. The routine ID becomes available after you create the routine.
A draft routine with a saved-prompt field and schedule controls. The cron expression is stored in UTC, and the preview shows local time.
A draft routine with a saved-prompt field and schedule controls. The cron expression is stored in UTC, and the preview shows local time.
Document triggers can watch selected collections. API calls use a routine-scoped key and the run URL shown below.
Document triggers can watch selected collections. API calls use a routine-scoped key and the run URL shown below.

To trigger a routine from code, create an API key with the Routine only scope (see Generating API Keys) and call:

curl -X POST "https://platform.docana.com/api/v1/agents/${AGENT_ID}/routines/${ROUTINE_ID}/run/" \
  -H "Authorization: ApiKey ${DOCANA_API_KEY}"

Manage routines​

The routines list shows each routine's triggers, next run, last run, and success rate. From there you can:

  • Run now: trigger it immediately, useful while testing
  • Pause / Resume: stop the triggers without deleting anything
  • Edit: change the prompt or triggers
  • Delete: removes the routine and its triggers. Past runs are kept.

Every run is recorded with its status, trigger, time, and duration, so you can see what happened while you weren't looking.

Best practices​

  1. Test with Run now first: don't wait until Monday 9:00 to find out the prompt was vague.
  2. Write prompts like instructions to a new hire: say what to do, with what data, and what done looks like.
  3. Use the Routine only API key scope: it limits the key to running routines the owner can access. It is not restricted to a single routine.
  4. Watch the success rate: a routine that fails silently every night is worse than no routine.

Next steps​