Schema Interfaces for Network Management Agent Skills

2.1. Network Management Agent

A software component that performs or assists with network-management work, including analysis, configuration, assurance, incident handling, validation, simulation, or remediation.¶

2.2. Client Agent

An A2A Client that identifies and contacts a remote agent, obtains and validates its Skill Interface Documents, and delegates tasks on behalf of a user or another system. This term describes a protocol role and does not imply administrative control over the remote agent.¶

2.3. Remote Agent

An A2A Server that publishes an Agent Card, exposes skills, receives delegated tasks, and returns task status and results.¶

2.4. Network-Management Domain

An application subject area, such as planning, assurance, configuration, or incident analysis, whose owner defines the meaning of its skill inputs, outputs, and supporting records. A domain is a schema-governance boundary; it does not create a global namespace for skill identifiers.¶

2.5. Delegation Hop

The relationship created when an agent handling one A2A Task invokes a skill at another agent, thereby creating a distinct downstream A2A Task. The task handled by the invoking agent is the upstream task, and the newly created task is the downstream task.¶

2.6. Schema Reference

A portable schema identity, integrity information, and inline schema content. The identity and digest remain independent of any deployment-local mechanism used to manage the schema before the Skill Interface Document is assembled.¶

2.7. Version String

A canonical version identifier consisting of two dot-separated non-negative decimal integers, MAJOR.MINOR. A component has no leading zero unless its value is zero. Two versions are equal only when both numeric components are equal; the canonical representation makes this equivalent to string equality. A change that is not backward compatible with consumers of the prior version increments MAJOR and resets MINOR to zero. A backward-compatible change increments MINOR. This syntax and comparison rule apply to skill_version and to the version in each Schema Reference. The version of the Skill Interface Schema is separately identified by interface_version, which this document fixes at 1.0.¶

2.8. Skill

A named capability advertised by an agent and invokable through an Agent-to-Agent protocol. A skill identifier is scoped to the Agent Card in which it is advertised and is not globally unique. Portable schema identity is provided by the Schema Reference rather than by the skill identifier alone.¶

2.9. Skill Interface Schema

The standardized, language-neutral schema that defines the permitted structure and interpretation of a Skill Interface Document. An agent uses a local or otherwise trusted copy of this schema to validate the documents it publishes. A client agent uses the same schema version to validate retrieved documents.¶

2.10. Skill Interface Document

A machine-readable description of a skill's accepted input, produced output, possible supporting records, interaction behavior, and applicable constraints. It is an instance of the Skill Interface Schema. It contains domain-specific Schema References supplied by the agent without modifying the standardized Skill Interface Schema.¶

2.11. Skill Interface Document Digest

The interface_digest value identifies the exact Skill Interface Document selected by a client. It is the string sha256: followed by the lowercase hexadecimal representation of the SHA-256 digest of the UTF-8 encoding of the complete Skill Interface Document serialized using the JSON Canonicalization Scheme (JCS) [JCS].¶

The digest covers every member of the Skill Interface Document, including its inline domain schemas. It does not cover the standardized Skill Interface Schema used to validate the document, the Agent Card, a describe_skill response wrapper, or a domain-skill invocation. The interface_digest is carried outside the Skill Interface Document so that the document does not contain a digest of itself.¶

The same Skill Interface Document Digest MUST be carried in the Agent Card extension advertisement, the describe_skill response, and each domain-skill invocation that uses the document. All three carried values and the digest calculated from the returned document MUST match.¶

2.12. Supporting Record

A domain-specific observation or artifact used to derive, validate, reproduce, or audit a skill output. A supporting record is validated against the applicable schema identified by the Skill Interface Document.¶

2.13. A2A Artifact Identifier

The task-scoped artifactId assigned to an A2A Artifact as defined by A2A [A2A]. It identifies an Artifact within an A2A Task and can be used by a skill output to reference a supporting-record Artifact carried by that Task. It is not a globally portable record identifier.¶

The following figure summarizes the structure of a Skill Interface Document:¶

text Skill Interface Document |-- interface_version |-- skill_id |-- skill_version |-- input_schema -------------------- Schema Reference | |-- schema_uri | |-- version | |-- dialect | |-- digest | `-- resolution | |-- type = "inline" | `-- schema |-- output_schema ------------------- Schema Reference |-- supporting_record_schemas[] | |-- kind | `-- schema_reference ------------ Schema Reference |-- interaction | |-- supported_response_modes[] | `-- cancellable `-- authority |-- default_mode `-- approval_may_be_required ¶

6.1. Preserve task identity across delegation hops

When an agent handling an upstream A2A Task invokes another agent, the downstream invocation creates a distinct A2A Task at the receiving agent. A delegating component MUST NOT reuse the upstream task identifier as the downstream protocol task identifier. Protocol task identifiers are interpreted in the scope of the agent or endpoint that issued them; implementations MUST NOT assume that they are globally unique. An implementation that needs to correlate the two tasks MUST record their relationship using separately named metadata rather than overloading either protocol task identifier.¶

6.2. Standardize reusable structures, not all domain semantics

This framework standardizes reusable interface metadata, not the semantics of every network-management domain. A vendor or domain owner defines the input, output, and supporting-record schemas used by a particular skill and combines them with the common structure; it does not redefine that structure. The domain determines schema meaning and governance, while the skill identifier selects one callable capability within an agent's advertised Agent Card.¶

6.3. Distinguish structural conformance from semantic conformance

Matching Schema References establishes that communicating agents use the same schema; it does not establish that the schema exposes sufficient semantics for the intended operation. A schema that defines configuration only as a string can validate the presence and type of that string but cannot by itself identify affected resources, validate command dependencies, or establish that the commands implement the requested intent.¶

When a skill-specific specification requires a receiving agent to inspect, validate, transform, simulate, or apply a configuration change, that specification MUST identify a machine-readable representation with sufficient semantics for the required processing. The applicable input, output, or supporting-record schema describes that representation, and describe_skill makes the schema available before delegation. The receiving agent MUST validate the representation and use a domain-specific implementation for semantic validation, policy evaluation, simulation, or application, as applicable.¶

6.4. Deliver schemas inline in version 1.0

Every v1.0 Schema Reference returned by describe_skill MUST carry its schema content inline. A client agent validates that embedded content against the declared digest and does not contact an external service to complete the interface.¶

An inline schema MAY be a compound schema document containing embedded schema resources as defined by JSON Schema [JSON-SCHEMA]. Every $ref and $dynamicRef in resolution.schema MUST resolve to the root schema, one of its subschemas, or an embedded schema resource contained within that same resolution.schema value. Each embedded schema resource used as a reference target MUST identify itself with an absolute URI in $id. References MAY retain an absolute URI when that URI resolves to such an embedded resource; an absolute URI does not permit external retrieval.¶

Validators MUST perform schema and instance validation with network and filesystem schema retrieval disabled. The only schema content a validator may use from outside resolution.schema is a locally trusted copy of the meta-schema identified by the Schema Reference's dialect. Embedded schema resources MUST use that same dialect. A reference that cannot be resolved under these rules, an attempted external retrieval, or an embedded resource that selects another dialect makes the Skill Interface Document invalid and MUST result in interface_invalid.¶

For interface version 1.0, a format value defined by JSON Schema Validation [JSON-SCHEMA-VALIDATION] MUST be evaluated as an assertion during instance validation. This is an additional interface version 1.0 conformance rule even when the referenced JSON Schema dialect would otherwise treat format as an annotation. In particular, an instance validated against "format": "date-time" MUST conform to the Internet timestamp syntax defined by [TIMESTAMP].¶

Registries, bundles, caches, and agent packaging MAY be used locally to store, govern, distribute, or prepare schemas. Their use does not alter the v1.0 wire representation, and a client agent is not required to know which local mechanism supplied an inline schema. Version 1.0 does not require the schema to originate in either an agent package or a central registry; either can be a deployment-local source used before the complete inline document is served.¶

6.5. Distinguish outputs from supporting records

The skill output states what the agent concluded or delivered. Supporting records explain why that output can be trusted, reproduced, or audited. An output and a supporting record use separate A2A Artifacts. An output that depends on a supporting record SHOULD reference that record's task-scoped A2A artifactId rather than duplicate its content.¶

6.6. Assemble and validate before advertisement

An agent implementation owns its domain-specific input, output, and supporting-record schemas. Its protocol service combines those schemas with a trusted copy of the standardized Skill Interface Schema and applicable interaction and authority declarations. The resulting Skill Interface Document MUST be validated before it is advertised or returned.¶

An implementation SHOULD perform this assembly during agent initialization or deployment configuration and retain an immutable validated document for each skill version. The describe_skill operation retrieves that document. It does not ask the agent's domain logic to construct or alter an interface while processing the interface request.¶

8.1. Skill input

The skill input is the domain-specific application data submitted to a skill invocation. The input MUST validate against the input_schema in the selected Skill Interface Document. The interface version 1.0 A2A mapping carries that input in the arguments member of its skill request object. As specified in Section 9.4, that object is the data value of the A2A user Message's single Data Part.¶

Constraints that affect skill execution MUST be represented in and validated by the skill's input_schema. A receiving agent MUST enforce a supplied constraint or reject the invocation with the constraint_rejected machine-readable error condition defined in Section 9.5; it MUST NOT silently ignore a valid constraint. Constraints enforced solely by a delegating system need not be transmitted. The names, structures, and semantics of transmitted constraints are defined by the domain-specific input schema rather than by this framework. Protocol lifecycle and authorization controls remain the responsibility of A2A and deployment policy.¶

Version 1.0 applies input_schema to the complete arguments value in the initial domain-skill invocation. If an A2A Task enters TASK_STATE_INPUT_REQUIRED, a caller's follow-up Message may contain only the information requested by the agent. Version 1.0 does not define a schema for such follow-up data, and the follow-up is not independently validated against input_schema. A deployment that requires schema-governed multi-turn input needs an additional profile or separately advertised skill for that exchange. The combined intermediate-exchange example in Section 9.4 illustrates an input-required request, the caller's partial reply, and the separate task identifiers used when another agent is invoked.¶

8.2. Skill output

The skill output is the domain-specific application data produced by a skill invocation. The output MUST validate against the output_schema in the selected Skill Interface Document. The interface version 1.0 A2A mapping carries that output in the result member of its skill result object. As specified in Section 9.4, that object is the data value of the primary A2A Artifact's single Data Part.¶

Protocol task status indicates whether protocol execution completed; it is not part of the skill output. Completion of a protocol task does not by itself establish that a requested downstream network operation completed successfully. The domain output schema defines how the skill reports the result of that operation.¶

Version 1.0 applies output_schema to the complete final result, after any streamed Artifact updates have been assembled. It does not apply independently to A2A status Messages, progress updates, or incomplete Artifact chunks. Version 1.0 therefore defines no separate streaming-output schema: A2A governs delivery of partial Artifact updates, while this document validates the assembled final result and each complete supporting record. The schema boundary for each intermediate exchange is summarized in Section 9.4. Supporting records and the primary output are separate Artifacts within the same A2A Task. An agent MAY stream zero or more complete supporting-record Artifacts before it produces the primary result Artifact. Each supporting record validates independently against its declared supporting-record schema, while the complete primary result validates against output_schema. A supporting record does not merge with or replace the primary result, and the final result MAY reference it by its A2A artifactId. An early finding intended for independent machine consumption SHOULD be published as such a supporting record.¶

8.3. Supporting-record schemas

A supporting record is a domain-specific observation or artifact used to derive, validate, reproduce, or audit a skill output. Each entry in supporting_record_schemas associates a kind with the Schema Reference for the complete record. A produced record MUST validate against the schema for its identified kind. A protocol progress update is not a supporting record unless it is published in that form and passes this validation.¶

Each supporting-record kind in a Skill Interface Document MUST be unique and MUST NOT equal that document's skill_id. This prevents a supporting-record Artifact from being confused with the primary result Artifact, whose name equals skill_id.¶

This framework does not define an additional common record envelope. The domain schema defines any required record identifier, producer, source, observation time, production time, integrity, derivation, classification, or payload fields. Under this mapping, each supporting record is carried in an A2A Artifact belonging to the same A2A Task, so the record's domain schema need not repeat the A2A task or context identifier.¶

When supporting records justify a skill output, the domain output_schema SHOULD define where the output carries their references. For records carried by the same A2A Task, each reference SHOULD identify the corresponding A2A Artifact by artifactId. This document does not mandate a common property name or reference structure within every domain output.¶

The skill output is the answer, decision, or deliverable normally consumed by the caller. Supporting records contain the observations and artifacts that support that output. They MUST be published in separate Artifacts. The output SHOULD reference a supporting record by its artifactId instead of embedding a duplicate copy.¶

9.1. Agent advertisement

An agent conforming to this framework MUST advertise describe_skill and each schema-governed domain skill in its Agent Card. It MUST also advertise the following A2A extension in AgentCapabilities.extensions:¶

text https://agentic-network-management.github.io/agent-schema-interfaces/extensions/schema-interface/v1 ¶

The extension MAY be marked required: false so that extension-unaware clients can continue to use the agent through base A2A procedures. A client using the procedure in this document MUST activate the extension for describe_skill and domain-skill requests as specified by A2A [A2A]. When the HTTP binding is used, the client requests activation by including the extension URI in the A2A-Extensions request header. An agent that activates the extension SHOULD echo that URI in the A2A-Extensions response header, as specified by A2A. The A2A Message extensions list MUST also include the URI when the Message carries a request object defined by this document. The header performs extension activation; the Message field identifies the extension as relevant to that Message.¶

The extension params MUST contain interface_version with value 1.0 and a skills array. Each entry MUST contain skill_id, skill_version, and interface_digest. The skill_id MUST identify an AgentSkill in the same Agent Card. The interface_digest MUST be the Skill Interface Document Digest for the document returned by describe_skill for that skill. Version 1.0 permits exactly one advertised skill_version and interface_digest binding for each skill_id in an Agent Card.¶

The following fragment illustrates the extension advertisement:¶

json { "uri": "https://agentic-network-management.github.io/agent-schema-interfaces/extensions/schema-interface/v1", "description": "Schema interfaces for advertised skills", "required": false, "params": { "interface_version": "1.0", "skills": [ { "skill_id": "example_skill", "skill_version": "1.0", "interface_digest": "sha256:..." } ] } } ¶

The client selects the advertised skill_id, skill_version, and interface_digest before calling describe_skill. Version 1.0 does not define request parameters for negotiating or selecting another interface or skill version within describe_skill. An agent that needs to advertise concurrent incompatible versions in version 1.0 MUST expose them using distinct skill identifiers. A client selects one of those identifiers from the Agent Card; it MUST NOT infer a version range or negotiate an unadvertised version.¶

When an agent replaces an advertised interface with a backward-compatible revision, it increments the minor skill_version and advertises the new version and digest. During a migration in which old and new incompatible interfaces must remain callable concurrently, the agent advertises them under distinct skill identifiers. Deprecation periods and removal policy are deployment concerns, but removal of an advertised version MUST be reflected in a newly retrieved Agent Card before clients can select it for new work.¶

The describe_skill skill MUST accept structured input identifying the selected skill_id and MUST produce structured output containing the corresponding Skill Interface Document and its interface_digest.¶

A caller MUST NOT assume that every Agent-to-Agent implementation conforms to this framework. Absence of either the schema-interface extension or the describe_skill skill from the Agent Card means that the agent does not provide the schema-interface procedure defined here. Such an agent MAY still be invoked using the base Agent-to-Agent protocol or an explicitly configured out-of-band interface contract. The caller MUST NOT infer or prescribe the remote skill's domain schemas from skill descriptions or media types alone, and MUST NOT claim schema-interface conformance or schema-governed compatibility for such an invocation. Supporting multiple non-conforming agents requires separately configured contracts, adapters, or other bilateral integration mechanisms. This is the scaling problem addressed by this document: replacing an expanding collection of bilateral integrations with one standardized interface-retrieval procedure.¶

9.2. describe_skill request

The request identifies one advertised skill by skill_id. It does not carry interface_version, skill_version, a version range, or another in-band negotiation parameter.¶

The client MUST invoke the A2A Send Message or Send Streaming Message operation with a user-role Message containing exactly one Data Part. The Data Part's data value MUST be the following request object:¶

json { "skill": "describe_skill", "arguments": { "skill_id": "example_skill" } } ¶

9.3. describe_skill response

On success, the A2A task MUST reach the completed state and contain exactly one Artifact. The Artifact name MUST be describe_skill, and the Artifact MUST contain exactly one Data Part. Its data value MUST be the following object, where the notation in angle brackets represents the complete Skill Interface Document rather than a JSON string:¶

text { "skill": "describe_skill", "result": { "interface_digest": "sha256:...", "interface": <Skill Interface Document> } } ¶

The result.interface value is a Skill Interface Document conforming to the advertised and previously selected version of the standardized Skill Interface Schema. Its skill_version MUST equal the advertised domain-skill version selected before the request. The result.interface_digest value MUST equal the interface_digest advertised for the selected skill. The client MUST calculate the Skill Interface Document Digest of result.interface and verify that it equals both values. In version 1.0, every Schema Reference in the document MUST contain the complete domain schema inline in resolution.schema and MUST set resolution.type to inline.¶

The response MUST be the previously assembled and validated document for the selected skill version. The describe_skill operation MUST NOT redefine the standard structure or invoke domain logic to construct or modify the document while processing the request. The returned input, output, and supporting-record schemas remain specific to the selected agent and skill.¶

The selected document and its calculated digest MUST correspond to the skill version and digest advertised by the agent. If an advertised interface cannot currently be returned, the agent MUST report interface_unavailable. If the available document is malformed, inconsistent with the selected skill, versions, or digest, or otherwise fails required validation, the agent MUST report interface_invalid. It MUST NOT accept or return an unvalidated opaque payload as a substitute.¶

9.4. Domain-skill invocation

After validating the selected Skill Interface Document, a client invokes the domain skill with the A2A Send Message or Send Streaming Message operation. The user-role Message MUST contain exactly one Data Part. The Data Part's data value MUST be this skill request object:¶

json { "skill": "example_skill", "skill_version": "1.0", "interface_digest": "sha256:...", "arguments": { "objective": "Evaluate the selected network resource" } } ¶

The skill value MUST equal the selected Agent Card skill identifier. The skill_version and interface_digest values MUST equal the values selected from the Agent Card extension, returned by describe_skill, and validated by the client. Before validating arguments or invoking domain logic, the receiving agent MUST compare both values with its currently active Skill Interface Document for that skill. It MUST reject the request with interface_mismatch if either value differs. The arguments value is the complete domain input and MUST validate against the selected Skill Interface Document's input_schema. The receiving agent MUST reject a nonconforming input with input_invalid before invoking domain logic.¶

Base A2A does not assign a primary role to an Artifact. This profile uses the term primary result Artifact for the one Artifact that carries the final skill output. It is identified by an Artifact name equal to the selected skill identifier and by a single Data Part containing the skill result object defined below.¶

On success, the task MUST reach the completed state and contain exactly one primary result Artifact:¶

json { "skill": "example_skill", "result": { "status": "succeeded" } } ¶

The result value is the complete domain output and MUST validate against the selected Skill Interface Document's output_schema.¶

Each supporting record, when present, MUST be carried in a separate Artifact. The Artifact name MUST equal the record kind declared in supporting_record_schemas, and its single Data Part MUST contain the complete record value that validates against the Schema Reference associated with that kind. The record kind, and therefore the supporting Artifact name, MUST NOT equal the selected skill_id. The Artifact artifactId provides a stable task-scoped identifier that the domain output MAY reference. A record transported or retrieved outside the task requires a stable reference mechanism defined by its domain schema.¶

The same final Task and Artifact requirements apply whether the client uses synchronous completion, streaming updates, or task retrieval and polling. For streaming, A2A governs Artifact-update delivery through artifactId, append, and lastChunk [A2A]. When append is true, the event content is appended to previously delivered content for the same Artifact. This profile does not assign additional semantics to append when it is false or absent, and does not define independent schema conformance for a partial update. A client MAY process the A2A updates incrementally or retrieve the completed Task using the A2A Get Task operation. In either case, the complete primary result MUST validate against output_schema.¶

The following summary shows the schema boundary for intermediate exchanges in version 1.0:¶

The primary result Artifact is the profile-defined Artifact described in Section 9.4; base A2A does not assign a primary role to an Artifact. The following example combines the intermediate exchanges described above:¶

```text 1. Initial request arguments validates against input_schema.¶

1. Status update: TASK_STATE_INPUT_REQUIRED The agent requests one missing credential reference. No schema for this status Message is defined by version 1.0.¶

2. Caller follow-up Message The caller sends only the requested credential reference. The reply augments the Task interaction; it does not replace the original input and is not independently validated against input_schema.¶

3. Supporting-record Artifact update artifactId="record-1", name="observation-record" The complete record validates against the advertised observation-record schema.¶

4. Incomplete primary result Artifact update artifactId="result-1", name="example_skill", lastChunk=false This update lacks fields required in the final result. A2A governs its delivery, and version 1.0 does not validate it independently against output_schema.¶

5. Complete primary result Artifact update artifactId="result-1", name="example_skill", lastChunk=true This final update contains the complete primary result. It validates against output_schema and may reference "record-1" as supporting information. A client may instead retrieve this complete Artifact from the Task using the A2A Get Task operation.¶

6. Status update: TASK_STATE_COMPLETED The agent reports completion only after validating the complete result. ```¶

If the receiving agent delegates work to another agent during this sequence, that delegation creates a distinct downstream A2A Task. An input-required status or Artifact belongs to the Task that emitted it. The delegating component records the association between the upstream and downstream task identifiers, qualified by their respective agent identities or endpoints; it does not reuse either identifier for the other Task.¶

All Artifacts in this sequence belong to the same A2A Task. The supporting record and primary result remain separate and each is validated against its own advertised schema. Version 1.0 does not define separate schemas for partial primary results or input-required replies.¶

9.5. Machine-readable error conditions

An error detected locally by a client before the remote agent creates a task MUST NOT be represented as a state of a nonexistent remote task. The client MUST stop the applicable procedure and report the machine-readable condition locally or through the error mechanism of its enclosing system.¶

When the remote agent reports one of the conditions below through an A2A Task, the Task's final status Message MUST contain exactly one Data Part whose data value has this form:¶

json { "error": { "code": "interface_invalid", "message": "The selected interface document is invalid" } } ¶

The code value MUST be one of the machine-readable conditions below or an additional value defined by a future profile. The human-readable message MAY be omitted. A server-side error detected before task creation MUST be carried using the error mechanism of the selected A2A protocol binding and SHOULD expose the same machine-readable code when that binding permits it. These conditions are not skill outputs and are not validated against the selected skill's output_schema.¶

The interface_invalid condition identifies a defect in the Skill Interface Document or an embedded schema. It MUST NOT be used when a valid interface rejects a particular data instance. Such instance failures use input_invalid, output_invalid, or constraint_rejected, as applicable.¶

A remote Task MUST reach TASK_STATE_REJECTED when the request is understood but is not accepted for execution because of interface_mismatch, input_invalid, constraint_rejected, or authorization_failed. A remote Task MUST reach TASK_STATE_FAILED when an accepted operation cannot complete, including when describe_skill cannot produce a valid advertised interface or when domain processing cannot produce valid output. A resource_limit_exceeded condition uses TASK_STATE_REJECTED when the limit is checked before acceptance and TASK_STATE_FAILED when the limit is reached during processing.¶

An implementation MUST distinguish at least the following conditions:¶

• skill_not_advertised: the requested skill_id is not advertised by the selected agent endpoint;¶

• unsupported_interface_version: the advertised or returned Skill Interface version is not supported by the client;¶

• interface_unavailable: the selected interface is advertised but cannot currently be returned;¶

• interface_invalid: a Skill Interface Document is malformed, does not match the selected skill, fails validation against the version 1.0 Skill Interface Schema, or contains an embedded schema that fails digest or schema validation;¶

• interface_mismatch: a domain-skill invocation carries a skill_version or interface_digest that does not match the receiving agent's currently active Skill Interface Document for that skill;¶

• input_invalid: the domain input does not validate against the selected Skill Interface Document's input_schema;¶

• output_invalid: the produced domain output does not validate against the selected Skill Interface Document's output_schema;¶

• constraint_rejected: a structurally valid requested constraint cannot be honored or enforced by the receiving agent;¶

• authorization_failed: authentication, authorization, or a required approval check does not permit the requested invocation or side effect; and¶

• resource_limit_exceeded: processing the interface, schema, input, output, or supporting records would exceed an implementation resource limit.¶

The skill_not_advertised condition can be detected by a client before it sends describe_skill. A client MUST NOT send the request when the Agent Card does not advertise the selected skill. A client detects unsupported_interface_version when the extension advertisement or returned document uses an interface version it does not support. Neither client-side condition creates a remote failed Task. If a server receives a domain-skill invocation based on a stale interface, it MUST report interface_mismatch through the interface version 1.0 A2A mapping using TASK_STATE_REJECTED.¶

A client that detects interface_invalid locally MUST reject the document and MUST NOT delegate the domain skill under this framework. An implementation MAY include a details array for input_invalid and output_invalid. Each entry MUST contain an instance_path identifying the invalid field using a JSON Pointer [JSON-POINTER]. It MAY contain a schema_path, keyword, expected, and actual value. These fields are diagnostic and do not replace the machine-readable error code. For example:¶

json { "error": { "code": "input_invalid", "message": "The threshold must be numeric", "details": [ { "instance_path": "/threshold", "schema_path": "/properties/threshold/type", "keyword": "type", "expected": "number", "actual": "string" } ] } } ¶

Diagnostic details MUST NOT disclose credentials, sensitive policy state, input values prohibited by local security policy, or other information that the caller is not authorized to receive.¶

The receiving agent MUST validate domain output before it reports TASK_STATE_COMPLETED; invalid output results in output_invalid and TASK_STATE_FAILED. A client MUST independently validate received output. If it detects invalid output after the remote agent reported completion, it MUST treat the output as unusable and report output_invalid locally; it cannot retroactively change the remote Task state.¶

9.6. Client-agent behavior

The following figure illustrates the conceptual inline flow between a client agent and a remote network management agent. Inline delivery does not replace Schema References. Each reference retains its stable identity, version, dialect, and digest while carrying the schema content in its resolution field.¶

       Client Agent                         Remote Agent
            |                                    |
            |------ Retrieve Agent Card -------->|
            |<-- Skills, versions, and interface |
            |    digests in A2A extension -------|
            |                                    |
            | Select advertised interface and    |
            | skill versions and digest          |
            |                                    |
            |--- describe_skill(skill_id) ------>|
            |<-- Document and interface_digest --|
            |       Schema References:           |
            |       - input schema               |
            |       - output schema              |
            |       - supporting records         |
            |       resolution.type = inline     |
            |       embedded schema content      |
            |                                    |
            | Validate document digest,          |
            | references, digests, and schemas   |
            |                                    |
            |--- Delegate request with version ->|
            |    and interface_digest            |
            |<--- Status, output, and records ---|
            | Validate response using cached     |
            | Schema References                  |

The client verifies each embedded schema against the digest declared by its Schema Reference before using it. The following steps define the v1.0 client behavior.¶

A client agent performs the following sequence:¶

1. retrieve the target Agent Card and obtain its A2A endpoint and schema- interface extension advertisement;¶

2. verify that both describe_skill and the selected domain skill are advertised, and select the advertised skill_version and interface_digest for that domain skill;¶

3. call describe_skill for the selected skill_id using the interface version 1.0 A2A mapping;¶

4. verify that the interface_digest returned by describe_skill equals the advertised value, calculate the digest of the returned Skill Interface Document, and verify that the calculated value also equals it;¶

5. validate the returned Skill Interface Document against a trusted local copy of the version 1.0 Skill Interface Schema, verify that its interface_version is 1.0, and verify that its skill_id and skill_version identify the selected skill and version;¶

6. verify every embedded domain schema against its Schema Reference digest;¶

7. validate the outgoing skill input against input_schema;¶

8. delegate the task through the Agent-to-Agent protocol, carrying the selected skill_version and interface_digest in the skill request;¶

9. receive task status, typed skill output, and supporting records according to that mapping;¶

10. validate the skill output against output_schema and validate the supporting records; and¶

11. preserve, forward, display, or interpret them according to local policy.¶

Before delegating a domain skill under this framework, the client agent MUST possess a successfully validated Skill Interface Document obtained from that target's describe_skill skill. If describe_skill is absent, fails, returns a document for a different skill or version, or returns a document that cannot be validated, the client agent MUST NOT delegate the domain request using the procedure defined in this document.¶

The client agent MAY reuse a cached Skill Interface Document without calling describe_skill before every task when the cache entry is bound to the same target identity, skill identifier, skill version, and interface digest advertised by the current Agent Card. A change to any of those values invalidates the entry and requires a new describe_skill exchange before the next delegation.¶

A generic client agent can validate and route an unfamiliar vendor schema without understanding its domain semantics. A domain-aware orchestrator may install optional handlers keyed by stable schema URI to evaluate operational thresholds, incident records, configuration policy, or other domain behavior.¶

A complete non-normative example is provided in Appendix B.¶

9.7. Composition of consecutive skills

When the output of one skill becomes the input to another skill, the component initiating the downstream delegation is the client agent for that interaction. That component may be a centralized orchestrator or the upstream agent itself communicating directly with the downstream agent. The same composition rules apply in either topology.¶

The downstream delegation creates a new Agent-to-Agent task with its own task identifier. The delegating component MUST retain the upstream and downstream task identifiers as distinct values. It SHOULD preserve a correlation mapping that includes the relevant agent identities or endpoints, skill identifiers, task identifiers, and timestamps for observability, audit, and troubleshooting. An implementation SHOULD define how this cross-hop correlation metadata is carried or recorded. Fields such as workflow_id, step_id, attempt_id, and parent_a2a_task_id may be used when defined by the applicable domain schema or binding, but they do not replace protocol task identifiers.¶

The following figure shows the reference comparison and validation decisions performed by that delegating component.¶

 Upstream Agent                 Delegating Component
       |                                  |
       |-- Output payload ---------------->|
       |   output_schema reference        |
       |                                  |
       |                         Retrieve downstream
       |                         Skill Interface
       |                                  |
       |                                  v
       |                         Downstream input_schema
       |                              reference
       |                                  |
       |                    Compare URI, version,
       |                    dialect, and digest
       |                                  |
       |                +-----------------+----------------+
       |                |                                  |
       |              Match                         No exact match
       |                |                                  |
       |      Validate output against              Reject direct
       |      downstream input schema               composition
       |                |
       |                v
       |      Create new downstream A2A task
       |      and delegate validated input
       |                |
       |                v
       |        Downstream Agent
       |      validates and processes

The standardized Schema Reference allows an orchestrating system or delegating agent to determine direct-composition eligibility without interpreting a domain-specific schema. Direct composition MUST require the Schema Reference for the transferred upstream output payload and the Schema Reference accepted for the corresponding downstream input to have the same schema_uri, version, dialect, and digest. Because version 1.0 carries schemas inline, the delegating component also verifies that each embedded schema matches its declared digest.¶

This exact-match rule is intentionally conservative. Two schemas can be structurally similar, or can both accept a particular instance, while assigning different meanings, units, defaults, constraints, or operational consequences to the same fields. Inferring compatibility from shape or successful validation alone could therefore connect semantically divergent interfaces. Comparing the complete portable identity and content digest gives v1.0 a deterministic composition decision without requiring domain interpretation, schema negotiation, or a standardized compatibility algorithm. The rule does not assert that only identical schemas can ever interoperate; it limits what this specification treats as direct composition.¶

The orchestrating system or delegating agent MUST validate the transferred instance mechanically against the downstream input schema before delegation, and the receiving agent MUST validate the received instance before processing it. Neither operation requires the orchestrating system or delegating agent to understand the schema's domain semantics.¶

If those Schema Reference fields do not match, the delegating component MUST NOT perform direct composition under this specification.¶

An implementation can use an out-of-band transformation mechanism before delegation. Transformation discovery, trust, execution, and provenance are outside the scope of this document. Any resulting payload enters this procedure as a new input and is subject to ordinary input validation against the downstream input_schema.¶

Matching Schema References and successful instance validation establish structural compatibility, not operational correctness. The receiving agent remains responsible for domain-semantic validation, authorization, policy evaluation, and operational safety before acting on the input.¶

For example, an input schema can define a network measurement with a metric, value, unit, observation window, observation time, and requested constraints. An instance reporting link capacity of 100 Gbps can be structurally valid while failing a request that requires available bandwidth measured over a particular window and no older than a specified age. Capacity and available bandwidth are not interchangeable merely because their values use the same unit. A generic client can validate and route the instance without understanding that distinction. A domain-aware orchestrator MAY reject it before delegation; otherwise, the downstream agent MUST enforce the window, scope, unit, and freshness constraints represented by fields in its input schema and supplied by the invocation. The component that detects the failure MUST reject the invocation with constraint_rejected.¶

10.1. Vendor release artifacts

Agent domain schemas are deployment-independent source artifacts. The standardized Skill Interface Schema is a separately versioned common artifact; an implementation packages an exact trusted copy rather than maintaining an agent-specific variation. A vendor release pipeline SHOULD:¶

1. validate all schemas;¶

2. test representative inputs and outputs against them;¶

3. assign stable schema URIs and versions;¶

4. compute schema digests;¶

5. when publishing a schema bundle, produce a bundle manifest; and¶

6. sign or otherwise integrity-protect any published schema bundle.¶

Producing a schema bundle is optional. A bundle, registry, or agent package may provide deployment-local source material for assembling a Skill Interface Document. Regardless of that source, the resulting v1.0 document contains the domain schemas inline. The release pipeline does not need access to a customer registry.¶

10.2. Agent initialization

Before advertising schema-interface support, an agent SHOULD:¶

1. load and integrity-check its packaged Skill Interface Schema;¶

2. load its domain input, output, and supporting-record schemas;¶

3. assemble a Skill Interface Document for each advertised skill version;¶

4. validate each document and each inline schema digest; and¶

5. calculate and retain the Skill Interface Document Digest for each immutable validated representation; and¶

6. advertise each skill version and digest through the schema-interface A2A extension.¶

Failure to load, assemble, or validate an interface prevents that skill version from being advertised through this framework. An implementation MUST NOT silently fall back to an opaque unconstrained payload.¶

12.1. Schema trust

A syntactically valid schema is not necessarily trustworthy. A client agent applies policy for trusted publishers, schema identities, digests, versions, and dialects.¶

12.2. Arbitrary retrieval

Following arbitrary schema URLs can expose a client agent to server-side request forgery, credential leakage, malicious redirects, and availability attacks. Version 1.0 Schema References contain inline schema content and MUST NOT direct the client agent to retrieve a schema from an arbitrary URL. Deployment-local schema-management tools that contact registries or other services remain subject to administrator-configured trust and network policy.¶

12.3. Resource limits

An implementation MUST enforce limits on schema size, nesting, reference depth, reference cycles, compilation time, payload size, and cache consumption. When an operation is rejected because one of these limits would be exceeded, the implementation MUST report the resource_limit_exceeded machine-readable condition defined in Section 9.5 through the applicable binding. The error response need not disclose the configured threshold or other sensitive implementation details.¶

Version 1.0 does not define numeric interoperability minima for these limits. A future interface version MAY define minimum supported capacities or maximum interoperable sizes for implementations that claim conformance to that version.¶

12.4. Schema validation and authorization

Schema validation establishes structural conformance, not caller authority, operational safety, truth, or permission to modify a network. The authority member of a Skill Interface Document is descriptive and MUST NOT be interpreted as a permission grant or evidence that an approval has been obtained.¶

At invocation time, the receiving agent or hosting platform MUST authenticate the caller and authorize the requested skill, resources, operation, and applicable constraints under current local policy. It MUST repeat or refresh the authorization decision when required by that policy before causing a side effect. A cached Skill Interface Document, successful schema validation, or a previous authorization decision MUST NOT substitute for a required current decision. A denied authentication, authorization, or required approval check MUST reject the invocation with the authorization_failed machine-readable condition defined in Section 9.5.¶

This document does not mandate an authorization model. Deployments may use RBAC, ABAC, capability-based authorization, external policy decision points, human or automated approval workflows, or another model that satisfies these runtime requirements.¶

12.5. Supporting-record integrity and provenance

Supporting records can be stale, replayed, forged, selectively omitted, or derived from untrusted inputs. A supporting-record schema SHOULD require the source, producer, relevant observation and production times, integrity data, derivation, and classification needed by its domain. Deployments define freshness and retention policy appropriate to the operation.¶

12.6. Injection

Text, CLI configuration, tool output, model output, and supporting-record payloads are untrusted data. An agent does not treat instructions embedded in those artifacts as authorized task instructions unless the applicable schema and policy explicitly assign them that role.¶

12.7. Interface integrity and substitution

The remote agent and client agent MUST integrity-check the packaged Skill Interface Schema before using it. A local implementation MUST NOT modify the standardized schema while adding domain schemas.¶

A client agent verifies that a retrieved Skill Interface Document identifies the requested agent skill and advertised skill version. It validates the document against the selected Skill Interface Schema, verifies all embedded schema digests, and verifies that the calculated Skill Interface Document Digest equals the value carried in the Agent Card and describe_skill response. A structurally valid document for a different skill, version, or digest MUST NOT be accepted as a substitute.¶

The receiving agent verifies that the skill_version and interface_digest carried by every domain-skill invocation identify its currently active Skill Interface Document before it validates or acts on the domain input. This check prevents a document change between interface retrieval and invocation from silently changing the contract applied to a request.¶

15.1. Normative References

[A2A]

"Agent2Agent Protocol Specification, Version 1.0.1", n.d., <https://a2a-protocol.org/v1.0.1/specification/>.

[JCS]

"JSON Canonicalization Scheme (JCS)", RFC 8785, n.d., <https://www.rfc-editor.org/rfc/rfc8785>.

[JSON-POINTER]

"JavaScript Object Notation (JSON) Pointer", RFC 6901, n.d., <https://www.rfc-editor.org/rfc/rfc6901>.

[JSON-SCHEMA]

"JSON Schema: A Media Type for Describing JSON Documents", n.d., <https://json-schema.org/draft/2020-12/json-schema-core.html>.

[JSON-SCHEMA-VALIDATION]

"JSON Schema Validation: A Vocabulary for Structural Validation of JSON", n.d., <https://json-schema.org/draft/2020-12/json-schema-validation.html>.

[RFC2119]

Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/rfc/rfc2119>.

[RFC8174]

Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.

[TIMESTAMP]

"Date and Time on the Internet: Timestamps", RFC 3339, n.d., <https://www.rfc-editor.org/rfc/rfc3339>.

15.2. Informative References

[IDL]

"IDL: A Semantic Information Model for Agent Communication", n.d., <https://datatracker.ietf.org/doc/draft-feng-agentproto-idl-info-model/>.