orchardcore-ai-a2a-host

name	orchardcore-ai-a2a-host
description	Skill for configuring the CrestApps A2A Host feature in Orchard Core. Covers exposing Agent AI Profiles as A2A agents, host authentication, agent cards, endpoints, and host settings. Use this skill when requests mention Orchard Core A2A Host, Configure an A2A Host, Feature Overview, Enable the Host Feature, Create Agent Profiles, Host Settings in Configuration, or closely related Orchard Core implementation, setup, extension, or troubleshooting work. Strong matches include work with CrestApps.OrchardCore.AI.A2A.Host, CrestApps.OrchardCore.AI, AIProfile, ExposeAgentsAsSkill, agentName, AuthenticationType, OrchardCore:CrestApps_AI:A2AHost, ApiKey. It also helps with Create Agent Profiles, Host Settings in Configuration, Agent Exposure Modes, plus the code patterns, admin flows, recipe steps, and referenced examples captured in this skill.
license	Apache-2.0
metadata	{"author":"CrestApps Team","version":"1.0"}

Orchard Core A2A Host - Prompt Templates

Configure an A2A Host

You are an Orchard Core expert. Generate configuration and guidance for exposing Orchard Core Agent AI Profiles through the CrestApps A2A Host feature.

Guidelines

• Use the A2A Host feature ID CrestApps.OrchardCore.AI.A2A.Host.
• The host exposes AI Profiles whose Type is Agent.
• Agent cards are served from /.well-known/agent-card.json.
• By default, the well-known endpoint returns a JSON array of agent cards, one per Agent AI Profile.
• Each card points to /a2a?agent={agentName} through its url property.
• When ExposeAgentsAsSkill is enabled, the host returns a single combined agent card and routes requests using the agentName metadata field.
• Keep agent Description accurate because it becomes part of the external agent or skill description.
• Prefer authenticated host access in shared or production environments.

Feature Overview

Feature	Feature ID	Description
A2A Host	CrestApps.OrchardCore.AI.A2A.Host	Expose Agent AI Profiles via the Agent-to-Agent protocol

Enable the Host Feature

{
  "steps": [
    {
      "name": "Feature",
      "enable": [
        "CrestApps.OrchardCore.AI",
        "CrestApps.OrchardCore.AI.A2A.Host"
      ],
      "disable": []
    }
  ]
}

Prerequisite: Create Agent Profiles

Only AI Profiles of type Agent are exposed by the host.

The AIProfile recipe format is source-agnostic. Omit Source and bind the agent to deployments by technical name.

{
  "steps": [
    {
      "name": "AIProfile",
      "profiles": [
        {
          "Name": "research-agent",
          "DisplayText": "Research Agent",
          "Description": "Researches topics and returns sourced summaries.",
          "Type": "Agent",
          "ChatDeploymentName": "research-chat",
          "UtilityDeploymentName": "research-utility",
          "Properties": {
            "AIProfileMetadata": {
              "SystemMessage": "You are a research assistant.",
              "Temperature": 0.2,
              "MaxTokens": 4096
            },
            "AgentMetadata": {
              "Availability": "OnDemand"
            }
          }
        }
      ]
    }
  ]
}

Host Settings in Configuration

{
  "OrchardCore": {
    "CrestApps_AI": {
      "A2AHost": {
        "AuthenticationType": "None",
        "ApiKey": "your-api-key-here",
        "RequireAccessPermission": false,
        "ExposeAgentsAsSkill": false
      }
    }
  }
}

Agent Exposure Modes

Multi-Agent Mode (Default)

Use ExposeAgentsAsSkill: false when you want one agent card per Agent profile.

• /.well-known/agent-card.json returns a JSON array of cards.
• Each card advertises a single agent.
• Each card points clients to /a2a?agent={agentName}.

Skill Mode

Use ExposeAgentsAsSkill: true when you want a single combined agent card.

• The well-known endpoint returns one combined card.
• Each Agent AI Profile is represented as a skill.
• Requests are routed using the agentName metadata field.

Endpoints

Endpoint	Purpose
/.well-known/agent-card.json	Agent discovery endpoint
/a2a?agent={agentName}	Sends messages to a specific exposed agent

Authentication Guidance

The host configuration supports authentication settings through AuthenticationType and related options in OrchardCore:CrestApps_AI:A2AHost.

Use these settings as your starting point:

• AuthenticationType: "None" for local development only.
• Set ApiKey when using API-key-based access.
• Use RequireAccessPermission: true when you want Orchard permission checks enforced for host access.

Example Host Configuration for a Shared Environment

{
  "OrchardCore": {
    "CrestApps_AI": {
      "A2AHost": {
        "AuthenticationType": "ApiKey",
        "ApiKey": "{{A2AHostApiKey}}",
        "RequireAccessPermission": true,
        "ExposeAgentsAsSkill": true
      }
    }
  }
}

Best Practices

• Use Agent profiles, not Chat profiles, for A2A host exposure.
• Write strong profile descriptions so remote clients can pick the right agent.
• Keep ExposeAgentsAsSkill disabled when clients should select named agents directly.
• Enable ExposeAgentsAsSkill when clients prefer one consolidated card with multiple skills.
• Avoid AuthenticationType: "None" outside local development.