Agent-Skills.md

Agent Skills: Configure SDK Options

>-

UncategorizedID: speakeasy-api/agent-skills/configure-sdk-options

Repository

speakeasy-api/agent-skills
speakeasy-apiLicense: Apache-2.0
94

Install this agent skill to your local

pnpm dlx add-skill https://github.com/speakeasy-api/skills/tree/HEAD/skills/configure-sdk-options

Skill Files

Browse the full folder contents for configure-sdk-options.

Download Skill

Loading file tree…

skills/configure-sdk-options/SKILL.md

Skill Metadata

Name
configure-sdk-options
Description
>-

Configure SDK Options

Configure gen.yaml options for an existing Speakeasy SDK. Supports TypeScript, Python, Go, Java, C#, PHP, and Ruby.

For new SDK projects: Use start-new-sdk-project skill instead. This skill is for configuring an existing SDK.

Language-Specific Guides

For comprehensive configuration details, see the language-specific guides:

| Language | Guide | Key Features | |----------|-------|--------------| | TypeScript | content/languages/typescript.md | Zod validation, React Query, standalone functions, dual module format | | Python | content/languages/python.md | Pydantic models, async modes (both/split), uv/poetry support | | Go | content/languages/go.md | Response formats, interface generation, K8s integration | | Java | content/languages/java.md | Builder pattern, Gradle customization, Maven Central publishing | | C# | content/languages/csharp.md | Async/await, cancellation tokens, DI integration, NuGet | | PHP | content/languages/php.md | Laravel integration, Guzzle config, Packagist publishing | | Ruby | content/languages/ruby.md | Sorbet typing, Rails integration, RubyGems publishing |

These guides include detailed configuration options, code examples, framework integrations, and publishing instructions.

When to Use

  • Configuring language-specific gen.yaml options on an existing SDK
  • Setting up SDK hooks, async patterns, or publishing
  • Configuring runtime behavior (retries, timeouts, server selection) in application code
  • User says: "configure SDK", "gen.yaml options", "SDK config", "runtime override", "per-call config"
  • User asks about: Zod, Pydantic, NuGet, PyPI, npm, Maven Central, Packagist, RubyGems

Inputs

| Input | Required | Description | |-------|----------|-------------| | Existing SDK | Yes | SDK with .speakeasy/workflow.yaml already created | | Target language | Yes | TypeScript, Python, Go, Java, C#, PHP, or Ruby |

Outputs

| Output | Description | |--------|-------------| | Updated gen.yaml | Language-specific configuration | | Hook files | Custom hooks if enabled |

Prerequisites

You must have an existing SDK with .speakeasy/workflow.yaml. If not, run:

speakeasy quickstart --skip-interactive --output console \
  -s openapi.yaml -t <language> -n "MySDK" -p "<package-name>"

Common Configuration (All Languages)

These options apply to all SDK targets in gen.yaml:

<language>:
  version: 1.0.0
  packageName: "my-sdk"

  # Method signatures
  maxMethodParams: 4              # Params before request object
  flatteningOrder: parameters-first

  # Error handling
  responseFormat: flat            # or "envelope" (Go)
  clientServerStatusCodesAsErrors: true

TypeScript Configuration

typescript:
  version: 1.0.0
  packageName: "@myorg/my-sdk"
  moduleFormat: dual              # esm, commonjs, or dual
  zodVersion: v4-mini             # v3, v4, or v4-mini
  enableCustomCodeRegions: true   # For custom code
  enableReactQuery: true          # React Query hooks

| Feature | Notes | |---------|-------| | Zod validation | Automatic for all models | | Tree-shaking | Use moduleFormat: dual + standalone functions | | JSR publishing | Create jsr.json, run deno publish | | npm publishing | Standard npm publish |

Standalone functions for tree-shaking:

import { TodoCore } from "my-sdk/core.js";
import { todosCreate } from "my-sdk/funcs/todosCreate.js";
const sdk = new TodoCore({ apiKey: "..." });

Python Configuration

python:
  version: 1.0.0
  packageName: "my-sdk"
  asyncMode: both                 # both or split
  packageManager: uv              # uv or poetry
  envVarPrefix: ""                # Prefix for env config

| Feature | Notes | |---------|-------| | Pydantic models | Automatic for all models | | Async mode both | sdk.method() and sdk.method_async() | | Async mode split | SDK() and AsyncSDK() constructors | | PyPI publishing | uv publish or poetry publish |

Async patterns:

# asyncMode: both (default)
result = sdk.users.list()           # sync
result = await sdk.users.list_async() # async

# asyncMode: split
sdk = MySDK()                       # sync only
async_sdk = AsyncMySDK()            # async only

Go Configuration

go:
  version: 0.1.0
  packageName: github.com/myorg/my-sdk
  maxMethodParams: 2
  methodArguments: require-security-and-request
  responseFormat: envelope
  flattenGlobalSecurity: true

| Feature | Notes | |---------|-------| | Interfaces | Generate with ifacemaker | | Mocks | Generate with mockery | | K8s integration | Add kubebuilder markers, run controller-gen |

Interface generation for testing:

go install github.com/vburenin/ifacemaker@latest
go install github.com/vektra/mockery/v2@latest
ifacemaker --file consumers.go --struct Consumers --iface ConsumersSDK --output consumers_i.go
mockery

Java Configuration

java:
  version: 1.0.0
  groupID: com.myorg
  artifactID: my-sdk
  packageName: com.myorg.mysdk
  methodArguments: require-security-and-request

| Feature | Notes | |---------|-------| | Builder pattern | Automatic for all classes | | Build customization | Use build-extras.gradle (preserved) | | Maven Central | ./gradlew publishToSonatype closeAndReleaseSonatypeStagingRepository |

Client usage:

MySdk sdk = MySdk.builder()
    .security(Security.builder().apiKey("key").build())
    .build();

C# Configuration

csharp:
  version: 1.0.0
  packageName: MyOrg.MySDK
  dotnetVersion: "6.0"
  baseErrorName: MySDKException

| Feature | Notes | |---------|-------| | Async/await | All operations async by default | | SSE streaming | EventStream<T> support | | NuGet publishing | dotnet pack -c Release && dotnet nuget push |

Async with cancellation:

var cts = new CancellationTokenSource(TimeSpan.FromSeconds(30));
var result = await sdk.Users.ListAsync(cancellationToken: cts.Token);

PHP Configuration

php:
  version: 1.0.0
  packageName: myorg/my-sdk
  namespace: MyOrg\MySDK

| Feature | Notes | |---------|-------| | PHP 8.2+ | Required minimum version | | Guzzle | HTTP client (configurable timeout) | | Packagist | Tag release, register on Packagist.org |

Security callback for token refresh:

$sdk = MySDK\MySDK::builder()
    ->setSecuritySource(fn() => getTokenFromCache() ?? refreshToken())
    ->build();

Ruby Configuration

ruby:
  version: 1.0.0
  packageName: my-sdk
  module: MySdk
  typingStrategy: sorbet          # sorbet or none

| Feature | Notes | |---------|-------| | Sorbet typing | Optional, enable with typingStrategy: sorbet | | Faraday | HTTP client | | RubyGems | gem build && gem push |

SDK Hooks (All Languages)

Enable custom hooks with enableCustomCodeRegions: true. Hook files are preserved across regeneration.

| Language | Hook Location | |----------|---------------| | TypeScript | src/hooks/ | | Python | src/<pkg>/_hooks/ | | Go | internal/hooks/ | | Java | src/main/java/.../hooks/ | | C# | src/.../Hooks/ | | PHP | src/Hooks/ | | Ruby | lib/.../sdk_hooks/ |

See customize-sdk-hooks skill for detailed hook implementation.

Runtime Overrides

Runtime behavior can be configured at SDK instantiation or per-call. These override gen.yaml defaults.

Server Selection

Define server IDs in OpenAPI spec, then select at runtime:

# OpenAPI spec
servers:
  - url: https://api.example.com
    x-speakeasy-server-id: production
  - url: https://sandbox.example.com
    x-speakeasy-server-id: sandbox

| Language | SDK Constructor | Custom URL | |----------|-----------------|------------| | TypeScript | new SDK({ server: "sandbox" }) | new SDK({ serverURL: "..." }) | | Python | SDK(server="sandbox") | SDK(server_url="...") | | Go | SDK.New(SDK.WithServer("sandbox")) | SDK.WithServerURL("...") |

Retry Overrides

Override retry behavior per-call (spec defaults set via x-speakeasy-retries):

TypeScript:

const res = await sdk.payments.create({ amount: 1000 }, {
  retries: {
    strategy: "backoff",
    backoff: { initialInterval: 1000, maxInterval: 30000, maxElapsedTime: 120000, exponent: 2.0 },
    retryConnectionErrors: true,
  },
});

Python:

from sdk.utils import BackoffStrategy, RetryConfig
res = sdk.payments.create(amount=1000, retries=RetryConfig("backoff",
    backoff=BackoffStrategy(1000, 30000, 120000, 2.0), retry_connection_errors=True))

Go:

res, err := sdk.Payments.Create(ctx, req, operations.WithRetries(retry.Config{
    Strategy: "backoff", Backoff: &retry.BackoffStrategy{
        InitialInterval: 1000, MaxInterval: 30000, MaxElapsedTime: 120000, Exponent: 2.0},
    RetryConnectionErrors: true}))

Timeout Overrides

Set global timeout on SDK constructor, or per-call:

| Language | Global | Per-call | |----------|--------|----------| | TypeScript | new SDK({ timeoutMs: 30000 }) | sdk.op({}, { timeoutMs: 60000 }) | | Python | SDK(timeout_ms=30000) | sdk.op(timeout_ms=60000) | | Go | SDK.WithTimeoutMs(30000) | operations.WithTimeoutMs(60000) |

Pagination Usage

SDK auto-generates pagination helpers when x-speakeasy-pagination is set in spec:

// Auto-iterate all pages
for await (const user of await sdk.users.list({ limit: 50 })) {
  console.log(user.name);
}

// Manual pagination
let page = await sdk.users.list({ limit: 50 });
while (page) {
  for (const user of page.data) { console.log(user.name); }
  page = await page.next();
}

Decision Framework

| Situation | Action | |-----------|--------| | Need tree-shaking (TS) | Set moduleFormat: dual, use standalone functions | | Need async/sync (Python) | Set asyncMode: both (default) | | Need separate async client | Set asyncMode: split (Python) | | Need interfaces for testing (Go) | Use ifacemaker + mockery | | Need custom build config (Java) | Edit build-extras.gradle | | Need runtime retry override | Pass retries config in per-call options | | Need runtime timeout override | Set timeoutMs on constructor or per-call | | Need server switching | Use x-speakeasy-server-id in spec, select at runtime |

What NOT to Do

  • Do NOT use this skill for initial SDK generation - use start-new-sdk-project
  • Do NOT edit generated files outside custom code regions
  • Do NOT modify files in src/ that aren't in preserved directories (hooks, extra)

Troubleshooting

| Language | Issue | Solution | |----------|-------|----------| | TypeScript | Bundle too large | Use standalone functions | | Python | Async pagination blocking | Enable fixFlags.asyncPaginationSep2025: true | | Go | Interface not generated | Ensure struct is exported (capitalized) | | Java | Gradle sync fails | Run ./gradlew --refresh-dependencies | | C# | Async deadlock | Use await not .Result | | PHP | PHP version error | Requires PHP 8.2+ | | Ruby | Sorbet errors | Run bundle exec tapioca gems | | All | Retries not working | Ensure x-speakeasy-retries at document root or operation level | | All | Server ID not recognized | Add x-speakeasy-server-id to each server entry | | All | Pagination next() undefined | Add x-speakeasy-pagination to the list operation |

After Making Changes

After modifying gen.yaml configuration, prompt the user to regenerate the SDK:

Configuration complete. Would you like to regenerate the SDK now with speakeasy run?

If the user confirms, run:

speakeasy run --output console

Changes to gen.yaml only take effect after regeneration.

Related Skills

  • start-new-sdk-project - Initial SDK generation
  • customize-sdk-hooks - Detailed hook implementation
  • manage-openapi-overlays - Spec customization