> ## Documentation Index
> Fetch the complete documentation index at: https://docs.checkfu.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Base URL: https://api.checkfu.com. Current wire version: `2026-08-31` (`Checkfu-Version: 2026-08-31`).
> Mutating HTTP requests require `Authorization: Bearer $CHECKFU_API_KEY`, `Checkfu-Version: 2026-08-31`, `Content-Type: application/json`, and `Idempotency-Key` on retriable writes. Ordinary API keys are Workspace-bound; do not send a Workspace selector header.
> Core workflow: create an Agent (`POST /v1/agents`) and Environment (`POST /v1/environments`), grant `use_environment` (`POST /v1/permission-assignments`), create a Session (`POST /v1/sessions`), send events (`POST /v1/sessions/{id}/events`), stream progress (`GET /v1/sessions/{id}/events/stream`), and read the input result (`GET /v1/sessions/{id}/inputs/{input_id}/result`).
> Domain model: an Agent is mutable configuration; a Session freezes its AgentVersion and Environment at creation and owns its private workspace and ordered event history. Vault stores secret credentials; Connection links an external account; ActionApproval records human approval before an action runs.
> Capability status combines `audience`, `stability`, `availability`, evaluated prerequisites, and release evidence; check https://docs.checkfu.com/getting-started/status (`GET /v1/support/capabilities`) for live `available` status.

# Triage worthwhile issues

> When a GitHub issue opens, a model decides whether it is worth a maintainer's time, and if Yes the Triage Agent handles it.

This recipe keeps an Agent from spending time on every new issue. A connected GitHub account starts the run when an issue opens, a Model block answers Yes or No to "Is this issue worth a maintainer's time?", and only Yes reaches the Triage Agent. A No ends the run.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
opened (GitHub issues.opened) → worth_it (Yes/No) → yes → triage (Triage Agent)
                                                  → no  → ends
```

> [!WARNING]
>
> The Checkfu CLI and TypeScript SDK are private-alpha artifacts with no self-service public installation channel.
> Part of this flow is behind a rollout fence; a deployment that has not enabled it refuses the request rather than running it.
> Confirm [capability status](https://docs.checkfu.com/getting-started/status.md) before making availability part of your application's contract.

## Before you start

You need:

* An API key with the `admin` or `root` role in `CHECKFU_API_KEY`.
* A service account for the Automation to run as (`RUNS_AS`) and the person who authors it (`AUTHOR`). An API key is not a person, so a create through an API key names the author.
* A [connected GitHub account](https://docs.checkfu.com/guides/connect-a-providers-account.md) (`GITHUB_ACCOUNT`, a `conn_…`).
* The Triage [Agent](https://docs.checkfu.com/concepts/agents.md) (`TRIAGE_AGENT`) and the [Environment](https://docs.checkfu.com/concepts/work-environments.md) it runs in (`ENVIRONMENT`). When the Workspace has exactly one, delete the `environment_id` line and leave out `ENVIRONMENT`.
* A model routing profile with the key `fast-judge`, or change `route.profile` to one you have.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export RUNS_AS=prin_0123456789abcdef0123456789abcdef
export AUTHOR=prin_fedcba9876543210fedcba9876543210
export GITHUB_ACCOUNT=conn_0123456789abcdef0123456789abcdef
export TRIAGE_AGENT=agent_0123456789abcdef0123456789abcdef
export ENVIRONMENT=env_0123456789abcdef0123456789abcdef
```

The CLI examples use [CLI access](https://docs.checkfu.com/getting-started/cli-access.md) and the TypeScript examples use the [TypeScript SDK](https://docs.checkfu.com/reference/typescript-sdk.md).

## 1. Create the draft

Save the recipe as `proactivity.yaml`. It is the published [`proactivity.yaml`](https://docs.checkfu.com/automation-recipes/proactivity.yaml) with `created_by_principal_id` added:

```yaml proactivity.yaml theme={"theme":{"light":"github-light","dark":"github-dark"}}
# yaml-language-server: $schema=https://docs.checkfu.com/openapi.json#/components/schemas/CreateBlockAutomation
name: Triage worthwhile issues
runs_as: "${RUNS_AS}"
environment_id: "${ENVIRONMENT}"
created_by_principal_id: "${AUTHOR}"
blocks:
  - id: opened
    type: trigger
    trigger: { type: app_event, connection_id: "${GITHUB_ACCOUNT}", event: issues.opened }
  - id: worth_it
    type: model
    route: { profile: fast-judge }
    prompt: "Is this issue worth a maintainer's time? {{opened.issue.title}} {{opened.issue.body}}"
    format: { type: yes_no }
  - id: triage
    type: agent
    agent: "${TRIAGE_AGENT}"
    prompt: "Triage {{opened.issue.html_url}}. Why it matters: {{worth_it.reason}}"
wires:
  - { from: opened, to: worth_it }
  - { from: worth_it, port: "yes", to: triage }
```

```bash CLI theme={"theme":{"light":"github-light","dark":"github-dark"}}
checkfu automations create -f proactivity.yaml --var RUNS_AS=$RUNS_AS --var AUTHOR=$AUTHOR \
  --var GITHUB_ACCOUNT=$GITHUB_ACCOUNT --var TRIAGE_AGENT=$TRIAGE_AGENT --var ENVIRONMENT=$ENVIRONMENT
```

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST https://api.checkfu.com/v1/automations \
  --header "Authorization: Bearer $CHECKFU_API_KEY" \
  --header "Checkfu-Version: 2026-08-31" \
  --header "Idempotency-Key: $(uuidgen)" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Triage worthwhile issues",
    "runs_as": "'"$RUNS_AS"'",
    "created_by_principal_id": "'"$AUTHOR"'",
    "environment_id": "'"$ENVIRONMENT"'",
    "blocks": [
      {
        "id": "opened",
        "type": "trigger",
        "trigger": { "type": "app_event", "connection_id": "'"$GITHUB_ACCOUNT"'", "event": "issues.opened" }
      },
      {
        "id": "worth_it",
        "type": "model",
        "route": { "profile": "fast-judge" },
        "prompt": "Is this issue worth a maintainer\u0027s time? {{opened.issue.title}} {{opened.issue.body}}",
        "format": { "type": "yes_no" }
      },
      {
        "id": "triage",
        "type": "agent",
        "agent": "'"$TRIAGE_AGENT"'",
        "prompt": "Triage {{opened.issue.html_url}}. Why it matters: {{worth_it.reason}}"
      }
    ],
    "wires": [
      { "from": "opened", "to": "worth_it" },
      { "from": "worth_it", "port": "yes", "to": "triage" }
    ]
  }'
```

```ts TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { Checkfu, recipes } from "@checkfu/sdk"

const checkfu = new Checkfu({ apiKey: process.env.CHECKFU_API_KEY })

const document = recipes.proactivity({
  runsAs: process.env.RUNS_AS!,
  environmentId: process.env.ENVIRONMENT,
  account: process.env.GITHUB_ACCOUNT!,
  route: { profile: "fast-judge" },
  agent: process.env.TRIAGE_AGENT!,
})

const automation = await checkfu.automations.create(
  {
    ...document,
    created_by_principal_id: process.env.AUTHOR,
  },
  { idempotencyKey: crypto.randomUUID() },
)
```

Keep the `auto_…` id it returns in `AUTOMATION`.

## 2. Grant what it needs

The service account needs `use_connection` on the GitHub account, `act_as` on the Triage Agent and `use_model` on the route. `GET /v1/automations/{id}/access` lists each one with its `status`:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://api.checkfu.com/v1/automations/$AUTOMATION/access \
  --header "Authorization: Bearer $CHECKFU_API_KEY" \
  --header "Checkfu-Version: 2026-08-31"
```

Grant a missing one with a [PermissionAssignment](https://docs.checkfu.com/concepts/tenancy-and-governance.md):

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST https://api.checkfu.com/v1/permission-assignments \
  --header "Authorization: Bearer $CHECKFU_API_KEY" \
  --header "Checkfu-Version: 2026-08-31" \
  --header "Idempotency-Key: $(uuidgen)" \
  --header "Content-Type: application/json" \
  --data '{
    "subject": { "type": "principal", "id": "'"$RUNS_AS"'" },
    "resource": { "type": "connection", "id": "'"$GITHUB_ACCOUNT"'" },
    "permission": "use_connection"
  }'
```

A grant that already exists answers `409`.

## 3. Test with a sample issue

The sample event has the shape GitHub sends, so `{{opened.issue.title}}` and the other references resolve.

```bash CLI theme={"theme":{"light":"github-light","dark":"github-dark"}}
checkfu automations test $AUTOMATION \
  --event '{"issue":{"title":"Login fails after upgrade","body":"Every sign-in returns 500 since v2.","html_url":"https://github.com/acme/api/issues/42"}}'
```

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST https://api.checkfu.com/v1/automations/$AUTOMATION/test \
  --header "Authorization: Bearer $CHECKFU_API_KEY" \
  --header "Checkfu-Version: 2026-08-31" \
  --header "Content-Type: application/json" \
  --data '{
    "event": {
      "issue": {
        "title": "Login fails after upgrade",
        "body": "Every sign-in returns 500 since v2.",
        "html_url": "https://github.com/acme/api/issues/42"
      }
    }
  }'
```

```ts TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const test = await checkfu.automations.test(automation.id, {
  event: {
    issue: {
      title: "Login fails after upgrade",
      body: "Every sign-in returns 500 since v2.",
      html_url: "https://github.com/acme/api/issues/42",
    },
  },
})
```

Starting from an app's events needs a deployment that registers provider triggers. Where it does not, test and publish refuse with `automation.draft_has_problems` and the problem "Starting from an app's events is not available here". Check [capability status](https://docs.checkfu.com/getting-started/status.md), or start the same blocks from a `webhook` trigger meanwhile.

## 4. Publish and watch

```bash CLI theme={"theme":{"light":"github-light","dark":"github-dark"}}
checkfu automations publish $AUTOMATION
```

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST https://api.checkfu.com/v1/automations/$AUTOMATION/publish \
  --header "Authorization: Bearer $CHECKFU_API_KEY" \
  --header "Checkfu-Version: 2026-08-31" \
  --header "Content-Type: application/json" \
  --data '{}'
```

```ts TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const publication = await checkfu.automations.publish(automation.id, {})
```

List the runs and their status:

```bash CLI theme={"theme":{"light":"github-light","dark":"github-dark"}}
checkfu automations runs $AUTOMATION --limit 5
```

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://api.checkfu.com/v1/automation-runs?automation_id=$AUTOMATION&limit=5" \
  --header "Authorization: Bearer $CHECKFU_API_KEY" \
  --header "Checkfu-Version: 2026-08-31"
```

```ts TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const runs = await checkfu.automationRuns.list({ automation_id: automation.id, limit: 5 })
```

The publish summary names what it listens for. Each new issue starts a run; a No answer ends it on `worth_it`, and Yes starts a Triage Session. Pause and resume with `checkfu automations pause` and `checkfu automations resume`.

See [Automations](https://docs.checkfu.com/concepts/automations.md) for every block and field, and [Trigger Automations from providers](https://docs.checkfu.com/guides/trigger-agents-from-providers.md) for how provider events are delivered.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.