What Are Agent Schema Interfaces? The Beginner's Guide to Schema-Governed Skills for Network-Management Agents

CodexFuse Team · 2026-11-05T12:03:42.341Z · 31 min read min read

What Are Agent Schema Interfaces? The Beginner's Guide to Schema-Governed Skills for Network-Management Agents

Agent schema interfaces are the missing contract layer for agent-to-agent work: they let one agent fetch and validate the exact input and output schemas of another agent's skill before sending a single task. This guide answers the question what are agent schema interfaces in plain terms, and it walks through the four components a new IETF draft standardizes, how a client checks a skill before invoking it, and what the draft deliberately leaves out.

The draft is draft-huang-ainetops-agent-schema-interfaces-00, titled "Schema Interfaces for Network Management Agent Skills", published on November 2, 2026, by Scott Huang and Dan Voyer of Cisco Systems and Fu Yu of China Telecom. This guide was written on November 5, 2026, three days later, when the draft itself was the only page on the internet explaining the term.

The draft's trust model leans on fingerprints: every schema carries a SHA-256 digest, the same kind of fixed-length hash a SHA-256 hash generator produces for any text, so a client can prove the schema it received is the schema that was advertised. The agents in question manage networks — routers, links and capacity checks — which is the same infrastructure world where VPS hosting runs the servers those agents watch over.

This guide explains what the draft standardizes, how the four components fit together, how the describe_skill operation works, how a client validates a skill step by step, what happens when something goes wrong, and where the draft's scope ends.

What Are Agent Schema Interfaces?

Agent schema interfaces are a standardized way for a network-management agent to publish the exact input, output and supporting-record schemas of each of its skills, so that another agent can retrieve those schemas, check their fingerprints, and validate its request before invoking the skill. The definition comes from Internet-Draft draft-huang-ainetops-agent-schema-interfaces-00, published November 2, 2026, which standardizes four components that together make a skill's interface machine-readable.

The four components are:

1. Schema References — a common structure for identifying, verifying and carrying inline schemas.
2. Skill Interface Documents — one machine-readable document per skill version, describing that skill's accepted input, produced output, possible supporting records, interaction behaviour and applicable constraints.
3. Advertisement and retrieval through an A2A extension and describe_skill — a client asks an agent to describe a skill and gets the full interface document back.
4. The A2A mapping for interface version 1.0 — how domain-skill inputs, outputs, supporting records and machine-readable errors ride on existing A2A Messages, Data Parts, Tasks, Artifacts and status messages.

The point is not to add another chat protocol. A2A already moves tasks between agents. Agent schema interfaces answer the question A2A leaves open: what exactly does this skill expect, and what exactly will it return?

The draft is narrow on purpose. It defines a normative representation for one version of one callable skill, plus the procedure for fetching and validating that representation. It does not define a universal schema for all of networking, and it does not tell agents how to find each other.

One more status note belongs up front, because it shapes everything that follows. This is Internet-Draft revision -00, a work in progress with intended status Standards Track — an intent that is stated, not granted.

It is not an RFC, it is not an adopted standard, and it expires on May 6, 2027, which is 185 days after its November 2 publication date. It may be updated, replaced or obsoleted at any time.

The Problem: A2A Tells Agents How to Talk, Not What the Words Mean

Task exchange between agents needs agreement at two different layers. The first layer is a protocol for discovery, task identity, lifecycle, streaming, polling, cancellation and result transport. The second layer is the application schemas that define the meaning of a skill's input, output, deliverables and supporting records.

The Agent-to-Agent (A2A) protocol, version 1.0.1, defines the first layer. It does not define the second. The draft states the gap plainly: "A common protocol envelope can deliver a JSON object without making that object semantically interoperable." Two independently built agents can exchange tasks over A2A while still having to guess what each other's skill inputs and outputs mean.

That guesswork is visible in the Agent Card itself. An A2A Agent Card lists each skill with only an id, a name, a description, tags, examples, and input and output modes.

It carries no per-skill input or output JSON Schema. A client reading the card learns that a skill called check-link-capacity exists, but not which fields it wants, which units it expects, or what a valid answer looks like.

The draft's motivating scenario is agents from different vendors, administrative domains and model architectures cooperating to decompose, delegate, execute and verify complex operational tasks. Their exchanges include task objectives, operational context, constraints, diagnostic requests, supporting records and risk assessments.

When those agents govern artifacts through bilateral assumptions instead of declared, machine-readable per-skill interfaces, the draft says end-to-end workflows become "fragile, difficult to reproduce, and difficult to audit".

Opaque text and unconstrained JSON are not an adequate substitute for a declared interface when agents make operational decisions or generate network changes. A field named "threshold" might be a percentage, a count, or a ratio, and a field named "value" might be observed, requested, or projected.

Nothing in the envelope tells the receiver which one it is. Protocols that carry agent messages across transports, such as what MCP over MOQT is, solve the transport half of the same problem — getting the message there — while agent schema interfaces solve the meaning half.

Agent Schema Interfaces Explained: The Four Standardized Components

Agent schema interfaces explained in one paragraph: the draft standardizes a fingerprint for every schema, a document that bundles a skill's schemas together, a way to advertise and fetch that document over A2A, and a mapping that carries skill data on ordinary A2A messages without changing A2A itself. The agent schema interfaces IETF draft is revision -00 of a 44-page document with 15 sections and two appendices, and the table below maps its four components to their jobs.

The first component, Schema References, gives every schema a portable identity. A reference carries a stable schema URI, a version, a dialect — JSON Schema draft 2020-12 in version 1.0 — a digest of the embedded schema content, and the schema itself, delivered inline. Identity and digest are independent of any deployment-local schema registry, so the same reference means the same thing on any system.

The second component, Skill Interface Documents, is the heart of the draft. Each document is an instance of a standardized Skill Interface Schema, describing one version of one skill: its accepted input, produced output, possible supporting records, interaction behaviour and applicable constraints. The agent assembles the document from its domain schemas plus a trusted copy of the standardized schema, validates it, and only then advertises it.

The third component is the retrieval procedure. A conforming agent advertises the schema-interface extension and a describe_skill skill in its Agent Card. A client that wants to use a skill first calls describe_skill, receives the full Skill Interface Document, and verifies it — including a three-way digest check described in the sections below.

The fourth component is the mapping. It pins domain-skill inputs, outputs, supporting records and machine-readable errors onto existing A2A constructs, without changing A2A operations, data objects, lifecycle semantics or protocol bindings. An implementation claiming conformance to interface version 1.0 over A2A must use this mapping.

What Is a Skill Interface Document?

A Skill Interface Document is a machine-readable description of one version of one skill, and it is the document a client fetches before it delegates anything. It binds the domain schemas to the skill's input, output, supporting-record, interaction and authority characteristics, and it is an instance of the standardized Skill Interface Schema published alongside the draft.

The document has nine required top-level members, listed in the table below. The first three identify the interface itself; the next three carry the domain schemas; the last three describe how the skill behaves and what posture it advertises.

The version rules are strict and simple. A version string is two dot-separated non-negative integers with no leading zero unless the value is zero, as in "1.0".

A breaking change increments the major version and resets the minor to zero; a backward-compatible change increments the minor. The Skill Interface Schema version itself is separate and fixed at 1.0 in this document.

The interaction member declares the response modes the skill supports — sync, stream or poll — and whether a running invocation can be cancelled. The authority member declares a default mode, one of exactly three values: observe_only, which reads and analyzes without proposing or applying a change; recommend_only, which may produce a proposed action or change but does not apply it; and execute, which may cause an operational side effect.

Authority is descriptive, not permission. A default_mode of execute does not grant the caller permission to use that mode, and approval_may_be_required only indicates that approval may apply — it does not assert approval was requested, granted or remains valid.

Authority is not a credential, a capability, an entitlement, an access-control decision, an approval record or an authorization token, and a client must not treat it as permission to execute a skill or cause a side effect.

One operation per skill is preferred. The draft permits a single skill to cover multiple operations, but the authors recommend exposing operations with materially different effects or approval requirements as separate skills.

An agent that can read and delete a managed resource should advertise separate read_resource and delete_resource skills, or one manage_resource skill whose input schema requires an operation selector of read or delete, with approval_may_be_required set to true if deletion may require approval.

Schema References: Identity, Version and a SHA-256 Fingerprint for Every Schema

A Schema Reference is the draft's answer to a simple question: how does a client know it is looking at the schema it thinks it is looking at? The answer is a portable identity plus a fingerprint, carried with the schema content itself. One Schema Reference structure serves every schema role — input, output and supporting records — with no different structures or delivery mechanisms per role.

Each reference carries five members. The schema_uri is the stable, portable identity of the schema. The version is meaningful to the schema publisher.

The dialect names the schema language and version — in interface version 1.0, that is JSON Schema draft 2020-12. The digest is a fingerprint of the embedded schema content. The resolution member carries the content itself, inline, in version 1.0.

The digest algorithm in version 1.0 is SHA-256 only, with no negotiation. The schema value is serialized with the JSON Canonicalization Scheme (RFC 8785), encoded as UTF-8, hashed with SHA-256, and written as the string "sha256:" followed by exactly 64 lowercase hexadecimal characters.

Sixty-four hex characters at four bits each make a 256-bit fingerprint. Whitespace, member order and permitted alternate string escapes do not change the digest, because canonicalization normalizes them away; a change to the JSON value does.

Crucially, the digest covers only the schema content in resolution.schema — not the reference's type, URI, version or dialect. The whole Schema Reference must be compared when checking identity, not the digest alone. And the Skill Interface Document Digest covers the entire document, including each reference's identity, version, dialect, digest and inline content, so it also detects metadata modification or substitution.

That document digest is the string "sha256:" plus the lowercase hex of the SHA-256 digest of the complete Skill Interface Document, serialized with JCS. It covers every member of the document, including the inline domain schemas, and it is carried outside the document — a document cannot contain a digest of itself. The same digest must appear in three places and match the value calculated from the returned document: the Agent Card extension advertisement, the describe_skill response, and each domain-skill invocation that uses the document.

In version 1.0, every Schema Reference returned by describe_skill must carry its schema content inline. The client validates the embedded content against the declared digest and does not contact an external service to complete the interface. That design choice is a security decision as much as a simplicity one: following arbitrary schema URLs could expose a client to server-side request forgery, credential leakage, malicious redirects and availability attacks, and version 1.0 removes that surface entirely.

How describe_skill Works in A2A

The describe_skill A2A operation turns an advertised skill into a validated contract. It is an A2A skill like any other, except that its job is to hand over the interface document for a domain skill instead of doing network work. The exchange runs in four steps.

1. The agent advertises the schema-interface extension and the describe_skill skill in its Agent Card, with the extension parameters naming interface_version "1.0" and a skills array of skill_id, skill_version and interface_digest entries.
2. The client selects the advertised skill_id, skill_version and interface_digest before calling describe_skill, and activates the extension — over HTTP, by including the extension URI in the A2A-Extensions request header.
3. The client sends a user-role A2A Message with exactly one Data Part whose data is {"skill": "describe_skill", "arguments": {"skill_id": "example_skill"}}.
4. The agent returns a completed task containing exactly one Artifact named describe_skill, whose single Data Part carries the full Skill Interface Document and its interface_digest.

The extension URI is https://agentic-network-management.github.io/agent-schema-interfaces/extensions/schema-interface/v1. The extension may be marked required: false, so clients that do not understand it can keep using base A2A. A client that uses this procedure must activate the extension for describe_skill and for domain-skill requests.

The response must be the previously assembled and validated document for the selected skill version. Describe_skill does not redefine the standard structure, and it does not invoke domain logic to construct or modify the document while processing the request. The document should have been assembled and validated at initialization or deployment, and retained as an immutable validated document per skill version.

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.

Two name collisions deserve a warning. First, describe_skill as the draft defines it is an A2A skill operation; it has nothing to do with Dify's unrelated difyctl describe skill command, which is the only similarly named hit in web search.

Second, version 1.0 permits exactly one advertised skill_version and interface_digest binding per skill_id in an Agent Card, and it defines no in-band negotiation for another version inside describe_skill. An agent needing concurrent incompatible versions must expose them under distinct skill identifiers, and a client must not infer a version range or negotiate an unadvertised version.

Absence means no conformance. If the Agent Card lacks the schema-interface extension or the describe_skill skill, the agent does not provide this procedure.

Such an agent may still be invoked through base A2A or an explicitly configured out-of-band contract, but the caller must not infer or prescribe its domain schemas from skill descriptions or media types alone, and must not claim schema-interface conformance for that invocation.

How a Client Validates a Skill Before Invoking It

The draft defines an eleven-step client validation sequence, and the gate rule behind it is absolute: before delegating a domain skill under this framework, the client must possess a successfully validated Skill Interface Document obtained from that target's describe_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 must not delegate using this procedure.

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, then select the advertised skill_version and interface_digest.
3. Call describe_skill for the selected skill_id, using the version 1.0 A2A mapping.
4. Verify the returned interface_digest equals the advertised value, calculate the digest of the returned document, and verify the calculated value equals it too.
5. Validate the returned document against a trusted local copy of the version 1.0 Skill Interface Schema, and verify interface_version is "1.0" and that 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 A2A, carrying the selected skill_version and interface_digest in the skill request.
9. Receive task status, the typed skill output and any supporting records, as the mapping defines.
10. Validate the skill output against output_schema and validate the supporting records.
11. Preserve, forward, display or interpret the results according to local policy.

That sequence is deliberately mechanical. A generic client can validate and route an unfamiliar vendor schema without understanding its domain semantics: it checks digests, versions and structure, and leaves meaning to the schema itself. A domain-aware orchestrator may additionally install handlers keyed by stable schema URI, to evaluate thresholds, incident records, configuration policy or other domain behaviour.

Clients do not repeat the describe_skill exchange for every task. A client may reuse a cached Skill Interface Document when the cache entry is bound to the same target identity, skill id, skill version and interface digest advertised by the current Agent Card. A change to any of those values invalidates the entry and requires a fresh describe_skill exchange, which keeps a stale interface from quietly surviving a redeployment.

Validation is not authorization, and the draft says so at every level. Successful schema and interface validation does not authorize execution. Before processing an invocation, the receiving agent or hosting platform must authenticate the caller and make a current authorization decision covering the requested skill, resources, operation and constraints.

Before causing a side effect it must enforce the approval and execution-control requirements of current deployment policy. A cached document, a successful validation or a previous authorization must not substitute for a required current decision.

Invoking a Skill: Inputs, Outputs and Supporting Records

Once the document is validated, the client invokes the domain skill with an A2A Send Message or Send Streaming Message. The user-role Message contains exactly one Data Part, and its data is the skill request object: the skill name, the skill_version and interface_digest selected from the Agent Card, and the arguments object carrying the complete domain input.

Before validating the arguments or invoking domain logic, the receiving agent must compare the skill_version and interface_digest in the request with its currently active Skill Interface Document. If either differs, it rejects the invocation with interface_mismatch.

That check prevents a document change between retrieval and invocation from silently changing the contract. The arguments must then validate against input_schema, and the receiving agent must reject nonconforming input with input_invalid before invoking domain logic.

Outputs and supporting records are kept strictly separate. The output states what the agent concluded or delivered; supporting records explain why it can be trusted, reproduced or audited.

The primary result Artifact carries the final skill output, is named with the selected skill id, and contains a single Data Part with the skill result object. Each supporting record is a separate Artifact, named with the record kind declared in supporting_record_schemas, and a record kind must never equal the skill id — so a supporting record can never be confused with the primary result.

An output that depends on a supporting record should reference that record's task-scoped artifactId rather than duplicate its content. The artifactId identifies an Artifact within one A2A Task; it is not a globally portable record identifier. The domain output schema should define where the output carries those references.

Not every exchange in a task is schema-validated, and the draft's own Table 1 draws that boundary precisely. The table below restates it.

Streaming follows the same boundary. A supporting record may be streamed as a complete Artifact before the primary result Artifact, and each validates independently against its declared schema. The output schema applies to the complete final result after streamed Artifact updates are assembled, not to status messages, progress updates or incomplete chunks, and version 1.0 defines no separate streaming-output schema.

The input-required case is worth spelling out, because it surprises people. If a task enters TASK_STATE_INPUT_REQUIRED, a follow-up message may contain only the requested information — for example, one missing credential reference.

Version 1.0 defines no schema for such follow-up data, and it is not independently validated against input_schema. A deployment that needs schema-governed multi-turn input needs an additional profile or a separately advertised skill.

If the receiving agent delegates to another agent mid-sequence, that creates a distinct downstream A2A Task. Task identifiers are scoped to the issuing agent and endpoint and must not be assumed globally unique, so the delegating component must never reuse the upstream task identifier as the downstream one. It records the upstream-to-downstream association, qualified by agent identities and endpoints, and correlation fields such as workflow_id, step_id or parent_a2a_task_id may be used when the domain schema defines them.

When Something Goes Wrong: The 10 Machine-Readable Error Codes

When a schema-governed invocation fails, the failure is machine-readable. The task's final status Message contains exactly one Data Part whose data is an error object with a code and an optional human-readable message. The code must be one of ten conditions defined by the draft, listed in the table below.

The terminal task state depends on when the failure happens. TASK_STATE_REJECTED is used when the request is understood but not accepted for execution — interface_mismatch, input_invalid, constraint_rejected and authorization_failed.

TASK_STATE_FAILED is used when an accepted operation cannot complete, including a describe_skill call that cannot produce a valid advertised interface, or domain processing that cannot produce valid output. A resource limit is REJECTED if checked before acceptance and FAILED if reached during processing.

Interface_invalid and input_invalid are easy to confuse, and the draft draws the line carefully. Interface_invalid means 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 — those cases use input_invalid, output_invalid or constraint_rejected.

Errors detected locally by a client before the remote agent creates a task must not be represented as the state of a nonexistent remote task. The client must stop the procedure and report the condition locally or through its enclosing system's error mechanism. Skill_not_advertised is detectable by the client before sending describe_skill, and a client must not send the request when the Agent Card does not advertise the selected skill.

For input_invalid and output_invalid, the error may carry an optional details array. Each entry must contain instance_path, a JSON Pointer identifying the invalid field, and may contain schema_path, keyword, expected and actual.

The draft's worked example reports a threshold that must be numeric: instance_path "/threshold", keyword "type", expected "number", actual "string". Diagnostic details must not disclose credentials, sensitive policy state, input values prohibited by local security policy, or information the caller is not authorized to receive.

One final rule closes the loop on outputs. The receiving agent must validate domain output before reporting TASK_STATE_COMPLETED, and invalid output produces output_invalid with 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, because it cannot retroactively change the remote task state.

Chaining Skills: Why Two Matching Schemas Must Match Exactly

Skills chain when one skill's output becomes another skill's input. The component that starts the downstream delegation is the client agent for that interaction, whether it is a centralized orchestrator or the upstream agent itself. The downstream delegation creates a new A2A Task with its own task id, and the delegating component retains the upstream and downstream task ids as distinct values, with a correlation mapping for observability, audit and troubleshooting.

Direct composition under this specification requires an exact match. The Schema Reference for the transferred upstream output payload and the Schema Reference accepted for the corresponding downstream input must have the same four fields, listed in the table below. Because version 1.0 carries schemas inline, the delegating component also verifies each embedded schema against its declared digest.

If the references do not match, the component must not perform direct composition under this specification. The rule is intentionally conservative. Two schemas can be structurally similar, or both accept the same instance, while assigning different meanings, units, defaults, constraints or operational consequences to the same fields.

Inferring compatibility from shape or successful validation alone could connect semantically divergent interfaces.

The draft's worked example makes the point concrete. An input schema can define a network measurement with a metric, a value, a unit, an observation window, an 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.

Comparing complete portable identity plus content digest gives a deterministic composition decision without 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. If the references do not match, an out-of-band transformation mechanism may be used before delegation, but transformation discovery, trust, execution and provenance are outside the scope of the draft, and any resulting payload enters as a new input subject to ordinary input_schema validation.

Matching references plus successful instance validation establish structural compatibility, not operational correctness. The orchestrator or delegating agent must validate the transferred instance mechanically against the downstream input schema before delegation, the receiving agent must validate it before processing, and the receiving agent remains responsible for domain-semantic validation, authorization, policy evaluation and operational safety.

Structural conformance and semantic conformance are different things, and the draft says so explicitly. Matching Schema References proves agents use the same schema; it does not prove the schema exposes sufficient semantics for the intended operation. A schema defining a configuration only as a string can validate the string's presence and type, but cannot identify affected resources, validate command dependencies, or establish that commands implement the requested intent.

What Agent Schema Interfaces Are NOT (Scope and Limits)

The draft is as careful about what it does not define as about what it does, and the boundary is worth stating plainly. It standardizes four things: a common Schema Reference structure, a Skill Interface Schema and conforming per-skill Skill Interface Documents, an advertisement and retrieval procedure using an A2A extension and describe_skill, and an A2A mapping for interface version 1.0. Everything else is either a domain owner's job or another specification's job.

The eight items the draft explicitly does not define are:

• The internal algorithm used by an agent to perform a skill.
• A universal schema for every network-management domain.
• A required schema-registry product or API, or a globally centralized schema service.
• Agent hosting, process lifecycle or platform onboarding.
• An authorization policy model, such as RBAC, ABAC, capabilities, policy engines or approval workflows.
• A grant of authority based on schema or interface validation.
• A new A2A transport or protocol binding.
• How agents are found, selected, ranked or matched to user intent.

That last item is the most commonly misunderstood. Agent discovery determines which agent to contact and how to reach it; the schema-interface procedure happens after an agent has been identified, and it provides the machine-readable interface for invoking one of its advertised skills. The draft does not define how agents are found, selected, ranked or matched to user intent, and it should never be described as an agent-discovery or agent-selection mechanism.

It is also not a universal schema. Each network-management domain — planning, assurance, configuration, incident analysis — owns the meaning of its skill inputs, outputs and supporting records.

A domain is a schema-governance boundary, not a global namespace for skill identifiers, and a skill identifier is scoped to the Agent Card it is advertised in rather than globally unique. The framework standardizes reusable interface metadata, not the semantics of every domain.

A related specification, the IDL draft on a semantic information model for agent communication, describes agent-wide identity, capabilities, autonomy boundaries, context requirements, governance interfaces and intent participation, with optional input-context and output-schema declarations.

It does not define a normative serialization or a per-skill interface-retrieval procedure. This draft is narrower: one version of one callable skill, plus the describe_skill procedure. The two models can be used together, and a formal mapping between them is outside the scope of this document.

Two more distinctions prevent expensive confusion. First, Anthropic-style agent skills — SKILL.md instruction packages for coding agents — are a different, unrelated concept that shares the word "skill". Those are Markdown instructions that teach a coding agent a procedure; the draft's skill is an A2A-advertised capability with a machine-readable JSON interface.

If you have used coding agents, how to use Claude Code covers the coding-agent side of the word, and it is a different world from the network-management skills this draft governs.

Second, the draft requests no IANA actions in this version. No identifiers for Skill Interface versions, media types or URN namespaces have been assigned, and a later version may request them only after the representation and protocol mapping stabilize. There is also no adoption to report: the draft names no implementations, products or deployments, and none should be claimed for it.

Worked Example: Checking a Network Resource the Schema-Governed Way

The draft's Appendix B walks through one skill end to end, and it is the clearest way to see schema governed agent skills in practice. The skill is evaluate_resource_condition: it evaluates whether an observed resource metric satisfies a caller-supplied threshold, and returns the observation as a supporting record. Every number in this section is the draft's own illustrative example, not a real-world measurement.

The Agent Card advertises describe_skill, the evaluate_resource_condition skill, and the extension with interface_version "1.0" and skill_version "1.0". The client activates the extension, calls describe_skill with the skill id, and receives the full Skill Interface Document.

The document's input schema requires a resource_id string and a condition object with a metric, an operator of gt, gte, lt or lte, a numeric threshold and a unit. Its output schema requires a result of condition_met or condition_not_met, an observed_value number, a unit, and a supporting_record_refs array of at least one string.

The client then invokes the skill with resource_id "network-resource-123" and a condition of utilization, operator gte, threshold 80, unit percent. The completed task contains two Artifacts.

The primary result Artifact, named evaluate_resource_condition, carries a result of condition_not_met, an observed_value of 42, the unit percent, and a supporting_record_refs entry pointing at observation-7. The supporting-record Artifact, named resource-observation, carries the record itself: record_id observation-7, the same resource and metric, value 42, unit percent, and observed_at 2026-08-11T12:00:01Z.

The arithmetic is the whole story in miniature. The observed utilization of 42 percent sits 38 points below the threshold of 80 percent — it reached only 52.5 percent of the required level — so the result is condition_not_met. Nothing about that conclusion is a guess: the input validated against the input schema, the output validated against the output schema, the record validated against its own schema, and the result references the record by artifactId instead of duplicating it.

The failure notes in the appendix are as instructive as the success path. A missing unit in the input, an output result outside the declared enum, or a record missing its observed_at timestamp each fails domain-schema validation.

A digest mismatch makes the interface invalid and prevents delegation entirely. The interface is the contract, and the contract is checked before anything is trusted.

Before pointing a new skill at a production network, teams test it in an isolated sandbox rather than on live infrastructure, and how to use E2B covers that pattern for agent code.

Sources

IETF Internet-Draft draft-huang-ainetops-agent-schema-interfaces-00, "Schema Interfaces for Network Management Agent Skills" (Huang, Yu, Voyer, November 2, 2026) — the primary source for every draft fact in this article, read in full on November 5, 2026.

Same draft, plain-text version — used for the table of contents, front matter and page numbers.

Draft source repository and issue tracker — linked from the draft; the Skill Interface JSON Schema is published there as schemas/skill-interface-v1.json.

Agent2Agent Protocol Specification, Version 1.0.1 — the A2A specification the draft cites and maps onto.

JSON Schema draft 2020-12 — the draft's schema dialect for all Schema References.

RFC 8785, JSON Canonicalization Scheme (JCS) — the canonicalization used for schema and document digests.

RFC 6901, JSON Pointer — the instance_path format used in error details.

RFC 3339, Date and Time on the Internet: Timestamps — the date-time format the draft requires for format assertions in version 1.0.

Web searches on November 5, 2026, for the exact term "agent schema interfaces", for "describe_skill" in A2A, and for "skill interface document" found no independent explainer of this draft. The draft itself is the only source for the exact term, and the nearest neighbouring content is A2A Agent Card explainers and Anthropic-style agent-skills guides, which describe different concepts.

Frequently Asked Questions

What are agent schema interfaces?

Agent schema interfaces are the four components of IETF draft-huang-ainetops-agent-schema-interfaces-00 that let an A2A client retrieve and validate the application schemas for a skill's inputs, outputs and supporting records. The components are Schema References, per-skill Skill Interface Documents, advertisement and retrieval through an A2A extension and describe_skill, and the A2A mapping for interface version 1.0. Together, they let a client check exactly what a skill expects and returns before invoking it.

What is a Skill Interface Document?

A Skill Interface Document is a machine-readable, per-skill-version document — an instance of the standardized Skill Interface Schema — describing a skill's accepted input, produced output, possible supporting records, interaction behaviour and constraints. It has nine required members: interface_version, skill_id, skill_version, input_schema, output_schema, supporting_record_schemas, interaction and authority. It is identified by its skill id and version and verified by its SHA-256 interface_digest, which is the string "sha256:" plus 64 lowercase hex characters.

How does describe_skill work in A2A?

The client reads the Agent Card, selects the advertised skill version and interface digest, and calls the describe_skill skill with {"skill": "describe_skill", "arguments": {"skill_id": "..."}}. The agent returns the full Skill Interface Document plus its interface_digest in a single Artifact named describe_skill. The client then verifies the digest three ways — the Agent Card value, the describe_skill response value, and a digest it calculates itself from the returned document — before delegating the domain skill.

Is the agent schema interfaces draft an official IETF standard?

No. It is Internet-Draft revision -00, published November 2, 2026, with intended status Standards Track — an intent that is stated, not granted.

It is a work in progress that expires on May 6, 2027, and it may be updated, replaced or obsoleted at any time. It should be cited only as a draft, never as an RFC or an adopted standard.

How are agent schema interfaces different from Anthropic agent skills (SKILL.md)?

Anthropic-style agent skills are Markdown instruction packages that teach a coding agent a procedure. IETF agent schema interfaces are machine-readable JSON Schema contracts, advertised in an A2A Agent Card and fetched through describe_skill, that let one network-management agent validate another agent's skill inputs and outputs before invoking it. They share the word "skill" and little else: one is a set of instructions for a coding agent, the other is a verifiable contract between two agents.