DOCSEARCHbyAlgolia
Submit Docs

Temporal Go SDK

repository·main·Indexed 21 days ago

https://github.com/temporalio/sdk-go

A framework for authoring scalable, durable, and resilient workflows and activities using the Go language. Includes contributions for AWS Lambda workers with OpenTelemetry support, an S3 Storage Driver for offloading large payloads via AWS SDK v2, Datadog tracing interceptors, and environment-based configuration via envconfig.

Tokens
42.1K
Snippets
130
Records
186
Agent score
74%

What's inside Temporal Go SDK

  1. Compose Google ADK with other Temporal plugins

    main

    The Google ADK integration is designed to compose easily with other Temporal SDK plugins.

    Temporal Worker Level:

    • The ADK plugin only registers Activities at worker start and closes cached MCP toolsets at worker stop.
    • It does not use interceptors or data converters.
    • This means you can add it to worker.Options.Plugins alongside other plugins (such as sdk-go/contrib/opentelemetry) without conflict.
    • To capture tracing, register your tracing interceptor on the worker as usual; ADK will emit its own OpenTelemetry spans.

    ADK Level:

    • To add other ADK-specific plugins, add them to runner.PluginConfig.Plugins following standard ADK patterns.

  3. How S3 key structures work in the S3 driver

    main

    The S3 driver uses content-addressable keys based on a SHA-256 hash of the serialized payload. Keys are segmented by Namespace and Workflow/Activity identifiers to prevent collisions and organize data.

    Key patterns include:

    • Workflow payload: v0/ns/<namespace>/wt/<workflow-type>/wi/<workflow-id>/ri/<run-id>/d/sha256/<hash>
    • Standalone Activity payload: v0/ns/<namespace>/at/<activity-type>/ai/<activity-id>/ri/<run-id>/d/sha256/<hash>
    • Unknown context (fallback): v0/d/sha256/<hash>

    Characters outside the S3 safe set (alphanumerics and !-_.*'()) are percent-encoded. Empty segments are replaced with null.

  5. Use sysinfo for worker heartbeats

    main

    If you need CPU and memory usage metrics for worker heartbeats but do not require a resource-based tuner, you can assign the sysinfo.SysInfoProvider() directly to worker.Options.SysInfoProvider.

    Note: If you are already using the provider for a tuner, reuse the same provider instance instead of creating a new one.

  7. How Google ADK agents work with Temporal

    main

    The Google ADK integration makes adk-go agents durable and replay-safe by running the agent's orchestration loop inside a Temporal Workflow.

    Key Concepts:

    • LLM Calls as Activities: Using googleadk.NewModel("<model-name>") turns LLM calls into durable Temporal Activities. The workflow only carries the model name; the actual model is reconstructed on the worker side using a ModelFactory.
    • Deterministic Tools: By default, tools run in-workflow. This means they must be deterministic and replay-safe (no direct network, clock, randomness, or goroutines).
    • I/O Tools as Activities: For tools that perform I/O (network, disk, etc.), you must opt them into Activities using googleadk.ActivityAsTool.
    • MCP Support: googleadk.NewMCPToolset provides a workflow-side proxy for Model Context Protocol (MCP) tools. The stateful toolset runs worker-side.
    • Determinism: googleadk.NewContext(workflowCtx) bridges the ADK platform seams (Time, UUID, Task Runner) to Temporal's deterministic providers.

  8. How Workflow Streams work

    main

    Workflow Streams provide a durable publish/subscribe log hosted inside a Temporal Workflow.

    Core Mechanics

    • Publishing: External code (activities, starters, or other workflows) publishes messages to named topics via signals.
    • Subscribing: Subscribers long-poll for new items via updates.
    • Offset Tracking: A query exposes the current offset.

    Key Characteristics

    • Durability: Backed by Temporal's durable execution, providing ordered, durable, and exactly-once delivery.
    • Performance: Each poll round-trip costs ~100 ms of latency; it is not intended for ultra-low-latency streaming.
    • Scalability: Well suited for event streams where cost scales with durable batches rather than individual message counts.
    • Interoperability: Uses a cross-language protocol compatible with Python and TypeScript packages.

  11. Understand Workflow Determinism Rules

    main

    The workflowcheck tool identifies non-deterministic code based on a default set of rules.

    Flagged Go Constructs

    • Starting a goroutine
    • Receiving from a channel
    • Sending to a channel
    • Iterating over a channel via range
    • Iterating over a map via range

    Flagged Functions and Variables

    • crypto/rand.Reader (Global crypto random reader)
    • math/rand.globalRand (Global pseudorandom)
    • os.Stderr, os.Stdin, os.Stdout (Standard I/O access)
    • time.Now (Current time)
    • time.Sleep (Sleeping)

    Limitations: The tool does not catch all cases, such as the mutation of global variables. Developers should still manually scrutinize Workflow code for other forms of non-determinism.

  12. Configure Prometheus-compatible metric names with Tally

    main
    If you require Prometheus-compatible metric names, you must wrap your Tally scope using NewPrometheusNamingScope and provide PrometheusSanitizeOptions. Refer to the package documentation for the full implementation details.