Skip to main content

Run agents from your systems

A conversation isn't the only way to use an agent. Sometimes your system has the prompt: an invoice arrives, a case is escalated, a report is due, and you want the agent's answer inside your own workflow. The execute endpoint turns any published agent into a function your backend can call.

What people build with it​

The pattern is always the same: your system owns the trigger, the agent owns the thinking, and the answer lands back in your workflow.

  • Invoice intake: your ERP receives an invoice, calls the agent to extract the line items and flag anomalies, and files the result on the invoice record.
  • Ticket triage: a ticket escalates in your helpdesk, a webhook asks the agent for a summary and a recommended owner, and the answer becomes a ticket comment.
  • Generated deliverables: a nightly job asks the agent to write the daily operations report from the latest documents, and posts it where the team reads it.

If your trigger is a schedule or new documents arriving, you don't even need the API call: routines own those triggers for you.

Set up once​

Three exports make every snippet below paste as-is:

export DOCANA_API_KEY=your_api_key_here    # see Generating API Keys
export AGENT_ID=1234567890123              # docana agents list
export APPLICATION_ID=1234567890124        # docana applications list

Fire the run​

Say that invoice just landed in your ERP. One call hands it to the agent. The prompt says what to do; context carries the data your system already knows, so the agent doesn't have to fish it out of prose:

curl -X POST "https://platform.docana.com/api/v1/agents/${AGENT_ID}/execute/" \
  -H "Authorization: ApiKey ${DOCANA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Review this invoice and flag anything unusual.",
    "context": { "invoiceId": "INV-2026-0841", "vendor": "Acme Corp", "amount": 12400 }
  }'

Docana answers before the agent even starts thinking. You get a ticket for the run, and the agent works in the background:

{
  "success": true,
  "executionId": "exec_01j9z3k2b4c5d6e7f8g9h0j1k2",
  "assistantMessageId": "…"
}

Want to watch it happen instead? The same run, live from your terminal: docana agent support run "Review this invoice".

Get the answer​

Inside a webhook and expecting a quick verdict? Don't build a polling loop. Add one field to the body, "waitSeconds": 60, and Docana holds the response until the agent finishes (up to 120 seconds). The response then carries a waitOutcome: completed, failed, or timeout. A timeout never cancels the run; the agent keeps working and you check back with the executionId.

For anything longer, check back when it suits you:

curl "https://platform.docana.com/api/v1/agents/${AGENT_ID}/executions/${EXECUTION_ID}/" \
  -H "Authorization: ApiKey ${DOCANA_API_KEY}"
{
  "id": "exec_01j9z3k2b4c5d6e7f8g9h0j1k2",
  "status": "FINISHED",
  "threadId": "cmly7kpth0019x5c9dyn3hegk",
  "startedAt": "2026-08-07T14:03:22.000Z",
  "executedNodes": [ … ]
}

Repeat every few seconds until status leaves RUNNING (FINISHED, or STOPPED, STALLED and TIMED_OUT for runs that did not complete); finished runs are served from a cache, so polling is cheap. The detail has the answer and a timeline of what each node did (fields=compact or fields=full for more), and the CLI shows the same run as a readable table: docana agent support runs get --execution-id <id>.

Two small things worth knowing: the execution row appears when the run starts, so a brief 404 right after scheduling just means "not started yet". And a run you no longer need is one call to stop: docana agents runs stop --agent-id <agent> --execution-id <id>.

Give long runs a time limit​

Some agents legitimately work for minutes: a supplier screening that searches, reads and reviews dozens of articles, a report over a hundred documents. Left alone, a run like that has no ceiling of its own. It ends when it ends, and if it never ends (a stuck tool, a loop) nothing tells you until much later. Declare how long the agent may take and Docana enforces it:

{
  "workflow": {
    "toolName": "screen_supplier",
    "toolDescription": "Screens a supplier for adverse media",
    "executionTimeoutSeconds": 900,
    "entryPoints": ["…"],
    "nodes": ["…"]
  }
}

In the builder the same setting is the Execution time limit field, under Basic Info → Configuration. executionTimeoutSeconds is a wall-clock budget for one execution, from 30s to 1800s (30 minutes). When it passes, Docana aborts the run: model calls in flight are cancelled, sub-agents included, and the execution finishes with status: "TIMED_OUT" instead of FINISHED. The nodes that were cut record the reason in their error, so the run's timeline in Logs shows where the time went. It applies only when you set it: an agent that declares nothing keeps today's behavior, with no explicit ceiling.

Pick a number about twice what a healthy run needs. Too tight and a slow day cuts good runs. Too loose and a stuck run occupies a worker until the ceiling. The budget is per attempt, so a run Docana resumes after an infrastructure failure starts a fresh one.

Keep the conversation going​

The agent remembers. The execution detail includes a threadId; send it with your next prompt and the agent picks up right where it left off, invoice and all:

{
  "prompt": "Now draft the rejection email for that invoice.",
  "threadId": "cmly7kpth0019x5c9dyn3hegk"
}

Same endpoint, same call as before, one extra field. That's a multi-step workflow: review on arrival, then draft the email, then whatever comes next, each step building on the last.

Which front door do you need?​

Three ways into the same agent, one right answer per situation:

  • Execute API (this guide): your system has a one-off prompt and wants the result programmatically.
  • Routines: the run happens on a schedule or a document event, and Docana owns the trigger.
  • Channels: a human is on the other end, so put the assistant where they already are.

Debug from the terminal​

The same executions are visible to the CLI, which is the fastest way to inspect a misbehaving run:

docana agent support runs list --errors
docana agent support runs get --execution-id <id>

Next steps​