a2a_pack.runtime

Declarative runtime/deployment metadata.

These types describe how the platform should run an agent: lifecycle, state needs, isolation level, resource budget, egress policy. They are read by the deployer and by the registry; agent code itself should not depend on which runtime is selected.

AgentComposition (class)

AgentComposition(*, sub_agents: tuple[a2a_pack.runtime.CompositionSubAgent, ...] = (), planning: Literal['llm_dag', 'deterministic_dag'] = 'llm_dag', max_nodes: typing.Annotated[int, Gt(gt=0)] = 8, max_parallel: typing.Annotated[int, Gt(gt=0)] = 3, max_replans: typing.Annotated[int, Ge(ge=0)] = 1) -> None

Declarative composition block from a2a.yaml.

public_payload (method)

public_payload(self) -> 'dict[str, Any]'

(no docstring)

AgentDatabase (class)

AgentDatabase(*, name: str, engine: Literal['postgres'] = 'postgres', provider: Literal['neon'] = 'neon', scope: Literal['user', 'org'] = 'user', branch: str = 'main', access_mode: Literal['read_only', 'read_write', 'owner'] = 'read_write', env: a2a_pack.runtime.AgentDatabaseEnv = <factory>, migrations: a2a_pack.runtime.AgentDatabaseMigrations | None = None, scale_to_zero: bool = True) -> None

Platform-managed Neon/Postgres database declaration.

public_payload (method)

public_payload(self) -> 'dict[str, Any]'

(no docstring)

AgentDatabaseEnv (class)

AgentDatabaseEnv(*, url: str = 'DATABASE_URL') -> None

Environment variables populated with platform-managed DB credentials.

public_payload (method)

public_payload(self) -> 'dict[str, Any]'

(no docstring)

AgentDatabaseMigrations (class)

AgentDatabaseMigrations(*, path: str | None = None) -> None

Optional migrations path for a platform-managed database.

public_payload (method)

public_payload(self) -> 'dict[str, Any]'

(no docstring)

AgentEndpoint (class)

AgentEndpoint(*, name: str | None = None, path: str, methods: tuple[typing.Literal['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'], ...] = ('POST',), skill: str, body_arg: str = 'body', headers_arg: str | None = None, query_arg: str | None = None) -> None

Raw HTTP endpoint adapter exposed by the runtime.

The endpoint path is not a skill URL. The runtime accepts the provider's native HTTP request, maps it into handler arguments, and dispatches to the named skill through the normal agent execution path.

AgentGoal (class)

AgentGoal(*, objective: str = '', success_criteria: tuple[str, ...] = (), constraints: tuple[str, ...] = ()) -> None

Durable objective advertised by a composable/meta agent.

public_payload (method)

public_payload(self) -> 'dict[str, Any]'

(no docstring)

AgentMemory (class)

AgentMemory(*, tiers: tuple[typing.Literal['files', 'kv', 'vector'], ...] = (), namespace: str | None = None, scope: Literal['agent', 'user', 'thread'] = 'agent', retention: Literal['ephemeral', 'durable'] = 'durable') -> None

Long-term memory declaration for composable/meta agents.

public_payload (method)

public_payload(self) -> 'dict[str, Any]'

(no docstring)

AgentPlatformResources (class)

AgentPlatformResources(*, memory: a2a_pack.runtime.AgentMemory | None = None, databases: tuple[a2a_pack.runtime.AgentDatabase, ...] = ()) -> None

Platform-managed resources declared in a2a.yaml.

from_mapping (method)

from_mapping(data: 'Mapping[str, Any] | None') -> "'AgentPlatformResources'"

(no docstring)

public_payload (method)

public_payload(self) -> 'dict[str, Any]'

(no docstring)

AgentRuntime (class)

AgentRuntime(*, lifecycle: a2a_pack.runtime.Lifecycle = <Lifecycle.EPHEMERAL: 'ephemeral'>, availability: a2a_pack.runtime.RuntimeAvailability = <RuntimeAvailability.ON_DEMAND: 'on_demand'>, state: a2a_pack.runtime.State = <State.NONE: 'none'>, sandbox: a2a_pack.runtime.Sandbox = <Sandbox.MICROSANDBOX: 'microsandbox'>, resources: a2a_pack.runtime.Resources = <factory>, concurrency: typing.Annotated[int, Gt(gt=0)] = 1, egress: a2a_pack.runtime.EgressPolicy = <factory>, tools_used: tuple[str, ...] = (), llm_provisioning: a2a_pack.runtime.LLMProvisioning = <LLMProvisioning.PLATFORM: 'platform'>, pricing: a2a_pack.runtime.Pricing = <factory>, wants_cp_jwt: bool = False, platform_resources: a2a_pack.runtime.AgentPlatformResources = <factory>, endpoints: tuple[a2a_pack.runtime.AgentEndpoint, ...] = (), apt_packages: tuple[str, ...] = ()) -> None

Aggregate runtime declaration; published on the Agent Card.

CompositionSubAgent (class)

CompositionSubAgent(*, name: str | None = None, tag: str | None = None, version: str | None = None, skills: tuple[str, ...] = (), default_args: dict[str, typing.Any] = <factory>, required: bool = True) -> None

One callable dependency declared by a composable/meta agent.

public_payload (method)

public_payload(self) -> 'dict[str, Any]'

(no docstring)

EgressPolicy (class)

EgressPolicy(*, allow_hosts: tuple[str, ...] = (), allow_internal_services: tuple[str, ...] = (), deny_internet_by_default: bool = True) -> None

What external hosts the agent is allowed to talk to.

LLMProvisioning (class)

LLMProvisioning(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Where the agent's LLM credentials come from.

Drives both runtime behaviour (ctx.llm resolution) and what the marketplace can charge the caller.

Lifecycle (class)

Lifecycle(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

How long an instance of the agent process lives.

MetaAgentManifest (class)

MetaAgentManifest(*, composition: a2a_pack.runtime.AgentComposition | None = None, goal: a2a_pack.runtime.AgentGoal | None = None, memory: a2a_pack.runtime.AgentMemory | None = None) -> None

Typed meta-agent contract parsed from a2a.yaml or class attrs.

from_mapping (method)

from_mapping(data: 'Mapping[str, Any] | None') -> "'MetaAgentManifest'"

(no docstring)

public_payload (method)

public_payload(self) -> 'dict[str, Any]'

(no docstring)

Pricing (class)

Pricing(*, price_per_call_usd: float = 0.0, caller_pays_llm: bool = False, notes: str = '', compute: dict[str, float] | None = None, total_usd: float | None = None) -> None

Per-agent pricing declaration. Surfaced on the Card; the marketplace uses it to display "this much per call" to potential callers.

Resources (class)

Resources(*, cpu: str = '100m', memory: str = '256Mi', gpu: typing.Annotated[int, Ge(ge=0)] = 0, max_runtime_seconds: typing.Annotated[int, Gt(gt=0)] = 600) -> None

Resource budget hint for the deployer.

RuntimeAvailability (class)

RuntimeAvailability(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Developer-facing availability intent for hosted deployments.

Sandbox (class)

Sandbox(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Isolation level. The platform always runs agents under microsandbox.

Modeled as an enum (rather than a constant) so the wire format stays stable if more isolation tiers are added later, but only one value is currently valid: every agent runs in a microvm-class sandbox.

SkillPolicy (class)

SkillPolicy(*, timeout_seconds: float | None = None, idempotent: bool = False, max_retries: typing.Annotated[int, Ge(ge=0)] = 0, cost_class: str | None = None, allow_scope_expansion: bool = False, grant_mode: str | None = None, grant_allow_patterns: tuple[str, ...] = (), grant_deny_patterns: tuple[str, ...] = (), grant_outputs_prefix: str | None = None, grant_write_prefixes: tuple[str, ...] = (), grant_ttl_seconds: Optional[Annotated[int, Gt(gt=0)]] = None, grant_run_timeout_seconds: Optional[Annotated[int, Gt(gt=0)]] = None, grant_approval_timeout_seconds: Optional[Annotated[int, Gt(gt=0)]] = None, grant_scope_approval_timeout_seconds: Optional[Annotated[int, Gt(gt=0)]] = None) -> None

Per-skill operational policy advertised on the Agent Card.

State (class)

State(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

What kind of state the agent retains between invocations.

TemplateLineage (class)

TemplateLineage(*, schema_version: str = '2026-06-02', template_ref: str | None = None, template_version: str | None = None, template_digest: str | None = None, source_agent: str | None = None, source_agent_version: str | None = None, source_repo_url: str | None = None, source_revision: str | None = None, instance_id: str | None = None, instance_version: str | None = None, update_policy: Literal['none', 'notify', 'propose', 'auto_patch'] = 'none', update_channel: str | None = None, migration_skill: str | None = None) -> None

Opt-in source-template lineage and update policy.

Agents generated from templates can publish this on their Agent Card so platforms can detect available template updates and decide how to handle them. The policy is intentionally advisory: callers/platforms remain the authority for whether an update is proposed, applied, reviewed, or denied.

from_mapping (method)

from_mapping(data: 'Mapping[str, Any] | str | None') -> "'TemplateLineage'"

(no docstring)

none (method)

none() -> "'TemplateLineage'"

(no docstring)

apply_project_manifest (function)

apply_project_manifest(agent_cls: 'type[Any]', config: 'Mapping[str, Any] | None') -> 'MetaAgentManifest'

Attach parsed a2a.yaml platform metadata to an agent class.

a2a run receives only an entrypoint, but the working directory still contains a2a.yaml. Applying parsed metadata here makes local and deployed Agent Cards reflect declarative composition/lineage without importing control-plane code.

Source: apps/a2a/a2a_pack/runtime.py