Outbound Metadata

Many remote agents need more than the message text: a tenant ID, the requester’s email, or the record the conversation is about. The A2A protocol carries these as metadata on each message. In Tool Studio, an A2A agent’s Outbound metadata section builds that metadata from a DSL expression, with an optional schema for values the assistant supplies from the conversation.

When the agent’s connector uses application credentials rather than per-user authorization, outbound metadata is also how the remote agent learns who is asking.

How It Fits Together

The expression is the only thing that produces metadata. With no expression, the message is sent without metadata even if a schema is set. With an expression and no schema, the expression can still use the requesting user’s fields.

Write the Expression

The expression is evaluated against two inputs:

The expression must return an object. For example, to send the ticket the assistant identified and the requester’s email:

{ticketId: data.ticketId, requester: {email: meta_info.user.email_addr}}

The result is sent as is, including any null values, on both the A2A message metadata and the request parameters metadata, because remote agents differ in which one they read.

Declare Values the Assistant Supplies

Use the schema when the metadata needs something only the conversation knows, such as a ticket number the user mentioned. The schema is shown to the model as a metadata input on both of the agent’s tools, and the model fills it from the conversation before each message, the same way it fills any tool argument. Describe each field so the model knows what to put in it.

Select Insert example for a starting point:

{
  "type": "object",
  "properties": {
    "ticketId": {
      "type": "string",
      "description": "ID of the ticket this conversation is about"
    }
  },
  "required": ["ticketId"]
}

The schema must be:

• A JSON Schema draft-07 object schema, with "type": "object" at the top level.
• Self-contained. $ref, $id, $defs, and definitions are not supported.
• At most 32 KB when saved.

Before each message, the model’s values are validated against the schema. Fields the schema does not declare are dropped unless the schema allows them with additionalProperties or patternProperties. Optional fields the model left empty are omitted. If the values fail validation, the model is told which field was wrong and can correct it.

Test the Expression

The Outbound metadata section includes Copy sample payload, which builds a sample data object from your schema and a sample meta_info.user. Paste it into the DSL & Mapper Playground with your expression to check the output before you publish. The sample user fields are illustrative; the fields present at runtime depend on your organization’s user data.

When Something Is Wrong

Saving the agent rejects an expression that does not parse and a schema that breaks the rules above, with the error shown next to the field. Two problems can only appear at runtime:

• The expression fails or returns something other than an object. The message is not sent, and the assistant receives a configuration error for that turn. Nothing reaches the remote agent. Fix the expression and save; the next message uses the corrected version.
• The schema cannot be presented to the model. This happens when the merged tool schema is too large for the model, for example a schema with thousands of enum values. The agent’s tools stay visible so the problem is noticed, but every call fails with a message that names the agent and asks for the schema to be fixed in its configuration.

Each turn’s log entry in the Logs app records the dispatch, so a rejected send is visible there. See View A2A Logs.

Limits