Agents and durable runs

Agents package a persona, model policy, optional knowledge, and tool grants. Use one-shot invocation for a single governed completion or create a durable run for multi-turn tool execution, approval, retry, and checkpointing.

Create an agent

curl -H "Authorization: Bearer $DEEPLINQ_API_KEY" \
  -H "X-End-User-Id: user-42" \
  -H "Content-Type: application/json" \
  -X POST "$BASE_URL/v1/agents" -d '{
  "owner_type":"user",
  "owner_id":"user-42",
  "name":"Mailbox triage",
  "description":"Find and summarize billing email.",
  "persona":"Be concise. Never send email without explicit approval.",
  "default_model":"gpt-5-mini",
  "allowed_models":["gpt-5-mini"],
  "temperature":0.2,
  "tools":[
    {"tool_name":"email.search","policy":"auto"},
    {"tool_name":"email.send","policy":"requires_approval"}
  ]
}'

Agents can belong to a user, team, or org. Creation and management authority follows that owner.

Tool policy is either:

• auto: the durable run may execute it;
• requires_approval: the run parks before execution.

Agents never store provider or connection credentials. Tools resolve from the invoking owner's current connections.

Attach knowledge or tools

Replace the attached dataset set:

PUT /v1/agents/{id}/datasets
{"dataset_ids":["<dataset-id>"]}

Attached datasets are caller-filtered at invocation time. The response reports attachments the caller cannot access rather than using agent ownership as a confused deputy.

Tool grants and datasets are mutually exclusive in the current one-shot retrieval design.

One-shot invocation

curl -H "Authorization: Bearer $DEEPLINQ_API_KEY" \
  -H "X-End-User-Id: user-42" \
  -H "Content-Type: application/json" \
  -X POST "$BASE_URL/v1/agents/$AGENT_ID/invoke" -d '{
  "message":"Find invoices received this week.",
  "model":"gpt-5-mini"
}'

One-shot invocation can return tool calls but does not execute requires_approval tools server-side. Use a durable run for managed execution.

Start a durable run

curl -H "Authorization: Bearer $DEEPLINQ_API_KEY" \
  -H "X-End-User-Id: user-42" \
  -H "Content-Type: application/json" \
  -X POST "$BASE_URL/v1/agents/$AGENT_ID/runs" -d '{
  "message":"Find the latest invoice and draft a reply asking for line-item detail.",
  "max_turns":8,
  "credit_budget":500000
}'

The response identifies an asynchronous run. Poll:

GET /v1/runs/{run_id}
GET /v1/runs?agent_id={agent_id}&status=running

Each turn holds a database-time lease, performs model or tool work, and commits a durable checkpoint. Restarts and replica changes do not discard committed progress.

Handle approval

When status is awaiting_approval, inspect the pending action in the owner-only run view, then:

curl -H "Authorization: Bearer $DEEPLINQ_API_KEY" \
  -H "X-End-User-Id: user-42" \
  -H "Content-Type: application/json" \
  -X POST "$BASE_URL/v1/runs/$RUN_ID/approve" \
  -d '{"note":"The draft is safe to send."}'

Or deny:

POST /v1/runs/{run_id}/deny
{"note":"Do not contact this recipient."}

Approval, state transition, and continuation-job creation commit atomically. Denial becomes a tool result so the model can adapt.

Bounds and cancellation

Every run is bounded by:

• maximum turns;
• an optional micro-USD credit budget;
• a wall-clock deadline;
• an approval timeout;
• a maximum tool-result size.

Cancel with:

POST /v1/runs/{run_id}/cancel

Cancellation stops after in-flight work completes. Explicit terminal reasons include budget, turn, timeout, guardrail, tool, and cancellation outcomes.

Events

Runs emit content-free events including run.started, run.approval_required, run.tool_unavailable, run.succeeded, and run.failed. The shared webhook delivery state machine can deliver them without placing prompts, tool arguments, or results in the event payload.