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.

Run the agent behind an employee​

An employee is an Assistant application with a profile. Its employee ID is the application ID, while AGENT_ID identifies a workflow inside it. Find the employee in the employee list API and use its published, enabled chatAgentId when you want the same agent selected by Work together. Do not pass the employee ID to an agent execution endpoint.

Prepare and test the draft, then publish it before calling the execute endpoint. Existing applications without employee profiles can use the same endpoint with their own published agents.

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 QUEUED and RUNNING (FINISHED, or STOPPED, STALLED and TIMED_OUT for runs that did not complete). QUEUED means the run was accepted and is waiting for a worker. 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 Limit how long a run may take switch under Basic Info → Configuration, with a slider from 30 seconds to 30 minutes. 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.

Queue API executions​

By default a run started through POST /api/v1/agents/{agentId}/execute/ begins the moment the API accepts it. That is what a user waiting for an answer wants, and it is the behaviour every agent has unless you change it. Two things can send a run to the queue instead:

  • The application is at its concurrency limit. Rather than rejecting the start, the platform queues it; the response is the same acknowledgement with the same executionId, and getAgentExecution reports QUEUED until a worker picks the run up.
  • The agent declares "dispatch": "queued" in its workflow (in the builder: Run in the background). Every run of that agent waits for a free worker. Nothing is lost if the platform restarts, you can submit any number of runs at once, and each one gets a bounded share of resources. Choose it for batch jobs, screenings and long runs.
{
  "workflow": {
    "dispatch": "queued",
    "entryPoints": ["start"]
  }
}

A queued run usually starts within seconds. Poll getAgentExecution the same way you do today; QUEUED is the second non-terminal status next to RUNNING. waitSeconds works for queued runs too: the response reports executionStatus: "QUEUED" when the window elapses before a worker claimed the run.

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>

Inspect the employee's work history​

For an employee, open Work history in its overview to see recent executions, duration, step counts, workflow versions, and links to the detailed logs. Expectation runs appear separately under Expectations. A FINISHED execution means the run ended without an execution error, not that its business result was correct. Use expectations and the configured performance measures to evaluate the work.

Next steps​

  • Employees: prepare, test, and publish the employee before connecting your system

  • Routines: Scheduled and event-driven runs

  • Web Widget: The conversational front door for humans

  • API Reference: Full schemas for execute and executions