ucitra/ agent teams

Integrations

An integration gives agents tools for an outside service. The daemon makes every call on your credentials: no agent holds a token or key, and every call is on the run's page.

lucitra integration-add github             # uses your own gh login; stores no token
lucitra integration-add alpaca paper       # paper by default; `live` is its own install
lucitra integration-add market-data
lucitra integration-add research           # Finnhub, FRED and SEC EDGAR (SEC needs no key)
lucitra integration-add ntfy               # lets agents push to your verified ntfy channel
lucitra integrations                       # what is installed, which keys are set, who names which tools
lucitra integration-remove github          # takes its tools away from every agent

Who may call what

An agent calls a tool only where its access.yaml allows it, as integration:tool:

allow:
  tools:
    - github:*            # every GitHub tool except merge, approve and release
    - github:pr-merge     # those three only by name

Allowed tools run on their own unless a team policy lists them under gated:. A gated call waits for you in the Inbox. A gate can name an environment: alpaca:orders-create@live holds orders only while Alpaca is installed as live, so paper orders fill on their own.

Where keys come from

Keys stay where you already keep them. Agent Teams keeps no copy, and listing which keys are set reads no value.

lucitra secret-source-add keychain lucitra   # the macOS Keychain
lucitra secret-source-add 1password Lucitra  # a 1Password vault, through your own op sign-in
lucitra secret-source-add gcp my-project     # GCP Secret Manager, through your own gcloud login
lucitra secret-source-add aws work@us-east-1 # AWS Secrets Manager, through your own aws login (a profile, or just the region)
lucitra secret-source-add env ./.env.local   # or an env file; sources are tried in the order you add them
lucitra secret-sources

A key is looked up by its secret name. In the Keychain it is an item filed under the service you added, with the name as its account:

security add-generic-password -s lucitra -a alpaca-paper-api-key-id -w   # prompts for the value

In 1Password it is an item in the vault titled with the name, read from its credential field (an API Credential) or its password field. In GCP or AWS it is the secret's name. In an env file it is the same name in upper snake case, or the name the vendor's own docs use, so an existing .env works as it is:

SecretEnv fileAlso accepted
alpaca-paper-api-key-id / -secretALPACA_PAPER_API_KEY_ID / _SECRETAPCA_API_KEY_ID / APCA_API_SECRET_KEY, unless APCA_API_BASE_URL is live
alpaca-live-api-key-id / -secretALPACA_LIVE_API_KEY_ID / _SECRETthe APCA_* pair, only beside APCA_API_BASE_URL=https://api.alpaca.markets
market-data-finnhub-api-keyMARKET_DATA_FINNHUB_API_KEYFINNHUB_API_KEY
research-fred-api-keyRESEARCH_FRED_API_KEYFRED_API_KEY

integration-add says which keys no source holds yet.

When an integration stops working

lucitra integration-health           # each integration and key source: working or not, why, and the fix
lucitra integration-health refresh   # check again now rather than use the last two minutes' answer

Each installed integration is in one state: working, needs sign-in, key missing, source broken, failing (three calls in a row failed; a 401 or 403 reads as a rejected key) or unreachable. A key source is checked by asking gcloud, op or the Keychain about itself, never about a key, so a logged-out gcloud shows as one thing to fix rather than as every key it holds.

The app's Integrations screen shows the same, with each fix as a command to copy. A broken integration that a switched-on schedule depends on is also an Inbox item, with the run it will cost next; a run that stopped on one names it; and the desktop app's menu bar counts them and notifies when one breaks. An agent whose call keeps failing is told to stop retrying and hand it to you.

GitHub

Uses your own gh login. Reaches api.github.com and github.com.

ToolEffectWhat it does
github:pr-listreadList open pull requests in this repository
github:pr-readreadRead one pull request: title, body, state, review decision
github:pr-filesreadThe files a pull request changes, and its diff
github:issue-readreadRead one issue: title, body, state, labels
github:pr-commentwriteComment on a pull request
github:pr-createpushPush this worktree's branch and open a pull request from it
github:pr-approveirreversibleApprove a pull request
github:pr-mergeirreversibleSquash-merge a pull request
github:release-createirreversibleCreate a release from a tag

Alpaca

A brokerage account. Installs as paper or live, each with its own key pair. Reaches paper-api.alpaca.markets and api.alpaca.markets.

ToolEffectWhat it does
alpaca:portfolio-balancereadThe account: equity, cash, buying power
alpaca:portfolio-positionsreadEvery open position
alpaca:orders-listreadOpen orders
alpaca:fills-listreadRecent fills
alpaca:orders-cancelwriteCancel one open order
alpaca:orders-createirreversiblePlace an order
alpaca:orders-amendirreversibleChange an open order's quantity or limit price

Market data

Quotes from Finnhub; history from Alpaca's market data, on the paper keys unless Alpaca is installed live. Reaches finnhub.io and data.alpaca.markets.

ToolEffectWhat it does
market-data:quotereadThe latest quote for one ticker
market-data:batch-quotereadLatest quotes for several tickers
market-data:historyreadDaily bars for one ticker

Research

Finnhub, FRED and SEC EDGAR. SEC needs no key. Reaches finnhub.io, api.stlouisfed.org, data.sec.gov, www.sec.gov and data.alpaca.markets.

ToolEffectWhat it does
research:equity-quotereadThe latest quote for one ticker
research:equity-historyreadDaily bars for one ticker
research:fred-seriesreadObservations of one FRED series, such as DGS10 or CPIAUCSL
research:news-searchreadRecent company news for one ticker
research:sec-filingsreadRecent SEC filings for one ticker

ntfy

Lets an agent granted ntfy:notify push to your verified ntfy channels, at most 20 an hour per team. Never SMS or WhatsApp. Reaches ntfy.sh.

ToolEffectWhat it does
ntfy:notifywriteSend you a push notification, for news you would want now

Trading limits

Every order through a brokerage integration is held to limits that scale with the account, whatever the team: at most 2% of the account per order, and no new orders once the day's loss reaches 5%. Change them with lucitra trading-limits and lucitra trading-limit alpaca <key> <value|default|none>, or in the app under Settings → Trading limits, which can only tighten one.

A team's policy can add its own. The most conservative of yours and the policy's applies, on every environment, whether or not the order was gated:

limits:
  alpaca:
    max_order_pct: 1              # of the account's equity
    max_order_dollars: 500
    max_orders_per_day: 5
    daily_max_loss_dollars: 100
    symbols: [SPY, QQQ, AAPL]

An order whose size cannot be worked out, or an account whose size cannot be read, is refused while a cap needs it. A refusal is a row in the run's record, with the reason. A limit the policy does not write is not enforced.

Cookie settings

Choose what this site may store in your browser. You can change it any time from Cookie settings at the bottom of every page.

EssentialAlways on

Remembers the choice you make here. Nothing else is stored until you turn analytics on.

What is stored
NameWherePurposeKept
lucitra-consentLocal storageYour analytics choiceUntil you clear it
Analytics

Shows us which pages people read, what breaks, and which links bring people here, so we know what to fix. Off until you turn it on.

What is stored
NameWherePurposeKept
ph_<key>_posthogCookieA random identifier for your browser, and the current session1 year
ph_<key>_posthogLocal storageThe same identifier, as a backup to the cookieUntil you clear it
lucitra-last-touchSession storageThe link or campaign that started this visit, sent only with a contact form messageUntil you close the tab
lucitra-first-touchLocal storageThe link or campaign of your first visitUntil you clear it
lucitra-last-touchLocal storageThe link or campaign of your latest visitUntil you clear it
Cookie policy