Skip to main content
Tracecat makes it easy to turn your Python scripts into actions for agents and workflows. All you need is:
  • A single Python decorator, @registry.register
  • from typing import Annotated
  • from typing_extensions import Doc

Quick start

  1. Add a Python file to your custom registry package.
  2. Register one async function with @registry.register(...).
  3. Define typed inputs, read secrets with secrets.get(...), and return JSON-serializable data.

What to define

  • Use tools.<integration> for the namespace.
  • Set default_title, description, display_group, doc_url, and namespace in @registry.register(...).
  • Define action inputs with type hints and Field(..., description=...).
  • Define required credentials with RegistrySecret(...) and pass them in secrets=[...].
  • Read secret values with secrets.get(...).
  • Return plain dicts, lists, strings, numbers, or booleans.

Declaring secret types

By default, secrets are custom (arbitrary key-value). If your action requires an SSH key, mTLS certificate, or CA certificate, set secret_type so the credentials UI renders the correct form.

Examples

secret_type uses snake_case everywhere — Python declarations, the API, and the UI all use the same values (ssh_key, ca_cert, mtls, custom). Use the same ${{ SECRETS... }} syntax as workflow actions. Custom secrets (API keys, SSH, mTLS, CA bundles, and so on):

OAuth

OAuth expressions use the provider’s exact ID, not its display name.
  • Built-in providers use stable lowercase IDs assigned by Tracecat, with underscores between words, such as slack, google_drive, and microsoft_sentinel.
  • Custom providers use an ID derived from the provider name, or from the requested ID when you create one through the API. Tracecat slugifies it with underscores and prepends custom_. My Security API becomes custom_my_security_api. If that ID is already used for the same grant type, Tracecat appends _1, _2, and so on.
Append _oauth to the exact provider ID for the secret name. For the key, uppercase the complete provider ID, preserve its underscores and any numeric suffix, then append _USER_TOKEN for authorization_code or _SERVICE_TOKEN for client_credentials.
A built-in google_drive authorization-code provider and a custom custom_my_security_api client-credentials provider resolve as:
When the provider has both grant types configured, you can fall back across both keys:
Validation checks both sides of a || independently, so this fallback only passes when the provider is configured for both authorization_code and client_credentials. If only one grant is set up, reference that grant’s key directly — otherwise the workflow fails validation on the missing one.
Tracecat refreshes expiring authorization-code tokens when the provider issued a refresh token, and reacquires client-credentials tokens with the stored client credentials. The expression resolves only to the current access-token string, which may be a JWT or an opaque token, not the refresh token.

Python UDFs

Declare credentials in @registry.register(..., secrets=[...]).
  • RegistrySecret: static keys; set secret_type to ssh_key, mtls, or ca_cert when needed (secret types). Optional: optional, optional_keys.
  • RegistryOAuthSecret: declares a dependency on an existing OAuth integration. Pass the provider_id and grant_type that match the integration in your workspace (a mismatch — for example declaring authorization_code when the integration uses client_credentials — will not resolve).
Read values with secrets.get("<KEY>") (key only, e.g. GOOGLE_DRIVE_USER_TOKEN), not a SECRETS. path.

YAML

Under definition, set a secrets list (same validator as Python). Custom (optional secret_type for structured secrets):
OAuth:
The provider_id and grant_type must match an integration already configured in your workspace. Use ${{ SECRETS.<provider_id>_oauth.<TOKEN_KEY> }} in args. Set optional: true on an OAuth entry when it is not always required.

Example providers

See integrations/google_api.py (google_oauth_secret, provider google, grant client_credentials) and integrations/slack_sdk.py for UDFs that use OAuth credentials. See tracecat_registry/core/ssh.py for an ssh_key secret example. For YAML templates, see microsoft_teams/send_message.yml (authorization_code), google_docs/create_document.yml (client_credentials), and microsoft_sentinel/.../get_alert_rule_template.yml (optional dual grant). See templates/tools/exa/search.yml for a simple API key template. For the full list of built-in provider IDs, see tracecat/integrations/providers/__init__.py.

Call Tracecat from a UDF

Import ctx from tracecat_registry to read and write Tracecat data, such as tables, cases, and variables, from inside a UDF. SDK calls use the workflow’s internal authenticated execution context, so you do not need an API key or a RegistrySecret. Use clients such as ctx.cases, ctx.tables, ctx.variables, and ctx.workflows. In an async def UDF, call the async variant under .aio, such as ctx.tables.aio. The synchronous clients raise an error inside async code.
You can also import a built-in Python action and call it like a regular function, for example from tracecat_registry.core.table import lookup. @registry.register returns the original function, so the call runs in the same process with the same context.

Private network access

Python UDFs can call hosts on a private or on-premises network through a tunnel. The tunnel reaches your action as the standard HTTP_PROXY and HTTPS_PROXY environment variables, which httpx, requests, and most SDKs read by default. Keep that default: do not set trust_env=False or open raw sockets, or the request bypasses the tunnel and fails.

Example actions

You can browse all open-source integrations in Tracecat in tools actions. Use template actions to see how actions are composed, and use core actions to inspect built-in implementations. For concrete examples, browse the Slack, AWS Boto3, and FalconPy integrations.