Python API reference

You can use the rh-sigstore-a2a Python API for programmatic integration into your applications.

Signing
Copy link

The following example demonstrates signing with ambient CI credentials:

from sigstore_a2a.signer import AgentCardSigner
from sigstore_a2a.provenance import ProvenanceBuilder

# Sign with ambient CI credentials
signer = AgentCardSigner(use_ambient_credentials=True)
signed_card = signer.sign_agent_card("agent-card.json")

# Sign with provenance
provenance = ProvenanceBuilder().build_provenance(
    "agent-card.json",
    source_repo="myorg/myrepo",
    commit_sha="abc123",
)
signed_card = signer.sign_agent_card("agent-card.json", provenance_bundle=provenance)

# Sign and write to a file in one step
output_path = signer.sign_file("agent-card.json", output_path="signed.json")

The sign_agent_card method accepts:

  • A file path (str or pathlib.Path)
  • A JSON string
  • A Python dictionary
  • An AgentCard protobuf object

Verification
Copy link

The following example demonstrates verification with identity constraints:

from sigstore_a2a.verifier import AgentCardVerifier, IdentityConstraints

# Create a verifier for a specific identity and issuer
verifier = AgentCardVerifier(
    identity="dev@example.com",
    oidc_issuer="https://accounts.google.com",
)

# Verify with additional constraints
constraints = IdentityConstraints(
    repository="myorg/myrepo",
    workflow="Sign Agent Card",
    identity="dev@example.com",
    identity_provider="https://accounts.google.com",
)

result = verifier.verify_signed_card("signed-agent-card.json", constraints)

if result.valid:
    print(f"Valid. Signed by: {result.identity.get('subject')}")
    print(f"Agent: {result.agent_card.name} v{result.agent_card.version}")
else:
    for error in result.errors:
        print(f"Error: {error}")

Using a private Sigstore instance
Copy link

The following examples demonstrate using a private RHTAS instance:

from pathlib import Path
from sigstore_a2a.signer import AgentCardSigner
from sigstore_a2a.verifier import AgentCardVerifier

# TUF-bootstrapped instance
signer = AgentCardSigner(
    instance="https://sigstore.example.com",
    use_ambient_credentials=True,
)
verifier = AgentCardVerifier(
    instance="https://sigstore.example.com",
    identity="signer@example.com",
    oidc_issuer="https://keycloak.example.com/realms/trusted-artifact-signer",
)

# Manual trust config
signer = AgentCardSigner(
    trust_config=Path("./client-trust-config.json"),
    identity_token="<your-oidc-token>",
    client_id="my-client-id",
)
verifier = AgentCardVerifier(
    trust_config=Path("./client-trust-config.json"),
    identity="signer@example.com",
    oidc_issuer="https://keycloak.example.com/realms/trusted-artifact-signer",
)

# Staging (testing only)
signer = AgentCardSigner(staging=True)
verifier = AgentCardVerifier(staging=True)