GovDash
Menu

Run agents

In this example you'll create an agent, start a run, read its result, and cancel a run you no longer need. It builds on the Quickstart, so set GOVDASH_API_URL, GOVDASH_API_KEY, and GOVDASH_API_VERSION the same way.

You need:

  • A service account whose role has the agent permissions for what you'll do. The API checks the role on every call, so a missing permission returns 403 forbidden.
  • The id of a team member to run the agent as. The run acts as that member, and the member must meet the same rules as in GovDash.

1. Create an agent

Send POST /v1/agents. name, goal_prompt, visibility, run_as_user_id, and tool_bundles are required.

FieldWhat it does
goal_promptThe instructions the agent follows on every run.
visibilityPERSONAL keeps the agent to its owner. TEAM shares it with your team.
run_as_user_idThe team member the agent acts as.
tool_bundlesThe groups of GovDash tools the agent may use, such as CAPTURE or PROPOSAL. The API reference lists every value.
triggersWhat starts the agent. MANUAL is for runs you start through the API. SCHEDULE runs on a cron schedule and needs cron_expression and timezone. Other types start the agent when something happens in GovDash, such as OPPORTUNITY_CREATED.

Set RUN_AS_USER_ID to the id of the team member the agent should act as. This example creates an agent you can run manually:

curlcurl
curl "$GOVDASH_API_URL/v1/agents" \
  -X POST \
  -H "Authorization: Bearer $GOVDASH_API_KEY" \
  -H "govdash-version: $GOVDASH_API_VERSION" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pipeline summary",
    "goal_prompt": "Summarize our pipeline changes.",
    "visibility": "TEAM",
    "run_as_user_id": "'"$RUN_AS_USER_ID"'",
    "tool_bundles": ["CAPTURE"],
    "triggers": [{"type": "MANUAL", "enabled": true}]
  }'
TypeScriptTypeScript
const apiVersion = process.env.GOVDASH_API_VERSION
if (!apiVersion) throw new Error("Set GOVDASH_API_VERSION")

const response = await fetch(`${process.env.GOVDASH_API_URL}/v1/agents`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.GOVDASH_API_KEY}`,
    "govdash-version": apiVersion,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Pipeline summary",
    goal_prompt: "Summarize our pipeline changes.",
    visibility: "TEAM",
    run_as_user_id: process.env.RUN_AS_USER_ID,
    tool_bundles: ["CAPTURE"],
    triggers: [{ type: "MANUAL", enabled: true }],
  }),
})
if (!response.ok) throw new Error(await response.text())
const agent = await response.json()
console.log(agent.id)
PythonPython
import os

import requests

response = requests.post(
    os.environ["GOVDASH_API_URL"] + "/v1/agents",
    headers={
        "Authorization": "Bearer " + os.environ["GOVDASH_API_KEY"],
        "govdash-version": os.environ["GOVDASH_API_VERSION"],
    },
    json={
        "name": "Pipeline summary",
        "goal_prompt": "Summarize our pipeline changes.",
        "visibility": "TEAM",
        "run_as_user_id": os.environ["RUN_AS_USER_ID"],
        "tool_bundles": ["CAPTURE"],
        "triggers": [{"type": "MANUAL", "enabled": True}],
    },
)
response.raise_for_status()
print(response.json()["id"])

A 201 returns the agent, including its id. You can start a run of any agent through the API, whatever its triggers are.

Change an agent with PATCH /v1/agents/{id}. Omitted fields keep their values, with one exception: an update replaces the entire triggers set. Sending {"triggers":[]} removes every trigger and its schedule.

Warning

Deleting an agent with DELETE /v1/agents/{id} cancels its active runs, deletes its run history, and removes its schedules. You can't undo it. To stop an agent without losing its history, PATCH it with {"enabled": false}.

2. Start a run

Send POST /v1/agents/{id}/runs with {} to start a manual run. To point the run at a record, pass its id in input: opportunity_id, proposal_id, document_id, or award_id.

Save the agent's id as AGENT_ID. Create an IDEMPOTENCY_KEY once for the run, for example with export IDEMPOTENCY_KEY="$(uuidgen)", and reuse it for any retries.

curlcurl
curl "$GOVDASH_API_URL/v1/agents/$AGENT_ID/runs" \
  -X POST \
  -H "Authorization: Bearer $GOVDASH_API_KEY" \
  -H "govdash-version: $GOVDASH_API_VERSION" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
TypeScriptTypeScript
const apiVersion = process.env.GOVDASH_API_VERSION
if (!apiVersion) throw new Error("Set GOVDASH_API_VERSION")

const idempotencyKey = process.env.IDEMPOTENCY_KEY
if (!idempotencyKey) throw new Error("Set IDEMPOTENCY_KEY once per run")

const response = await fetch(
  `${process.env.GOVDASH_API_URL}/v1/agents/${process.env.AGENT_ID}/runs`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.GOVDASH_API_KEY}`,
      "govdash-version": apiVersion,
      "Idempotency-Key": idempotencyKey,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({}),
  },
)
if (!response.ok) throw new Error(await response.text())
console.log(await response.json())
PythonPython
import os

import requests

response = requests.post(
    f"{os.environ['GOVDASH_API_URL']}/v1/agents/{os.environ['AGENT_ID']}/runs",
    headers={
        "Authorization": "Bearer " + os.environ["GOVDASH_API_KEY"],
        "govdash-version": os.environ["GOVDASH_API_VERSION"],
        "Idempotency-Key": os.environ["IDEMPOTENCY_KEY"],
    },
    json={},
)
response.raise_for_status()
print(response.json())

The response is 202 Accepted with an agent_run object. The run hasn't finished yet. Its status is QUEUED or RUNNING, and its id identifies the run.

Two refusals are specific to starting a run:

  • 402 quota_exceeded means the team is out of agent credits. Retrying won't help until credits are added.
  • 403 forbidden means the service account's role can't run agents.

Warning

Starting a run consumes credits. Send an Idempotency-Key header with a unique value, and reuse it if the request times out. A retry with the same key returns the original run once its creation has completed. An unresolved attempt can return 409; check recent runs before trying a new key. See Retry safely.

3. Read the run

Send GET /v1/agent-runs/{id} to read a run's status and result.

curlcurl
curl "$GOVDASH_API_URL/v1/agent-runs/$RUN_ID" \
  -H "Authorization: Bearer $GOVDASH_API_KEY" \
  -H "govdash-version: $GOVDASH_API_VERSION"
TypeScriptTypeScript
const apiVersion = process.env.GOVDASH_API_VERSION
if (!apiVersion) throw new Error("Set GOVDASH_API_VERSION")

const response = await fetch(
  `${process.env.GOVDASH_API_URL}/v1/agent-runs/${process.env.RUN_ID}`,
  {
    headers: {
      Authorization: `Bearer ${process.env.GOVDASH_API_KEY}`,
      "govdash-version": apiVersion,
    },
  },
)
if (!response.ok) throw new Error(await response.text())
console.log(await response.json())
PythonPython
import os

import requests

response = requests.get(
    f"{os.environ['GOVDASH_API_URL']}/v1/agent-runs/{os.environ['RUN_ID']}",
    headers={
        "Authorization": "Bearer " + os.environ["GOVDASH_API_KEY"],
        "govdash-version": os.environ["GOVDASH_API_VERSION"],
    },
)
response.raise_for_status()
print(response.json())

Runs can take minutes. Poll periodically until the run reaches a terminal status; avoid polling continuously. We are rebuilding webhooks and hope to publish the updated API by the end of 2026.

StatusMeaning
QUEUEDAccepted and waiting to start.
RUNNINGIn progress.
SUCCEEDEDFinished. The answer is in result_message.
FAILEDStopped with an error. The reason is in failure_reason.
ACTION_REQUIREDStopped because it needs a person to act in GovDash. failure_reason says what.
REFUSEDGovDash declined to run it.
CANCELEDStopped by a cancel request.
TIMED_OUTRan past its time limit.
SYSTEM_TERMINATEDStopped by GovDash rather than by a cancel request.

A run in ACTION_REQUIRED can still become SUCCEEDED once someone resolves it in GovDash.

If a run's thread is classified above what your key can read, the response keeps the run's metadata and classification but leaves out result_message, failure_reason, and input. See Classification.

Add expand[]=credits to include credits_used. It's null until a finished run has ledger entries.

4. Cancel a run

Send POST /v1/agent-runs/{id}/cancel to stop a run you no longer need. The response is the run, with its latest status.

curlcurl
curl "$GOVDASH_API_URL/v1/agent-runs/$RUN_ID/cancel" \
  -X POST \
  -H "Authorization: Bearer $GOVDASH_API_KEY" \
  -H "govdash-version: $GOVDASH_API_VERSION"
TypeScriptTypeScript
const apiVersion = process.env.GOVDASH_API_VERSION
if (!apiVersion) throw new Error("Set GOVDASH_API_VERSION")

const response = await fetch(
  `${process.env.GOVDASH_API_URL}/v1/agent-runs/${process.env.RUN_ID}/cancel`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.GOVDASH_API_KEY}`,
      "govdash-version": apiVersion,
    },
  },
)
if (!response.ok) throw new Error(await response.text())
console.log(await response.json())
PythonPython
import os

import requests

response = requests.post(
    f"{os.environ['GOVDASH_API_URL']}/v1/agent-runs/{os.environ['RUN_ID']}/cancel",
    headers={
        "Authorization": "Bearer " + os.environ["GOVDASH_API_KEY"],
        "govdash-version": os.environ["GOVDASH_API_VERSION"],
    },
)
response.raise_for_status()
print(response.json())

List runs

GET /v1/agent-runs lists your team's runs, most recently started first. It pages like the other list endpoints. See Pagination.