Skip to main content

Temporal Integration

Connect Temporal to enable the AI agent to monitor and interact with your workflow orchestration platform during investigations.

Capabilities​

Once connected, the AI agent can:

CapabilityDescription
Test ConnectionVerify connectivity and cluster health
Describe WorkflowsGet detailed workflow execution information
List WorkflowsView workflows in your namespace
Monitor Task QueuesCheck task queue status and throughput
View SchedulesAccess scheduled workflow information

Prerequisites​

  • A Temporal cluster (Temporal Cloud or self-hosted)
  • Temporal server address and port
  • Namespace access
  • API key or mTLS certificates for authentication

Setup​

1
Gather Temporal Credentials

Depending on your setup, collect:

For Temporal Cloud:

  • Cluster address (e.g., namespace.account.tmprl.cloud:7233)
  • Namespace name
  • API key from Temporal Cloud console

For Self-Hosted with mTLS:

  • Cluster address (e.g., temporal.yourcompany.com:7233)
  • Namespace name
  • Client certificate (PEM format)
  • Client key (PEM format)
  • Server CA certificate (PEM format)
2
Add Integration in Autoheal
  1. Go to Integrations in Autoheal
  2. Click Temporal
  3. Enter a name (e.g., "Production Temporal Cluster")
3
Configure Connection

Enter the following:

  • Host: Your Temporal server address with port (e.g., temporal.example.com:7233)
  • Namespace: The namespace to connect to (typically default or your custom namespace)
  • API Key: Your authentication token (for Temporal Cloud or API-key authenticated clusters)

Optional - For mTLS:

  • Client Certificate: Paste your PEM-encoded client certificate
  • Client Key: Paste your PEM-encoded private key
  • Server CA: Paste your PEM-encoded CA certificate
4
Test and Save

Click Test Connection to verify connectivity, then Save.

Authentication Methods​

API Key Authentication​

Used for Temporal Cloud and self-hosted clusters with API key authentication enabled.

  • When to use: Temporal Cloud or clusters configured with API key auth
  • Required fields: Host, Namespace, API Key

mTLS Authentication​

Used for self-hosted Temporal clusters with mutual TLS authentication.

  • When to use: Self-hosted clusters requiring client certificates
  • Required fields: Host, Namespace, Client Certificate, Client Key, Server CA
tip

For production environments, mTLS is recommended for enhanced security. Contact your platform team for the required certificates.

Temporal Cloud Configuration​

For Temporal Cloud:

  1. The host format is: {namespace}.{accountId}.tmprl.cloud:7233
  2. Find your account ID in the Temporal Cloud console
  3. Generate an API key in Settings → API Keys
  4. Use your namespace name (visible in the Temporal Cloud console)

Context Learning​

After connecting, complete the Context Form to help the AI agent understand your Temporal environment:

  • Namespaces: List your namespaces and their purposes (prod, staging, dev)
  • Workflow Types: Document common workflows and what they do
  • Task Queues: Identify task queues and their workers
  • Search Attributes: Document custom search attributes you use

This context enables the agent to provide more intelligent assistance when investigating issues.

Example Queries​

Once connected, you can ask the AI agent questions like:

Check the health of our Temporal cluster
Show me the status of workflow ID payment-workflow-123
Are there any stuck workflows in the production namespace?
What's the status of the user-onboarding task queue?

Required Permissions​

Ensure your authentication credentials have these permissions:

PermissionWhy It's Needed
Namespace readAccess namespace information
Workflow readView workflow executions
Task queue readMonitor task queue status
Schedule readAccess scheduled workflows
warning

For security, create dedicated credentials for Autoheal with read-only permissions. Avoid using admin credentials.

Security Best Practices​

  1. Use dedicated credentials: Create a separate API key or certificate pair for Autoheal
  2. Limit namespace access: Restrict access to only the namespaces needed for monitoring
  3. Rotate credentials regularly: Update API keys and certificates on a regular schedule
  4. Use mTLS in production: For self-hosted clusters, prefer mTLS over API key authentication

Troubleshooting​

Connection Refused
  • Verify the host address and port are correct
  • Check that your Temporal cluster is accessible from Autoheal
  • For Temporal Cloud, ensure you're using the full cluster address with .tmprl.cloud
  • Verify network connectivity and firewall rules
Authentication Failed
  • Verify your API key is correct and not expired
  • For mTLS, check that all certificates are in PEM format
  • Ensure the client certificate is not expired
  • Verify the namespace exists and you have access
Certificate Errors
  • Ensure certificates are in PEM format (start with -----BEGIN CERTIFICATE-----)
  • Check that the client key matches the client certificate
  • Verify the Server CA certificate is the root CA that signed the server certificate
  • Make sure there are no extra spaces or newlines in the certificate fields
Namespace Not Found
  • Verify the namespace name is correct (case-sensitive)
  • Check that the namespace exists in your Temporal cluster
  • For Temporal Cloud, use the namespace name shown in the console, not the cluster address

Additional Resources​