Virtualized Conversations D. G Petrie Internet-Draft SIPez LLC Intended status: Standards Track 2 November 2026 Expires: 6 May 2027 The JSON vCon - Tool Invocation Extension draft-petrie-vcon-tool-invocation-00 Abstract A vCon is a container for data and information relating to a conversation. This document defines an extension to the JSON vCon schema for recording the policy decisions of AI agents and their invocation of tools. Before an agent performs an operation, the agent or its host uses policy to decide whether the operation is allowed, disallowed or requires permission. This document defines an Event Object type for those decisions, and Event Object types for each step of a tool invocation. It also outlines requirements for recording requests for permission and direction, which need to be defined in a future document. About This Document This note is to be removed before publishing as an RFC. The latest revision of this draft can be found at https://dgpetrie.github.io/draft-petrie-vcon-tool-invocation/draft- petrie-vcon-tool-invocation.html. Status information for this document may be found at https://datatracker.ietf.org/doc/draft- petrie-vcon-tool-invocation/. Discussion of this document takes place on the Virtualized Conversations Working Group mailing list (mailto:vcon@ietf.org), which is archived at https://mailarchive.ietf.org/arch/browse/vcon/. Subscribe at https://www.ietf.org/mailman/listinfo/vcon/. Source for this draft and an issue tracker can be found at https://github.com/dgpetrie/draft-petrie-vcon-tool-invocation. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Petrie Expires 6 May 2027 [Page 1] Internet-Draft vCon Tool Invocation Extension November 2026 Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on 6 May 2027. Copyright Notice Copyright (c) 2026 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/ license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Conventions and Definitions . . . . . . . . . . . . . . . . . 4 2.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 3. Extension Name . . . . . . . . . . . . . . . . . . . . . . . 5 4. Policy Decision State Model . . . . . . . . . . . . . . . . . 6 4.1. Policy Decisions . . . . . . . . . . . . . . . . . . . . 7 5. Tool Invocation State Model . . . . . . . . . . . . . . . . . 8 5.1. Attempts . . . . . . . . . . . . . . . . . . . . . . . . 12 6. Parameter Definitions . . . . . . . . . . . . . . . . . . . . 12 6.1. Event Object Types and Parameters . . . . . . . . . . . . 12 6.1.1. Event Object Parameter Applicability by Type . . . . 13 6.1.2. operation_id . . . . . . . . . . . . . . . . . . . . 17 6.1.3. attempt . . . . . . . . . . . . . . . . . . . . . . . 17 6.1.4. decision . . . . . . . . . . . . . . . . . . . . . . 18 6.1.5. policy_life . . . . . . . . . . . . . . . . . . . . . 18 6.1.6. reason . . . . . . . . . . . . . . . . . . . . . . . 18 6.1.7. operation . . . . . . . . . . . . . . . . . . . . . . 19 6.1.8. server . . . . . . . . . . . . . . . . . . . . . . . 19 6.1.9. tool . . . . . . . . . . . . . . . . . . . . . . . . 20 6.1.10. Event Content . . . . . . . . . . . . . . . . . . . . 20 Petrie Expires 6 May 2027 [Page 2] Internet-Draft vCon Tool Invocation Extension November 2026 6.1.11. attachment . . . . . . . . . . . . . . . . . . . . . 21 7. Requirements for Permission and Directive Events . . . . . . 21 8. Compatibility Considerations . . . . . . . . . . . . . . . . 22 9. Incompatibility Considerations . . . . . . . . . . . . . . . 22 10. Privacy and Integrity Considerations . . . . . . . . . . . . 23 11. Security Considerations . . . . . . . . . . . . . . . . . . . 23 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23 12.1. vCon JSON Registry Additions . . . . . . . . . . . . . . 23 12.1.1. vCon Extensions Names Registry . . . . . . . . . . . 24 12.1.2. Event Type Name Registry . . . . . . . . . . . . . . 24 12.1.3. Event Object Parameter Names Registry . . . . . . . 25 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 27 13.1. Normative References . . . . . . . . . . . . . . . . . . 27 13.2. Informative References . . . . . . . . . . . . . . . . . 27 Appendix A. Mapping to MCP . . . . . . . . . . . . . . . . . . . 28 Appendix B. Example vCons . . . . . . . . . . . . . . . . . . . 30 Appendix C. JSON Schema for the tool-invocation Extension . . . 30 Appendix D. CDDL for the tool-invocation Extension . . . . . . . 39 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 43 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 43 1. Introduction This document adds Event Object types for recording the policy decisions of AI agents and their invocation of tools to the JSON [JSON] vCon schema defined in [VCON-CORE]. The general framework and requirements for defining an extension to the JSON vCon schema are defined in [VCON-CORE]. AI agents converse with people and other agents, and perform operations on their behalf (e.g. invoking tools). The conversation between an agent and a person or another agent is captured with Dialog Objects in [VCON-CORE]. The use of a tool by an agent is not dialog. It is a request to the tool and one or more responses from it, which are captured in this document as Event Objects. This fills the gap for tool invocations and results identified in [ROADMAP], and covers the agent view of an Action Record in [AUDIT-ARCH]. Before an agent performs an operation (e.g. invoking a tool), the agent or its host decides by policy whether the operation may be performed. The decision is that no permission is needed, that permission is required or that the operation is disallowed. No one is asked, so there is no conversation, only the decision and what it applies to. The policy decision is defined in this document because the invocation of a tool is the most common operation it applies to, and the decision is part of the life cycle of a tool invocation. Its Petrie Expires 6 May 2027 [Page 3] Internet-Draft vCon Tool Invocation Extension November 2026 outcome determines whether the tool is invoked, and it identifies the tool by the same parameters as the invocation. Without it, a use of a tool which was disallowed, or for which permission was not granted, would leave no record. The decision is defined so that it can also apply to other operations (e.g. delegating to another agent). This document defines a state model for the policy decision (see Section 4) and a state model for a tool invocation (see Section 5), with an Event Object type for each transition in them. The Event Object types are not specific to any one protocol. The Model Context Protocol [MCP] is used as the first example, and a mapping to it is given in Appendix A. The word "invocation" is used rather than "call", as "call" in vCon commonly implies a telephone call. Requests for permission or direction made to the person or agent on whose behalf the agent is acting, and their responses, are not defined in this document. They are part of the conversation, and occur outside tool invocations as well as within them (e.g. a clarifying choice put to a person, approval to delegate to another agent, and in contact centers, consent to record and IVR menu choices). Event Object types for them need to be defined in a future document. The requirements identified so far are outlined in Section 7. The following are also not in the scope of this document: * The definition of tools and of the tools available to an agent. This document assumes that tools are defined elsewhere and only records their use. * Making or enforcing the policy decision. Only the decision is recorded. * The record of the invocation kept by the tool or its provider. This is another observation point, which may be captured in the same vCon, in a separate vCon or in a log (see [ROADMAP]). * The protocol used to invoke the tool. Only the data exchanged and the outcome of the invocation are captured. 2. Conventions and Definitions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. Petrie Expires 6 May 2027 [Page 4] Internet-Draft vCon Tool Invocation Extension November 2026 2.1. Terminology See section 2.1 of [VCON-CORE] for terminology used in this document. Agent: A party that acts on behalf of a person or another agent and that performs operations, such as invoking tools. TODO: align with the definition in [ROADMAP]. Host: The software in which an agent runs and through which it sends requests to tools. The host may itself provide tools, and is then a server. Server: The provider of a set of tools (e.g. an [MCP] server, or the host). Tool: A named function or service which an agent may invoke. A tool is not a party in the vCon. Operation: An action which an agent performs, and to which a policy decision applies (e.g. the invocation of a tool). Policy Decision: The decision made by the agent or its host, by policy, whether an operation may be performed. Invocation: The use of a tool by an agent, which is one kind of operation, consisting of one or more attempts. Attempt: A single request sent to a tool for an invocation, and the responses to that request. 3. Extension Name The extension name for this document is "tool-invocation". A vCon that contains any of the Event Object types defined in this document SHOULD include "tool-invocation" in the extensions parameter. "tool-invocation" is not required in the critical parameter (see Section 8). TODO: revisit whether "tool-invocation" is required in the critical parameter, pending Section 9. Petrie Expires 6 May 2027 [Page 5] Internet-Draft vCon Tool Invocation Extension November 2026 4. Policy Decision State Model Before an operation is performed, the agent or its host makes a policy decision whether it may be performed. When the decision is made for that operation alone, it is recorded as a "policy-decision" type Event Object (see Section 4.1). If the operation is allowed, or permission is required and is granted, the operation is performed. For a tool invocation, the next Event Object is then the "tool- invocation" type Event Object (see Section 5). If the operation is disallowed, or permission is required and is not granted, the operation is not performed. The state before an operation is set by the policy decision which applies to it: a "policy-decision" type Event Object for that operation alone, or a standing decision in effect for it (see Section 4.1). An operation covered by a standing decision has no "policy-decision" type Event Object of its own. When no policy decision for an operation was observed (e.g. by an observer at the tool), the vCon contains no "policy-decision" type Event Object for it. The policy decision follows the state model shown in Figure 1. policy-decision | +---------------------+----------------------+ | allowed | permission-required | disallowed v v v +---------+ +---------------------+ +------------+ | Allowed | | Permission Required | | Disallowed | +---------+ +---------------------+ +------------+ | | (1) +---------------------+ v operation is performed (e.g. tool-invocation) (1) permission granted (see Requirements for Permission and Directive Events) Figure 1: Policy Decision States The states are: * Allowed - the policy decision is that no permission is needed * Permission Required - the policy decision is that permission is required before the operation is performed Petrie Expires 6 May 2027 [Page 6] Internet-Draft vCon Tool Invocation Extension November 2026 * Disallowed - the policy decision is that the operation is disallowed, and it is not performed The following table defines the transitions. +======================+===========================+===============+ | From State | Event Object | To State | +======================+===========================+===============+ | (before the | policy-decision, decision | Allowed | | operation) | "allowed" | | +----------------------+---------------------------+---------------+ | (before the | policy-decision, decision | Permission | | operation) | "permission-required" | Required | +----------------------+---------------------------+---------------+ | (before the | policy-decision, decision | Disallowed | | operation) | "disallowed" | | +----------------------+---------------------------+---------------+ | Allowed | the operation (e.g. tool- | (operation is | | | invocation) | performed) | +----------------------+---------------------------+---------------+ | Permission Required, | the operation (e.g. tool- | (operation is | | when permission is | invocation) | performed) | | granted | | | +----------------------+---------------------------+---------------+ Table 1: Policy Decision State Transitions The request for permission and the response are not defined in this document (see Section 7). When permission is not granted, the operation is not performed, and for a tool invocation no "tool- invocation" type Event Object follows. The Event Objects of this document alone do not distinguish permission refused, from no response, from a response which was not observed. 4.1. Policy Decisions The policy decides whether a decision applies to one operation only or is standing. A decision for one operation applies only to that operation, and is recorded before the operation is performed. It is recorded as a "policy-decision" type Event Object with the policy_life parameter "once" and the operation_id of the operation. Depending upon the policy, a decision for one operation may be made before any attempt of it, and is then recorded before that attempt with its attempt number. Petrie Expires 6 May 2027 [Page 7] Internet-Draft vCon Tool Invocation Extension November 2026 A standing decision applies to all later operations of the same kind and target. For a tool invocation, the target is a tool, or all of the tools of a server when no tool is named. It is recorded as a "policy-decision" type Event Object with the policy_life parameter "standing" and no operation_id. Operations covered by a standing decision have no "policy-decision" type Event Object of their own. A standing decision applies until a later "policy-decision" type Event Object for the same operation and target replaces it, or until the end of the vCon. When a host starts a new vCon while standing decisions from an earlier vCon are still in effect, it SHOULD record a "policy-decision" type Event Object for each of them at the start of the new vCon. TODO: how a standing decision for one tool and a standing decision for all of the tools of the same server interact (e.g. which applies when both are in effect). 5. Tool Invocation State Model A tool invocation starts with a "tool-invocation" type Event Object, after any policy decision which applies to it (see Section 4). The invocation, and each attempt of it, follows the state model shown in Figure 2. Each transition is recorded as an Event Object of the type that labels it. Petrie Expires 6 May 2027 [Page 8] Internet-Draft vCon Tool Invocation Extension November 2026 tool-invocation (attempt n) <- - - - - - - - - -+ | . +- Active ------------------|-------------------------------+ . | +- Working ---------------|-----------------------------+ | . | | v | | . | | +-----------+ tool-pending +-----------+ | | . | | | Running |----------------->| Pending | | | . | | +-----------+ +-----------+ | | . | | ^ | | ^ | | . | | (2) | | (1) (1) | | (2) | | . | | | v v | | | . | | +----------------------------------------+ | | . | | | Input Required | | | . | | +----------------------------------------+ | | . | +-------------------------------------------------------+ | . | | | | . | | tool-timeout | tool-cancel | . | v v | . | +-----------+ tool-cancel +------------------+ | . | | Timed Out |-------------->| Cancel Requested | | . | +-----------+ +------------------+ | . +-----------------------------------------------------------+ . | . tool-result, tool-failure, tool-error, tool-denied . v . +- Attempt Ended -------------------------------------------+ . | +-----------+ +--------+ +---------+ +--------+ | . | | Completed | | Failed | | Errored | | Denied | |- -+ | +-----------+ +--------+ +---------+ +--------+ | +-----------------------------------------------------------+ (1) tool-input (2) tool-input-response tool-progress may occur in Running, Pending, Timed Out and Cancel Requested. - - - next attempt: same operation_id, attempt n + 1 Figure 2: Tool Invocation States The states are: * Running - the request has been sent to the tool and it is performing the operation * Pending - the tool has accepted the request and will complete it later * Input Required - the tool has asked the agent for input before it continues Petrie Expires 6 May 2027 [Page 9] Internet-Draft vCon Tool Invocation Extension November 2026 * Timed Out - the agent has stopped waiting for a response * Cancel Requested - the agent has asked the tool to stop * Completed, Failed, Errored and Denied - the attempt has ended Running, Pending and Input Required are the Working states. The Working states, Timed Out and Cancel Requested are the Active states. Timed Out and Cancel Requested are not final. A tool may still respond after the agent has timed out or asked it to stop, and that response is recorded. The following table defines the transitions. Petrie Expires 6 May 2027 [Page 10] Internet-Draft vCon Tool Invocation Extension November 2026 +===================+=====================+=========================+ | From State | Event Object Type | To State | +===================+=====================+=========================+ | (start of an | tool-invocation | Running | | attempt) | | | +-------------------+---------------------+-------------------------+ | Running | tool-pending | Pending | +-------------------+---------------------+-------------------------+ | Running, Pending, | tool-progress | (unchanged) | | Timed Out, Cancel | | | | Requested | | | +-------------------+---------------------+-------------------------+ | Running, Pending | tool-input | Input Required | +-------------------+---------------------+-------------------------+ | Input Required | tool-input-response | Running or Pending, | | | | the state from | | | | which the input was | | | | requested | +-------------------+---------------------+-------------------------+ | Running, Pending, | tool-timeout | Timed Out | | Input Required | | | +-------------------+---------------------+-------------------------+ | Running, Pending, | tool-cancel | Cancel Requested | | Input Required, | | | | Timed Out | | | +-------------------+---------------------+-------------------------+ | any Active state | tool-result | Completed | +-------------------+---------------------+-------------------------+ | any Active state | tool-failure | Failed | +-------------------+---------------------+-------------------------+ | any Active state | tool-error | Errored | +-------------------+---------------------+-------------------------+ | any Active state | tool-denied | Denied | +-------------------+---------------------+-------------------------+ Table 2: Tool Invocation State Transitions TODO: should a "tool-input-response" type Event Object return to the state from which the input was requested, as above, or always to Running? A vCon records what was observed. An Event Object which does not follow the state model (e.g. because an earlier Event Object was not observed) is still recorded. Petrie Expires 6 May 2027 [Page 11] Internet-Draft vCon Tool Invocation Extension November 2026 5.1. Attempts An invocation may take more than one attempt. Each attempt starts with a "tool-invocation" type Event Object and follows the state model above. All attempts of an invocation have the same operation_id, and each later attempt has the next attempt number. An agent may retry after any ended attempt, for example after "tool- denied" when it has obtained more authorization, or after "tool- error". Every attempt SHOULD be recorded, so that the escalation leading to the final attempt can be reviewed. The Event Objects of an attempt carry its attempt number, so that a late response is associated with the attempt to which it responds. 6. Parameter Definitions 6.1. Event Object Types and Parameters The following types of events are defined in this document: * "policy-decision" - the agent or its host made a policy decision whether an operation may be performed and the following, collectively referred to as the tool event types: * "tool-invocation" - the agent sent a request to the tool * "tool-pending" - the tool accepted the request and will complete it later * "tool-progress" - the tool reported progress or partial output * "tool-input" - the tool asked the agent for input before it continues * "tool-input-response" - the agent sent the input requested by the tool * "tool-result" - the tool completed the operation and returned its output * "tool-failure" - the tool performed or attempted the operation and reported an error * "tool-error" - the request failed at the protocol level (e.g. an unknown tool or invalid arguments) * "tool-denied" - the tool refused to perform the operation Petrie Expires 6 May 2027 [Page 12] Internet-Draft vCon Tool Invocation Extension November 2026 * "tool-timeout" - the agent stopped waiting for a response from the tool * "tool-cancel" - the agent asked the tool to stop The "policy-decision" type Event Object records the decision of the policy of the agent or its host, before the operation is performed (see Section 4). It is not a response from a tool. The "tool-denied" type Event Object records a refusal by the tool, after the request was sent to it. It is used only when the response from the tool is identified by the protocol as a denial (e.g. for [MCP], an HTTP 401 or 403 response). A refusal which the protocol does not distinguish from other errors is recorded as a "tool- failure" type Event Object, with the refusal in its content. The "tool-invocation" type Event Object records the request actually sent to the tool. In the Event Object types defined in this document: * the sessions parameter references the Session Object(s) in which the agent performed, or decided whether to perform, the operation * the party parameter references the agent, including in the Event Objects for policy decisions and for responses from the tool * the tool is identified by the server and tool parameters in the "tool-invocation" type Event Object and in a "policy-decision" type Event Object for the "tool-invocation" operation, and the operation by the operation_id parameter in the other tool event types TODO: the dialog parameter in [VCON-CORE]; decide whether it applies to the Event Object types defined in this document (e.g. a "tool- invocation" which an agent made in response to a Dialog Object). 6.1.1. Event Object Parameter Applicability by Type The following tables summarize which Event Object parameters apply to each Event Object type defined in this document. The parameter definitions in the subsections of this document are definitive; these tables are provided as a summary. The symbols used in the tables are: M the parameter MUST be present, S the parameter SHOULD be present, O the parameter is optional, X the parameter MUST NOT be present. "Content" is the body, encoding and mediatype parameters or the url, content_hash and mediatype parameters (see Section 6.1.10). Petrie Expires 6 May 2027 [Page 13] Internet-Draft vCon Tool Invocation Extension November 2026 The following table applies to the "policy-decision" type Event Object for the "tool-invocation" operation. +==============+====================+========================+ | Parameter | policy-decision, | policy-decision, | | | policy_life "once" | policy_life "standing" | +==============+====================+========================+ | type | M | M | +--------------+--------------------+------------------------+ | time | M | M | +--------------+--------------------+------------------------+ | sessions | M | M | +--------------+--------------------+------------------------+ | party | M | M | +--------------+--------------------+------------------------+ | decision | M | M | +--------------+--------------------+------------------------+ | policy_life | M | M | +--------------+--------------------+------------------------+ | reason | O | O | +--------------+--------------------+------------------------+ | operation | M | M | +--------------+--------------------+------------------------+ | operation_id | M | X | +--------------+--------------------+------------------------+ | attempt | M | X | +--------------+--------------------+------------------------+ | server | M | M | +--------------+--------------------+------------------------+ | tool | M | O | +--------------+--------------------+------------------------+ | content | X | X | +--------------+--------------------+------------------------+ | attachment | X | X | +--------------+--------------------+------------------------+ Table 3: Policy Decision Event Parameters Petrie Expires 6 May 2027 [Page 14] Internet-Draft vCon Tool Invocation Extension November 2026 +==============+============+=======+========+=====+========+======+ | Parameter | tool- |tool- |tool- |tool-|tool- |tool- | | | invocation |pending|progress|input|input- |result| | | | | | |response| | +==============+============+=======+========+=====+========+======+ | type | M |M |M |M |M |M | +--------------+------------+-------+--------+-----+--------+------+ | time | M |M |M |M |M |M | +--------------+------------+-------+--------+-----+--------+------+ | sessions | M |M |M |M |M |M | +--------------+------------+-------+--------+-----+--------+------+ | party | M |M |M |M |M |M | +--------------+------------+-------+--------+-----+--------+------+ | operation_id | M |M |M |M |M |M | +--------------+------------+-------+--------+-----+--------+------+ | attempt | M |M |M |M |M |M | +--------------+------------+-------+--------+-----+--------+------+ | server | M |X |X |X |X |X | +--------------+------------+-------+--------+-----+--------+------+ | tool | M |X |X |X |X |X | +--------------+------------+-------+--------+-----+--------+------+ | content | S |O |S |S |S |S | +--------------+------------+-------+--------+-----+--------+------+ | attachment | O |O |O |O |O |O | +--------------+------------+-------+--------+-----+--------+------+ Table 4: Tool Event Parameters, Part 1 Petrie Expires 6 May 2027 [Page 15] Internet-Draft vCon Tool Invocation Extension November 2026 +==============+==============+=======+========+=========+========+ | Parameter | tool-failure | tool- | tool- | tool- | tool- | | | | error | denied | timeout | cancel | +==============+==============+=======+========+=========+========+ | type | M | M | M | M | M | +--------------+--------------+-------+--------+---------+--------+ | time | M | M | M | M | M | +--------------+--------------+-------+--------+---------+--------+ | sessions | M | M | M | M | M | +--------------+--------------+-------+--------+---------+--------+ | party | M | M | M | M | M | +--------------+--------------+-------+--------+---------+--------+ | operation_id | M | M | M | M | M | +--------------+--------------+-------+--------+---------+--------+ | attempt | M | M | M | M | M | +--------------+--------------+-------+--------+---------+--------+ | server | X | X | X | X | X | +--------------+--------------+-------+--------+---------+--------+ | tool | X | X | X | X | X | +--------------+--------------+-------+--------+---------+--------+ | content | S | S | S | O | O | +--------------+--------------+-------+--------+---------+--------+ | attachment | O | O | O | O | O | +--------------+--------------+-------+--------+---------+--------+ Table 5: Tool Event Parameters, Part 2 The decision, policy_life, reason and operation parameters MUST NOT be present in the tool event types. The content of each Event Object type is: * "policy-decision" - none, the arguments of an invocation are recorded only in its "tool-invocation" type Event Object * "tool-invocation" - the arguments sent to the tool * "tool-pending" - any reference to the pending operation returned by the tool (e.g. a task handle) * "tool-progress" - the progress report or the partial output * "tool-input" - the request for input * "tool-input-response" - the input sent to the tool * "tool-result" - the output of the tool Petrie Expires 6 May 2027 [Page 16] Internet-Draft vCon Tool Invocation Extension November 2026 * "tool-failure" - the error reported by the tool * "tool-error" - the protocol error * "tool-denied" - the reason given by the tool for the denial (e.g. for [MCP], the required scopes and the error description) * "tool-timeout" - any detail of the timeout (e.g. how long the agent waited) * "tool-cancel" - any reason for the cancellation sent to the tool As the arguments are recorded only in the "tool-invocation" type Event Object, the arguments of an invocation which is disallowed, or for which permission is not granted, are not recorded. TODO: whether "tool-input-response" carries the outcome of the response (e.g. accept, decline or cancel in [MCP]) as a parameter of its own, rather than only in its content. 6.1.2. operation_id The operation_id parameter identifies the operation to which this event relates. * operation_id: "String" The operation_id parameter MUST be present in the Event Object types defined in this document, other than "policy-decision" type Event Objects with the policy_life "standing", in which it MUST NOT be present. All of the Event Objects for an operation, across all of its attempts, MUST have the same operation_id. The operation_id MUST be unique among the operations in the vCon. The operation_id is assigned by the agent or its host, and is not the request identifier of the protocol used to perform the operation (e.g. to invoke the tool). The protocol request identifier may change between attempts or when a request is reissued. When a policy decision is made for an operation alone, the operation_id is assigned when the decision is made, before the operation is performed. It can then also be referenced by the permission request and response Event Objects to be defined in a future document (see Section 7). 6.1.3. attempt The attempt parameter indicates the attempt of the operation to which this event relates. Petrie Expires 6 May 2027 [Page 17] Internet-Draft vCon Tool Invocation Extension November 2026 * attempt: "UnsignedInt" The attempt parameter MUST be present in the Event Object types defined in this document, other than "policy-decision" type Event Objects with the policy_life "standing", in which it MUST NOT be present. In a "policy-decision" type Event Object, it is the attempt which the decision precedes. The first attempt of an operation is 1, and each later attempt is one more than the attempt before it (see Section 5.1). 6.1.4. decision The decision parameter indicates the outcome of a policy decision. * decision: "String" The decision parameter MUST be present in "policy-decision" type Event Objects. The value MUST be one of: * "allowed" - no permission is needed to perform the operation * "permission-required" - permission is required before the operation is performed * "disallowed" - the operation is disallowed 6.1.5. policy_life The policy_life parameter indicates how long a policy decision applies (see Section 4.1). * policy_life: "String" The policy_life parameter MUST be present in "policy-decision" type Event Objects. The value MUST be one of: * "once" - the decision applies to one operation only * "standing" - the decision applies to later operations until it is replaced or the vCon ends 6.1.6. reason The reason parameter gives the reason for a policy decision (e.g. why an operation was disallowed). * reason: "String" (optional) Petrie Expires 6 May 2027 [Page 18] Internet-Draft vCon Tool Invocation Extension November 2026 The reason parameter MAY be present in "policy-decision" type Event Objects. 6.1.7. operation The operation parameter indicates the kind of operation to which a policy decision applies. * operation: "String" The operation parameter MUST be present in "policy-decision" type Event Objects. This document defines the value "tool-invocation", for the invocation of a tool. For the "tool-invocation" operation, the server and tool parameters identify the tool (see Section 6.1.8 and Section 6.1.9). TODO: other operations (e.g. access to a resource, delegation to another agent, sharing data with another agent or service, and in contact centers, recording), the parameters which identify them, and whether operation names need a registry. 6.1.8. server The server parameter identifies the server which provides the tool. * server: "String" The server parameter MUST be present in "tool-invocation" type Event Objects and in "policy-decision" type Event Objects for the "tool- invocation" operation. It MUST NOT be present in the other tool event types. The value is one of: * the URL of the server, when it has one (e.g. an [MCP] server reached over HTTP) * the name of the server, when it has no URL (e.g. for [MCP], the name in serverInfo of a server reached over stdio) * "!host", when the tool is provided by the host A server name MUST NOT start with "!", which is reserved for values defined by this document or a vCon extension. The "!" character is not allowed in DNS host names or IPv6 addresses, and cannot start a URL. A server name is not guaranteed to be unique (e.g. the name in [MCP] serverInfo), so the URL SHOULD be used when there is one. Petrie Expires 6 May 2027 [Page 19] Internet-Draft vCon Tool Invocation Extension November 2026 6.1.9. tool The tool parameter identifies the tool that was invoked, or to which a policy decision applies. * tool: "String" The tool parameter MUST be present in "tool-invocation" type Event Objects, and in "policy-decision" type Event Objects for the "tool- invocation" operation with the policy_life "once". It MAY be present in "policy-decision" type Event Objects for the "tool-invocation" operation with the policy_life "standing", and when absent, the decision applies to all of the tools of the server. It MUST NOT be present in the other tool event types. The value is the name of the tool as known to the server (e.g. for [MCP], the name of the tool in the tools/call request). A tool name is unique within a server, so the server and tool parameters together identify the tool. TODO: whether a standing "policy-decision" type Event Object may name a list of tools of a server, rather than one tool or all of them. 6.1.10. Event Content The content of a tool event type is included inline or referenced externally, in the same way as Dialog Object content in [VCON-CORE]. For inline included content: * body: "*" (optional in a redacted vCon) * encoding: "String" Alternatively, for externally referenced content: * url: "String" (optional in a redacted vCon) * content_hash: "ContentHash" | "ContentHash[]" The media type of the content: * mediatype: "String" (required for inline content) The body and url parameters MUST NOT both be present in the same Event Object. The mediatype parameter MUST be present for inline content, as for other inline content in [VCON-CORE] (e.g. "application/json" for the arguments of an [MCP] tool invocation). It is not required when the content is absent. Petrie Expires 6 May 2027 [Page 20] Internet-Draft vCon Tool Invocation Extension November 2026 6.1.11. attachment The attachment parameter references files which are passed to or returned by the tool. * attachment: "UnsignedInt" | "UnsignedInt[]" (optional) The value of the attachment parameter is the index, or an array of indices, into the attachments Object array to the Attachment Objects to which this event relates. 7. Requirements for Permission and Directive Events This section is informative. When a policy decision requires permission, or an agent needs direction, the agent asks the person or agent on whose behalf it is acting, and they respond. These requests and responses are part of the conversation. They occur outside tool invocations as well as within them, and also in contact centers (e.g. consent to record and IVR menu choices). For this reason they are not defined in this document. Event Object types for them need to be defined in a future document. The following requirements have been identified so far. * PD-1: permission requests and responses, with responses beyond yes or no (e.g. allow once, allow for the Session, always allow or a choice from a menu) * PD-2: a request and its response refer to the policy decision and the operation they apply to (e.g. by operation_id) * PD-3: a response given by a button press (e.g. a "keydown" type Event Object) is linked to the request it answers * PD-4: a question from a tool ("tool-input") which is passed on to the person or a parent agent, and its answer, are correlated with the "tool-input" * PD-5: step-up consent after a "tool-denied" (e.g. an [MCP] HTTP 403 with insufficient scope) is correlated with the retried attempt * PD-6: directive requests which are not about an operation (e.g. a clarifying choice put to a person) * PD-7: a subagent asking its parent agent, rather than a person Petrie Expires 6 May 2027 [Page 21] Internet-Draft vCon Tool Invocation Extension November 2026 * PD-8: directives no one asked for (e.g. stop, redirect, change of mode, and grant or revocation of a permission) * PD-9: requests which end other than with an answer (withdrawn, timed out or expired, and declined versus dismissed) * PD-10: requests passed along a chain of agents, and the answer passed back, across Sessions * PD-11: who may answer a request, including more than one approver * PD-12: answers given out of band (e.g. [MCP] URL mode elicitation), where only the outcome is observed * PD-13: the kind of answer (e.g. free text, a form with a schema, or a single or multiple choice) * PD-14: a response or an unprompted grant which changes the policy (e.g. always allow) is linked to the standing "policy-decision" type Event Object that follows it In the absence of that document, a request and its response may be recorded with the existing Objects of [VCON-CORE]: * the question and the answer as Dialog Objects * a button press as a "keydown" type Event Object These do not record the link to the policy decision and the operation, which is why Event Object types for requests and responses need to be defined. 8. Compatibility Considerations The Event Object types defined in this document are new values of the Event Object type parameter. An implementation that does not recognize this extension ignores Event Objects with a type which it does not recognize, as described in [VCON-CORE]. It can still process the rest of the vCon correctly, as the Dialog, Attachment and other Objects do not depend on these Event Object types. The parameters defined in this document apply only to the Event Object types defined in this document, and so are ignored with them. 9. Incompatibility Considerations This extension introduces no incompatibilities in the processing of the conversation itself. Petrie Expires 6 May 2027 [Page 22] Internet-Draft vCon Tool Invocation Extension November 2026 TODO: the content of the tool event types may contain data that must be redacted (see Section 10). An implementation that redacts a vCon but does not recognize this extension might copy the tool event types unchanged into the redacted vCon. Decide whether "tool-invocation" is therefore required in the critical parameter when tool event types with content are present, or whether [VCON-CORE] already requires unrecognized Objects to be removed when redacting. 10. Privacy and Integrity Considerations The content of the tool event types can contain personally identifiable information, party identifying data, the contents of files, credentials and other secrets, and data belonging to third parties. The arguments of a "tool-invocation" and the output of a "tool-result" are the most likely to contain such data. The content of the tool event types is subject to redaction in the same way as Dialog Object content in [VCON-CORE]. The body or url parameter MAY be absent in a redacted vCon. The tool and server parameters can themselves reveal information about the conversation (e.g. the name of a tool which accesses a medical record). The reason parameter of a "policy-decision" type Event Object can reveal the policy of the host, and may contain data from the conversation. Externally referenced content MUST have a content_hash, as for other externally referenced files in [VCON-CORE]. Credentials (e.g. access tokens) used to invoke a tool MUST NOT be recorded in the Event Object types defined in this document. This includes the content of a "tool-denied" type Event Object. 11. Security Considerations The security considerations of [VCON-CORE] apply. * The output of a tool may contain instructions intended to manipulate an agent (e.g. prompt injection). Such content is recorded as it was received, and implementations processing a vCon MUST NOT act on instructions in the content of the tool event types. * TODO: other security considerations. 12. IANA Considerations 12.1. vCon JSON Registry Additions Petrie Expires 6 May 2027 [Page 23] Internet-Draft vCon Tool Invocation Extension November 2026 12.1.1. vCon Extensions Names Registry The following extension name is added to the vCon Extensions Names Registry. +=================+==================+============+===============+ | Extension Name | Extension | Change | Specification | | | Description | Controller | Document(s) | +=================+==================+============+===============+ | tool-invocation | policy decision | IESG | Section 3 RFC | | | and tool | | XXXX | | | invocation Event | | | | | Object types | | | +-----------------+------------------+------------+---------------+ Table 6 12.1.2. Event Type Name Registry The following defines additional values for the Event Type Name Registry. +=====================+================+============+===============+ | Event Type Name | Event Type | Change | Specification | | | Description | Controller | Document(s) | +=====================+================+============+===============+ | policy-decision | operation | IESG | Section 6.1 | | | policy | | RFC XXXX | | | decision | | | | | event | | | +---------------------+----------------+------------+---------------+ | tool-invocation | tool | IESG | Section 6.1 | | | invocation | | RFC XXXX | | | request | | | | | sent event | | | +---------------------+----------------+------------+---------------+ | tool-pending | tool | IESG | Section 6.1 | | | invocation | | RFC XXXX | | | pending | | | | | event | | | +---------------------+----------------+------------+---------------+ | tool-progress | tool | IESG | Section 6.1 | | | invocation | | RFC XXXX | | | progress | | | | | event | | | +---------------------+----------------+------------+---------------+ | tool-input | tool input | IESG | Section 6.1 | | | request | | RFC XXXX | Petrie Expires 6 May 2027 [Page 24] Internet-Draft vCon Tool Invocation Extension November 2026 | | event | | | +---------------------+----------------+------------+---------------+ | tool-input-response | tool input | IESG | Section 6.1 | | | response | | RFC XXXX | | | event | | | +---------------------+----------------+------------+---------------+ | tool-result | tool | IESG | Section 6.1 | | | invocation | | RFC XXXX | | | result | | | | | event | | | +---------------------+----------------+------------+---------------+ | tool-failure | tool | IESG | Section 6.1 | | | reported | | RFC XXXX | | | failure | | | | | event | | | +---------------------+----------------+------------+---------------+ | tool-error | tool | IESG | Section 6.1 | | | invocation | | RFC XXXX | | | protocol | | | | | error event | | | +---------------------+----------------+------------+---------------+ | tool-denied | tool denied | IESG | Section 6.1 | | | invocation | | RFC XXXX | | | event | | | +---------------------+----------------+------------+---------------+ | tool-timeout | tool | IESG | Section 6.1 | | | invocation | | RFC XXXX | | | timeout | | | | | event | | | +---------------------+----------------+------------+---------------+ | tool-cancel | tool | IESG | Section 6.1 | | | invocation | | RFC XXXX | | | cancel | | | | | event | | | +---------------------+----------------+------------+---------------+ Table 7 12.1.3. Event Object Parameter Names Registry The following defines additional values for the Event Object Parameter Names Registry. Petrie Expires 6 May 2027 [Page 25] Internet-Draft vCon Tool Invocation Extension November 2026 +==============+======================+============+================+ | Parameter | Parameter | Change | Specification | | Name | Description | Controller | Document(s) | +==============+======================+============+================+ | operation_id | operation identifier | IESG | Section 6.1.2 | | | | | RFC XXXX | +--------------+----------------------+------------+----------------+ | attempt | operation attempt | IESG | Section 6.1.3 | | | number | | RFC XXXX | +--------------+----------------------+------------+----------------+ | decision | policy decision | IESG | Section 6.1.4 | | | outcome | | RFC XXXX | +--------------+----------------------+------------+----------------+ | policy_life | policy decision life | IESG | Section 6.1.5 | | | | | RFC XXXX | +--------------+----------------------+------------+----------------+ | reason | policy decision | IESG | Section 6.1.6 | | | reason | | RFC XXXX | +--------------+----------------------+------------+----------------+ | operation | kind of operation of | IESG | Section 6.1.7 | | | a policy decision | | RFC XXXX | +--------------+----------------------+------------+----------------+ | server | tool server URL or | IESG | Section 6.1.8 | | | name | | RFC XXXX | +--------------+----------------------+------------+----------------+ | tool | tool name | IESG | Section 6.1.9 | | | | | RFC XXXX | +--------------+----------------------+------------+----------------+ | body | inline tool event | IESG | Section | | | content | | 6.1.10 RFC | | | | | XXXX | +--------------+----------------------+------------+----------------+ | encoding | inline tool event | IESG | Section | | | content encoding | | 6.1.10 RFC | | | | | XXXX | +--------------+----------------------+------------+----------------+ | url | externally | IESG | Section | | | referenced tool | | 6.1.10 RFC | | | event content | | XXXX | +--------------+----------------------+------------+----------------+ | content_hash | externally | IESG | Section | | | referenced tool | | 6.1.10 RFC | | | event content hash | | XXXX | +--------------+----------------------+------------+----------------+ | mediatype | tool event content | IESG | Section | | | media type | | 6.1.10 RFC | | | | | XXXX | +--------------+----------------------+------------+----------------+ Petrie Expires 6 May 2027 [Page 26] Internet-Draft vCon Tool Invocation Extension November 2026 | attachment | tool event | IESG | Section | | | attachment index or | | 6.1.11 RFC | | | indices | | XXXX | +--------------+----------------------+------------+----------------+ Table 8 13. References 13.1. Normative References [JSON] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", STD 90, RFC 8259, DOI 10.17487/RFC8259, December 2017, . [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . [VCON-CORE] Petrie, D., "The JSON format for vCon - Conversation Data Container", Work in Progress, Internet-Draft, draft-ietf- vcon-vcon-core-05, 31 October 2026, . 13.2. Informative References [AUDIT-ARCH] Kühlewind, M. and H. Birkholz, "An Architecture for Auditing Agent Delegation and Interactions", Work in Progress, Internet-Draft, draft-kuehlewind-audit- architecture-01, 7 September 2026, . [CDDL] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data Definition Language (CDDL): A Notational Convention to Express Concise Binary Object Representation (CBOR) and JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, June 2019, . Petrie Expires 6 May 2027 [Page 27] Internet-Draft vCon Tool Invocation Extension November 2026 [MCP] "Model Context Protocol Specification", n.d., . [MCP-2025-11-25] "Model Context Protocol Specification, Revision 2025-11-25", n.d., . [MCP-2026-07-28] "Model Context Protocol Specification, Revision 2026-07-28", n.d., . [ROADMAP] Petrie, D., "vCon for AI Agent Conversations: Requirements, Gaps and Extension Roadmap", Work in Progress, Internet-Draft, draft-petrie-vcon-agent-audit- roadmap-00, 2 November 2026, . Appendix A. Mapping to MCP This appendix describes how the Event Object types defined in this document map to the messages of [MCP]. The mapping is informative. It is given for two revisions, [MCP-2025-11-25] and [MCP-2026-07-28], as the later revision changes how input, pending operations and retries are handled. +=====================+================+===========================+ | Event Object Type | MCP Revision | MCP Revision 2026-07-28 | | | 2025-11-25 | | +=====================+================+===========================+ | policy-decision | no message; | no message; the host | | | the host | applies its policy | | | applies its | | | | policy | | +---------------------+----------------+---------------------------+ | tool-invocation | tools/call | tools/call request | | | request | | +---------------------+----------------+---------------------------+ | tool-pending | task-augmented | task handle returned by | | | response to | the tasks extension | | | tools/call | (io.modelcontextprotocol/ | | | | tasks) | +---------------------+----------------+---------------------------+ | tool-progress | notifications/ | notifications/progress on | | | progress | the response stream of | | | | the request | Petrie Expires 6 May 2027 [Page 28] Internet-Draft vCon Tool Invocation Extension November 2026 +---------------------+----------------+---------------------------+ | tool-input | elicitation/ | result with resultType | | | create request | "input_required"; for a | | | from the | task, task status | | | server; for a | input_required | | | task, task | | | | status | | | | input_required | | +---------------------+----------------+---------------------------+ | tool-input-response | response to | inputResponses in a retry | | | elicitation/ | of the original request; | | | create | for a task, | | | | inputResponses in tasks/ | | | | update | +---------------------+----------------+---------------------------+ | tool-result | tools/call | tools/call result with | | | result with | isError absent or false | | | isError absent | | | | or false | | +---------------------+----------------+---------------------------+ | tool-failure | tools/call | tools/call result with | | | result with | isError true | | | isError true | | +---------------------+----------------+---------------------------+ | tool-error | JSON-RPC error | JSON-RPC error response | | | response | | +---------------------+----------------+---------------------------+ | tool-denied | HTTP 401 or | HTTP 401 or 403 response | | | 403 response | (HTTP transports only) | | | (HTTP | | | | transports | | | | only) | | +---------------------+----------------+---------------------------+ | tool-timeout | no message; | no message; the client | | | the client | stops waiting | | | stops waiting | | +---------------------+----------------+---------------------------+ | tool-cancel | notifications/ | notifications/cancelled; | | | cancelled | for a task, tasks/cancel | +---------------------+----------------+---------------------------+ Table 9: Mapping of Event Object Types to MCP Notes: * The operation_id is not the JSON-RPC request id, which changes when a request is reissued. Petrie Expires 6 May 2027 [Page 29] Internet-Draft vCon Tool Invocation Extension November 2026 * The server parameter is the URL of a server reached over HTTP, or the name in serverInfo of a server reached over stdio. [MCP] tool names are unique within a server, and [MCP] says the serverInfo name is not guaranteed to be unique. * In [MCP-2026-07-28], input is supplied by retrying the original request. TODO: decide whether that retry is a new attempt, with a "tool-invocation" type Event Object, or only a "tool-input- response" type Event Object in the same attempt. * A tool reached over the stdio transport has no HTTP response, so a refusal by it is reported as a tool execution error and recorded as "tool-failure". * After an HTTP 403 with insufficient scope, a client acting for a user may obtain a token with more scope and retry the request. The retry is a new attempt of the same invocation (see Section 5.1). The consent of the user is a permission request (see PD-5 in Section 7). * In [MCP-2026-07-28], notifications/cancelled MUST NOT be used to cancel a task, which is cancelled with tasks/cancel. Cancellation of a task is cooperative, and the task may still end with another status. * A sampling/createMessage request from the server, which is deprecated in [MCP-2026-07-28], is not supported by this document. Appendix B. Example vCons TODO Appendix C. JSON Schema for the tool-invocation Extension This appendix provides a JSON schema for the parameters defined by the tool-invocation extension. The text in the preceding sections of this document defines the normative definition of these parameters. If the JSON schema provided below differs from that in the text of the preceding sections, the text is the definitive definition and the JSON schema below is to be considered incorrect. This schema supplements, and does not replace, the core vCon JSON schema. To fully validate a vCon that uses this extension, apply both the core vCon schema and this schema to the vCon. Petrie Expires 6 May 2027 [Page 30] Internet-Draft vCon Tool Invocation Extension November 2026 The JSON schema definition below has been formatted with line breaks to print nicely on the page. The unformatted version of the JSON schema can be downloaded from: https://raw.githubusercontent.com/dgpetrie/draft-petrie-vcon-tool- invocation/refs/heads/main/tool_invocation_json_schema.json { "$schema": "http://json-schema.org/draft-07/schema#", "$id": "https://ietf.org/vcon/schemas/tool-invocation-extension .json", "title": "vCon Tool Invocation (tool-invocation) Extension", "description": "Supplemental JSON schema for the Event Object t ypes and parameters defined by the vCon tool-invocation exten sion, RFCXXXX. This schema is applied in addition to the core vCon schema; it constrains only the Event Object types and p arameters added by this extension and leaves all other parame ters to the core schema. The text of this document is normati ve; this schema is informational.", "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/definitions/EventToolInvocationExtension" } } }, "definitions": { "EventToolInvocationExtension": { "type": "object", "description": "Event Object types and parameters added to the core Event Object by the tool-invocation extension", "properties": { "type": { "type": "string", "description": "policy-decision, tool-invocation, tool- pending, tool-progress, tool-input, tool-input-respon se, tool-result, tool-failure, tool-error, tool-denie d, tool-timeout or tool-cancel, in addition to the co re Event Object types" }, "decision": { "type": "string", "enum": [ "allowed", "permission-required", "disallowed" ], Petrie Expires 6 May 2027 [Page 31] Internet-Draft vCon Tool Invocation Extension November 2026 "description": "Outcome of a policy decision (policy-de cision only)" }, "policy_life": { "type": "string", "enum": [ "once", "standing" ], "description": "Whether a policy decision applies to on e operation only or is standing (policy-decision only )" }, "reason": { "type": "string", "description": "Reason for a policy decision (policy-de cision only)" }, "operation": { "type": "string", "description": "Kind of operation to which a policy dec ision applies; this document defines tool-invocation (policy-decision only)" }, "operation_id": { "type": "string", "description": "Identifier of the operation; the same f or all Event Objects of an operation, across all of i ts attempts; not present in standing policy decisions " }, "attempt": { "type": "integer", "minimum": 1, "description": "Attempt of the operation, starting at 1 ; not present in standing policy decisions" }, "server": { "type": "string", "description": "URL of the server which provides the to ol, otherwise its name, or !host for a tool provided by the host (policy-decision and tool-invocation only )" }, "tool": { "type": "string", "description": "Name of the tool as known to the server (policy-decision and tool-invocation only); absent i Petrie Expires 6 May 2027 [Page 32] Internet-Draft vCon Tool Invocation Extension November 2026 n a standing policy decision for all of the tools of the server" }, "mediatype": { "type": "string", "description": "Media type of the content of a tool eve nt type; MUST be present for inline content" }, "encoding": { "type": "string", "description": "Encoding of the inline content of a too l event type: json, none or base64url" }, "body": { "description": "Inline content of a tool event type; an y JSON value when encoding is json, otherwise a strin g" }, "url": { "type": "string", "description": "URL of the externally referenced conten t of a tool event type" }, "content_hash": { "oneOf": [ { "type": "string", "pattern": "^[a-z0-9]+-[A-Za-z0-9_-]+$" }, { "type": "array", "items": { "type": "string", "pattern": "^[a-z0-9]+-[A-Za-z0-9_-]+$" } } ], "description": "Hash of the externally referenced conte nt of a tool event type" }, "attachment": { "oneOf": [ { "type": "integer", "minimum": 0 }, { "type": "array", Petrie Expires 6 May 2027 [Page 33] Internet-Draft vCon Tool Invocation Extension November 2026 "items": { "type": "integer", "minimum": 0 } } ], "description": "Index or indices of the Attachment Obje cts passed to or returned by the tool (tool event typ es only)" } }, "allOf": [ { "if": { "properties": { "type": { "enum": [ "policy-decision" ] } }, "required": [ "type" ] }, "then": { "required": [ "sessions", "party", "decision", "policy_life", "operation", "server" ], "allOf": [ { "not": { "anyOf": [ { "required": [ "mediatype" ] }, { "required": [ "encoding" ] }, Petrie Expires 6 May 2027 [Page 34] Internet-Draft vCon Tool Invocation Extension November 2026 { "required": [ "body" ] }, { "required": [ "url" ] }, { "required": [ "content_hash" ] }, { "required": [ "attachment" ] } ] } }, { "if": { "properties": { "policy_life": { "const": "once" } }, "required": [ "policy_life" ] }, "then": { "required": [ "operation_id", "attempt", "tool" ] }, "else": { "not": { "anyOf": [ { "required": [ "operation_id" ] Petrie Expires 6 May 2027 [Page 35] Internet-Draft vCon Tool Invocation Extension November 2026 }, { "required": [ "attempt" ] } ] } } } ] } }, { "if": { "properties": { "type": { "enum": [ "tool-invocation", "tool-pending", "tool-progress", "tool-input", "tool-input-response", "tool-result", "tool-failure", "tool-error", "tool-denied", "tool-timeout", "tool-cancel" ] } }, "required": [ "type" ] }, "then": { "required": [ "sessions", "party", "operation_id", "attempt" ], "allOf": [ { "not": { "anyOf": [ { Petrie Expires 6 May 2027 [Page 36] Internet-Draft vCon Tool Invocation Extension November 2026 "required": [ "decision" ] }, { "required": [ "policy_life" ] }, { "required": [ "reason" ] }, { "required": [ "operation" ] } ] } }, { "if": { "properties": { "body": {} }, "required": [ "body" ] }, "then": { "required": [ "encoding" ], "not": { "required": [ "url" ] } } }, { "if": { "required": [ "url" ] }, Petrie Expires 6 May 2027 [Page 37] Internet-Draft vCon Tool Invocation Extension November 2026 "then": { "required": [ "content_hash" ] } } ] } }, { "if": { "properties": { "type": { "enum": [ "tool-invocation" ] } }, "required": [ "type" ] }, "then": { "required": [ "server", "tool" ] } }, { "if": { "properties": { "type": { "enum": [ "tool-pending", "tool-progress", "tool-input", "tool-input-response", "tool-result", "tool-failure", "tool-error", "tool-denied", "tool-timeout", "tool-cancel" ] } }, "required": [ Petrie Expires 6 May 2027 [Page 38] Internet-Draft vCon Tool Invocation Extension November 2026 "type" ] }, "then": { "not": { "anyOf": [ { "required": [ "server" ] }, { "required": [ "tool" ] } ] } } } ] } } } Appendix D. CDDL for the tool-invocation Extension This appendix provides a [CDDL] definition for the parameters defined by the tool-invocation extension. The text in the preceding sections of this document defines the normative definition of these parameters. If the CDDL provided below differs from that in the text of the preceding sections, the text is the definitive definition and the CDDL below is to be considered incorrect. This CDDL is used together with the core vCon CDDL in [VCON-CORE]. It adds Event Object types through the event-type-ext socket of the core CDDL, and needs no other core socket. Each Event Object type it defines ends with a socket of its own, so that another vCon extension can add parameters to it. The unformatted version of the CDDL can be downloaded from: https://raw.githubusercontent.com/dgpetrie/draft-petrie-vcon-tool- invocation/refs/heads/main/tool_invocation.cddl Petrie Expires 6 May 2027 [Page 39] Internet-Draft vCon Tool Invocation Extension November 2026 ; CDDL for the tool-invocation vCon extension ; (draft-petrie-vcon-tool-invocation). ; The prose of the draft is normative. ; This CDDL is informative. ; Constraints that cannot be expressed in CDDL are stated in ; comments. ; ; This CDDL is used together with the core vCon CDDL ; (draft-ietf-vcon-vcon-core, syntax version 0.5.0). ; It adds Event Object types through the event-type-ext socket of ; the core CDDL, and uses no other core socket. ; It uses these rules of the core CDDL: date_type, ; session_index_or_list_type, party_index_type, ; attachment_index_or_list_type, media_type_value_type and ; file_content_type. ; ; Each Event Object type defined here ends with a socket of its ; own, so that another vCon extension can add parameters to it. ; A policy decision for another kind of operation is added by ; another vCon extension, as a group of its own with the type ; "policy-decision" and its own operation value, through the ; event-type-ext socket. ; ; Not enforced by this CDDL: ; - A vCon which contains these Event Object types SHOULD list ; "tool-invocation" in its extensions parameter. ; - operation_id MUST be unique among the operations in the vCon, ; and all of the Event Objects of an operation, across all of ; its attempts, MUST have the same operation_id. ; - Each later attempt of an operation is one more than the ; attempt before it. ; - mediatype MUST be present for inline content. $$event-type-ext //= ( event_policy_decision_once_type ) $$event-type-ext //= ( event_policy_decision_standing_type ) $$event-type-ext //= ( event_tool_invocation_type ) $$event-type-ext //= ( event_tool_response_type ) ; Parameters common to the Event Object types of this extension ; party references the agent, also in the Event Objects for ; policy decisions and for responses from the tool. event_ti_common_type = ( "time": date_type, sessions: session_index_or_list_type, party: party_index_type ) ; Policy decision event type Petrie Expires 6 May 2027 [Page 40] Internet-Draft vCon Tool Invocation Extension November 2026 policy_decision_value_type = "allowed" / "permission-required" / "disallowed" ; Parameters common to the policy-decision type policy_decision_common_type = ( type: "policy-decision", event_ti_common_type, decision: policy_decision_value_type, ? reason: tstr ) ; A decision for one tool invocation event_policy_decision_once_type = ( policy_decision_common_type, operation: "tool-invocation", policy_life: "once", operation_id: tstr, attempt: attempt_value_type, tool_identity_type, * $$event-policy-decision-ext ) ; A standing decision for one tool, or for all of the tools of a ; server when tool is absent ; Not enforced by this CDDL: ; - A standing decision applies until a later policy-decision type ; Event Object for the same operation and target replaces it, or ; until the end of the vCon. event_policy_decision_standing_type = ( policy_decision_common_type, operation: "tool-invocation", policy_life: "standing", server: server_value_type, ? tool: tstr, * $$event-policy-decision-ext ) ; The server and the tool together identify a tool. tool_identity_type = ( server: server_value_type, tool: tstr ) ; The URL of the server when it has one, otherwise the name of the ; server, or "!host" for a tool provided by the host. ; Not enforced by this CDDL: ; - A server name MUST NOT start with "!". server_value_type = tstr Petrie Expires 6 May 2027 [Page 41] Internet-Draft vCon Tool Invocation Extension November 2026 ; Parameters common to the tool event types event_tool_common_type = ( event_ti_common_type, operation_id: tstr, attempt: attempt_value_type ) ; Content of a tool event type, inline or externally referenced ; as for Dialog Content in the core CDDL. ; Not enforced by this CDDL: ; - Content SHOULD be present in the tool event types, other than ; tool-pending, tool-timeout and tool-cancel, in which it is ; optional (see Event Object Parameter Applicability by Type). event_tool_content_type = ( ? mediatype: media_type_value_type, file_content_type ) ; Tool invocation event type ; The content is the arguments sent to the tool. event_tool_invocation_type = ( type: "tool-invocation", event_tool_common_type, tool_identity_type, ? event_tool_content_type, ? attachment: attachment_index_or_list_type, * $$event-tool-invocation-ext ) ; Event types for the responses from the tool, and for the input, ; timeout and cancellation of the agent ; Not enforced by this CDDL: ; - tool-denied is used only when the response from the tool is ; identified by the protocol as a denial. event_tool_response_type = ( type: "tool-pending" / "tool-progress" / "tool-input" / "tool-input-response" / "tool-result" / "tool-failure" / "tool-error" / "tool-denied" / "tool-timeout" / "tool-cancel", event_tool_common_type, ? event_tool_content_type, ? attachment: attachment_index_or_list_type, * $$event-tool-ext ) ; The first attempt of an operation is 1. attempt_value_type = uint .ge 1 Petrie Expires 6 May 2027 [Page 42] Internet-Draft vCon Tool Invocation Extension November 2026 Acknowledgments Author's Address Daniel G Petrie SIPez LLC Email: dan.ietf@sipez.com Petrie Expires 6 May 2027 [Page 43]