Orchardcore AI A2a Host

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

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.

{
  "steps": [
    {
      "name": "AIProfile",
      "profiles": [
        {
          "Source": "OpenAI",
          "Name": "research-agent",
          "DisplayText": "Research Agent",
          "Description": "Researches topics and returns sourced summaries.",
          "Type": "Agent",
          "ChatDeploymentId": "research-chat-deployment",
          "UtilityDeploymentId": "research-utility-deployment",
          "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

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.