What Is Runtime Discovery for AWS Agent Toolkit Skills?

Runtime discovery is the dynamic process by which AWS Agent Toolkit skills query live AWS APIs during execution to discover resource topology, endpoints, and schemas rather than relying on static configuration.

In the aws/agent-toolkit-for-aws repository, runtime discovery serves as the foundation for safe, context-aware automation. Every skill that interacts with mutable AWS services implements this pattern to obtain up-to-date metadata about the environment it operates within.

The Runtime Discovery Process

Runtime discovery operates through a standardized lifecycle that transforms raw AWS API responses into structured contracts. This ensures skills always work with current resource states rather than stale, hard-coded values.

Start-up Discovery

When a skill instance initializes—particularly within Lambda MicroVM architectures—it must immediately register with the discovery service. According to the lifecycle model defined in skills/specialized-skills/serverless-skills/aws-lambda-microvms/references/lifecycle-model.md, the /run endpoint performs a fast "register with discovery" operation to obtain per-VM state including secrets and endpoint information. This registration must complete quickly to maintain cold-start performance while establishing the security context for subsequent operations.

Resource Discovery

Skills query AWS APIs using describe-* and list-* operations to enumerate actual resources present in the target account and region. Specific implementations vary by service:

• Amazon ElastiCache skills execute cluster slots and cluster shards commands to map topology before establishing connections, as documented in skills/specialized-skills/database-skills/amazon-elasticache/references/setup/connection-guide.md.
• Data lake ingestion skills launch temporary AWS Glue crawlers to capture JDBC schemas dynamically, then retrieve table metadata via aws glue get-tables before cleaning up temporary resources.

Discovery Contracts

The metadata retrieved during discovery materializes into a JSON discovery contract that downstream automation consumes. The MSK migration skill exemplifies this pattern in skills/specialized-skills/analytics-skills/migrate-to-msk/scripts/sizing.py, which reads cluster-config.json—the discovery contract—before performing any assessment or sizing calculations. This contract contains critical fields such as bootstrapServers and tlsEnabled that determine how the skill interacts with the target cluster.

Guardrails and Validation

The toolkit enforces strict guardrails ensuring discovery completes before any "full" operation executes. Skills must explicitly reference references/discovery.md and present discovered candidates to users for confirmation. The generic analytics skill checklist in skills/specialized-skills/analytics-skills/connecting-to-data-source/SKILL.md mandates this verification step, preventing automated actions against unintended resources.

Runtime Discovery in Practice

The following examples demonstrate how skills implement runtime discovery patterns using Python, Bash, and YAML configurations.

Reading Discovery Contracts in Python

The MSK migration skill consumes discovery output to configure connection parameters:

import json
import pathlib

# Load the discovery contract produced during the discovery phase

contract_path = pathlib.Path(
    "migrate-to-msk-skill-artifacts") / cluster_name / "cluster-config.json"

with open(contract_path) as f:
    discovery = json.load(f)

# Extract discovered configuration for downstream use

bootstrap_servers = discovery["bootstrapServers"]
tls_enabled = discovery["tlsEnabled"]

Dynamic Schema Discovery with Glue

For data lake ingestion scenarios, skills orchestrate temporary Glue crawlers to capture schema information:

# Launch crawler to introspect JDBC source

aws glue start-crawler --name temp-discovery-crawler --region $AWS_REGION

# Retrieve discovered schema metadata

aws glue get-tables --database-name temp_discovery_db --region $AWS_REGION

# Cleanup temporary discovery resources

aws glue delete-crawler --name temp-discovery-crawler
aws glue delete-database --name temp_discovery_db

Discovery Checklist Configuration

Skills define their discovery requirements in structured checklists:

steps:
  - verify required tools are installed
  - list candidate resources (e.g., `aws rds describe-db-instances`)
  - present candidates to the user for selection
  - record the chosen ARN in the discovery contract

Summary

• Runtime discovery enables AWS Agent Toolkit skills to learn about AWS resources dynamically during execution rather than relying on static configuration.
• The process follows four phases: start-up registration, resource enumeration via AWS APIs, contract materialization into JSON, and guardrail validation before action execution.
• Discovery contracts stored as cluster-config.json or similar files provide the canonical source of truth for resource topology, endpoints, and security settings.
• Skills must adhere to the discovery workflow defined in references/discovery.md and obtain user confirmation before proceeding with automated operations.

Frequently Asked Questions

What triggers runtime discovery in an AWS Agent Toolkit skill?

Runtime discovery triggers automatically when a skill instance initializes, specifically when the /run endpoint executes in Lambda MicroVM environments. The skill registers with the discovery service to obtain per-VM state and then proceeds to query AWS APIs for resource metadata before performing any substantive operations.

How does runtime discovery differ from static configuration?

Static configuration requires users to hard-code ARNs, endpoints, and schema definitions before execution. Runtime discovery queries live AWS APIs using describe-* and list-* operations to discover current resource topology, ensuring skills operate against existing infrastructure rather than potentially outdated manual inputs.

What format does discovery output use?

Discovery output materializes as JSON discovery contracts, typically named cluster-config.json or similar. These files contain structured fields such as bootstrapServers, tlsEnabled, and security profiles that downstream skill logic consumes to establish connections and perform assessments.

Where can I find the discovery requirements for specific skills?

Each specialized skill documents its discovery requirements in references/discovery.md within its skill directory. For example, analytics skills reference skills/specialized-skills/analytics-skills/connecting-to-data-source/references/discovery.md, which defines the mandatory checklist steps and guardrails before resource interaction.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}