Skip to content
ShareOut ShareOut Docs

Crew overview

import { Steps, Aside } from ‘@astrojs/starlight/components’;

Each artifact can run a crew — a server-side autonomous agent with tools to query data, refresh snapshots, write JSON summaries, deliver to Slack, and more. Crews are triggered on a schedule, by metric-alert follow-up (on_trigger), from the Telegram bot (ask_crew), or manually via the crew API.

Feature key: ai.crew (labeled CrewAI agents in the admin catalog).

When to use Crew

Section titled “When to use Crew”
You want…Use
Answer visitor questions in the pageAI chat agent (sdk.agent)
Run fixed SQL on a schedule (no LLM)Scheduled job → query_snapshot
Alert when a number crosses a thresholdMetric alerts
Summarize, investigate, or deliver in natural languageCrew
Ask a page’s crew from TelegramTelegram bot → ask_crew
Ask a page’s crew from SlackSlack bot → ask_crew

Jobs are deterministic — SQL and delivery config are fixed. Crew is agentic: it decides which tools to call and how to phrase output. Use Crew when the task needs judgment, narrative, or light follow-up queries.

How a run works

Section titled “How a run works”
flowchart LR
  T[Trigger] --> R[Run loop]
  R --> M[Model turn]
  M -->|tool calls| Tools[Granted tools]
  Tools --> M
  M -->|finish| Done[Summary + cost]
  1. A trigger or manual call starts a run.
  2. The model receives your instructions plus optional run input.
  3. Each iteration, the model may call granted tools (json_get, connection_query, notify_send, …).
  4. The run ends with a summary, iteration count, and cost (micro-USD). Sensitive writes may queue an owner approval first.

Stream live with sdk.crew.run() or replay from run history.

What starts a run

Section titled “What starts a run”
SourceHow
Cron triggersdk.crew.triggers.create({ kind: 'cron', cron: '…' })
Condition triggerTable row count crosses a predicate
Event triggere.g. table.row.inserted
Metric alerton_trigger.crew: true on an alert rule
TelegramOwner/editor confirms ask_crew via @ShareOutAI_bot
Manualsdk.crew.run({ input: '…' }) or REST POST …/crew/run

Prerequisites

Section titled “Prerequisites”
  1. ai.crew enabled — GET /v1/features?artifact_id=…. Off → 403 FEATURE_DISABLED.
  2. Artifact owner session or API token.
  3. For delivery tools, destination flags (dest.slack, dest.email, …) must be on.

Quick start

Section titled “Quick start”

  1. Define — instructions, model, tool grants (once per artifact).

    const sdk = await ShareOut.create();
    

    await sdk.crew.define({
      name: 'Weekly reviewer',
      instructions: 'Read sales, flag revenue < 0, write a summary to json key "weekly_review".',
      model: 'claude-sonnet-4-20250514',
      tools: { read: ['table_query'], write: ['json_set'] },
    });

  2. Run — test before scheduling.

    for await (const event of sdk.crew.run({ input: 'Run now.' })) {
      if (event.type === 'finish') console.log(event.summary);
    }

  3. Schedule (optional).

    await sdk.crew.triggers.create({ kind: 'cron', cron: '0 9 * * 1' });

Permissions and identity

Section titled “Permissions and identity”
  • Crew tools run with owner identity for data writes and warehouse queries.
  • Write tools may require owner approval when the artifact is public (whenPublic) or always (notify_send by default policy).
  • Per-user connectors work for crew warehouse queries — same as the interactive data API.
  • The HTML page cannot widen tool grants at runtime; only what you stored in define() is exposed to the model.

Limits and billing

Section titled “Limits and billing”
ControlWhat it does
maxIterationsCap tool loops per run
runBudgetMicroUsdOptional per-run spend cap
Workspace AI balanceRuns halt when credits are exhausted
Concurrent runsCapped server-side per artifact

Check usage: sdk.crew.usage(workspaceId).

What’s next

Section titled “What’s next”