Package com.xebialabs.xlrelease.a2a.server

Interface A2aServerSkill

All Known Implementing Classes:
GetReleaseStatusSkill, OrchestrateReleaseSkill, RequestDeploymentApprovalSkill
public interface A2aServerSkill
One skill Release advertises on its Agent Card and executes when an external A2A agent sends a message for it.

Phase-0 shape: host-defined skills only, executed synchronously on the request thread, one text artifact out. The annotation-driven, plugin-contributed skill model (@A2aSkill/A2aSkillset bridged through the plugin extension registry, like MCP tools) replaces this interface's discovery — not its semantics — in a later phase; see documentation/proposals/a2a-implementation-design.md §4.

  • Method Summary

    Modifier and Type
    Method
    Description
    String
    description()
    What the skill does and what input it expects — agents read this to decide what to send.
    String
    id()
    Skill id as advertised on the Agent Card and addressed via message metadata skillId.
    A2aSkillOutcome
    invoke(String text, Map<String,String> metadata)
    Executes the skill.
    String
    name()
    Human-readable name for the Agent Card.
    boolean
    readOnly()
    Whether the skill only reads Release state.

  • Method Details

    • id

      String id()
      Skill id as advertised on the Agent Card and addressed via message metadata skillId.

    • name

      String name()
      Human-readable name for the Agent Card.

    • description

      String description()
      What the skill does and what input it expects — agents read this to decide what to send.

    • readOnly

      boolean readOnly()
      Whether the skill only reads Release state. When the A2A feature's read-only mode is on, skills returning false are hidden from the Agent Card and rejected if called anyway.

    • invoke

      A2aSkillOutcome invoke(String text, Map<String,String> metadata) throws Exception
      Executes the skill.

      Runs on the HTTP request thread under the caller's authenticated identity, so host API calls are permission-checked as that caller. Return A2aSkillOutcome.text(String) for an immediately-complete result, or A2aSkillOutcome.release(String) for work delegated to a release, whose live state becomes the A2A task from then on. Throw IllegalArgumentException for bad input (becomes a failed A2A task with the message as explanation), A2aContractViolationException for a governance handoff-contract violation (becomes a rejected task); any other exception is reported as a failed task without internal detail.

      Parameters:
      text - the concatenated text parts of the incoming message
      metadata - the incoming message's metadata values, stringified
      Throws:
      Exception