OSSA Schema Reference
Complete JSON Schema for defining portable, framework-agnostic AI agents
Version v0.3.2 • The OpenAPI for AI Agents
Why This Schema?
The Problem: Every AI framework defines agents differently. LangChain has "chains," CrewAI has "crews," OpenAI has "assistants," Anthropic has different tools. This creates vendor lock-in and makes it impossible to share agents between teams or frameworks.
The Solution: OSSA provides a single, standard way to describe agents that works everywhere. Like OpenAPI revolutionized REST APIs, OSSA revolutionizes AI agents.
The Result: Write your agent definition once, deploy it to any framework. Switch providers without rewriting code. Share agents across organizations. True portability.
Schema Architecture
OSSA Agent Manifest Structure
Complete breakdown of all manifest components and their relationships
OSSA Agent Manifest
agent.yaml / agent.json
apiVersion
Specifies the OSSA specification version
ossa/v0.3.2
kind
Resource type identifier that specifies what type of OSSA resource this manifest defines.
Agent
Agent is the primary resource type in OSSA. An Agent represents an autonomous AI system that can:
- Process natural language instructions
- Make decisions and take actions
- Use tools and interact with external systems
- Maintain context and state across interactions
Think of an Agent as a reusable, portable definition of an AI assistant that can be deployed to any framework.
metadata
Agent identification and labeling
• name - Unique agent identifier
• version - Agent version number
• description - Human-readable description
• labels - Key-value metadata tags
• annotations - Additional metadata
spec
Core agent configuration including behavior, capabilities, and operational settings.
role
Defines the agent's system prompt and identity. This is the core instruction that tells the agent who it is and how it should behave.
type: string (multi-line)
llm
Configuration for the Large Language Model that powers the agent's reasoning and responses.
provider
openai | anthropic | azure
model
gpt-4, claude-3, etc.
temperature
0.0 - 2.0 (creativity level)
max_tokens
Maximum response length
tools
Capabilities the agent can use to interact with external systems and perform actions.
http
Make REST API calls to external services
code
Execute Python, JavaScript, or Shell scripts
database
Run SQL queries against databases
file
Read and write file system operations
search
Web search and vector similarity search
taxonomy
Categorization metadata for organizing and discovering agents across domains and use cases.
domain
customer_service, engineering, etc.
subdomain
technical_support, devops, etc.
use_case
troubleshooting, automation
industry
saas, healthcare, finance
autonomy
Controls how independently the agent can operate, from fully manual (L0) to fully autonomous (L5).
level
L0 (no autonomy) → L5 (full autonomy)
approval_required
List of actions that require human approval before execution
human_in_loop
Notification and escalation settings for human oversight
observability
Monitoring and debugging capabilities for tracking agent behavior and performance.
logging
Logs & audit trails
metrics
Performance data
tracing
Execution paths
constraintsOptional
Resource limits and operational boundaries to ensure safe and controlled agent execution.
cost
Budget and spending limits
performance
Timeout and rate limiting
resources
Memory and CPU constraints
security
Access control and permissions
extensions
Optional framework-specific configurations that extend the core OSSA specification for platform-specific features.
Supported frameworks:
LangChain
OpenAI
Anthropic
Langflow
Vercel AILangGraph
Drupal
LibreChat
MCP
Hugging Face
Google
AWS
Azure
GitHub
Docker
KubernetesData Flow: How OSSA Works
1. Definition → Execution
1
Write agent.yaml
Define role, LLM, tools
2
Validate schema
JSON Schema validation
3
Load into runtime
kAgent / LangChain / etc
4
Execute agent
Run tasks, call LLM, use tools
2. Cross-Framework Portability
A
agent.yaml (OSSA)
Framework-agnostic definition
↓ Export to ↓
LangChain: chains.json
CrewAI: crew_config.yaml
OpenAI: assistant_config.json
Anthropic: claude_tools.json
Complete Agent Lifecycle
From development to deployment across any framework
Developer
Writes OSSA Manifest
agent.yaml
OSSA Schema Validator
JSON Schema validation engine
Validation Checks:
✓Required fields present
✓Correct types
✓Value constraints
✓Schema compliance
Valid Manifest
Framework Adapter Layer
Converts OSSA → Framework-Specific Config
kAgent
Runtime
LangChain
Runtime
CrewAI
Runtime
OpenAI
Runtime
Agent Execution
LLM Calls
GPT-4, Claude, etc.
Tool Usage
APIs, Code, DB
Task Processing
Execute workflows
Observability
Logs
Debug & audit
Metrics
Performance data
Traces
Execution paths
Schema Components
The OSSA schema is organized into core components that define every aspect of an AI agent. Each component serves a specific purpose in creating portable, framework-agnostic agent definitions. Click on any component below to learn more about its structure, purpose, and usage.
WHAT:
Version identifier and resource type for the manifest.
WHY:
Enables schema evolution while maintaining backward compatibility. Like Kubernetes resources or OpenAPI specs, agents can evolve without breaking existing definitions.
EXAMPLE:
apiVersion: ossa/v0.3.2
kind: AgentInteractive Schema Explorer
Explore the complete JSON Schema interactively. Click on any property to see its type, description, and validation rules.
Schema Structure
apiVersion(string)required
OSSA API version (v0.3.2+ supports Task and Workflow kinds)
kind(string)required
Resource type: Agent (agentic loops), Task (deterministic steps), or Workflow (composition)
metadata(object)required
spec(object)
Specification varies based on kind
extensions(object)
Framework-specific extensions
runtime(object)
Runtime-specific capability bindings (for Task and Workflow kinds)
Schema Overview
Type
object
Description
Open Standard for Scalable AI Agents (OSSA) v0.3.2 - Unified Task Schema with Access Tiers & Separation of Duties. Supports Agent (agentic loops with LLM), Task (deterministic workflow steps), and Workflow (composition of Tasks and Agents) kinds. Includes Agent-to-Agent Messaging Extension and Access Control Tiers for privilege separation.
JSON Schema
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://openstandardagents.org/schemas/v0.3.2/manifest.json",
"title": "OSSA v0.3.2 Manifest Schema",
"description": "Open Standard for Scalable AI Agents (OSSA) v0.3.2 - Unified Task Schema with Access Tiers & Separation of Duties. Supports Agent (agentic loops with LLM), Task (deterministic workflow steps), and Workflow (composition of Tasks and Agents) kinds. Includes Agent-to-Agent Messaging Extension and Access Control Tiers for privilege separation.",
"type": "object",
"required": [
"apiVersion",
"kind",
"metadata"
],
"properties": {
"apiVersion": {
"type": "string",
"pattern": "^ossa/v(0\\.3\\.[0-9]+(-[a-zA-Z0-9]+)?|0\\.2\\.[2-9](-dev)?|1)(\\.[0-9]+)?(-[a-zA-Z0-9]+)?$",
"description": "OSSA API version (v0.3.2+ supports Task and Workflow kinds)",
"examples": [
"ossa/v0.3.2",
"ossa/v1",
"ossa/v0.2.9"
]
},
"kind": {
"type": "string",
"enum": [
"Agent",
"Task",
"Workflow"
],
"description": "Resource type: Agent (agentic loops), Task (deterministic steps), or Workflow (composition)"
},
"metadata": {
"$ref": "#/definitions/Metadata"
},
"spec": {
"description": "Specification varies based on kind"
},
"extensions": {
"type": "object",
"description": "Framework-specific extensions",
"properties": {
"mcp": {
"$ref": "#/definitions/MCPExtension"
}
},
"additionalProperties": true
},
"runtime": {
"$ref": "#/definitions/RuntimeBinding",
"description": "Runtime-specific capability bindings (for Task and Workflow kinds)"
}
},
"allOf": [
{
"if": {
"properties": {
"kind": {
"const": "Agent"
}
}
},
"then": {
"properties": {
"spec": {
"$ref": "#/definitions/AgentSpec"
}
},
"required": [
"spec"
]
}
},
{
"if": {
"properties": {
"kind": {
"const": "Task"
}
}
},
"then": {
"properties": {
"spec": {
"$ref": "#/definitions/TaskSpec"
}
},
"required": [
"spec"
]
}
},
{
"if": {
"properties": {
"kind": {
"const": "Workflow"
}
}
},
"then": {
"properties": {
"spec": {
"$ref": "#/definitions/WorkflowSpec"
}
},
"required": [
"spec"
]
}
}
],
"definitions": {
"AccessTier": {
"type": "object",
"description": "Access tier configuration for separation of duties (v0.3.2+). Defines privilege levels and role separations for agents.",
"required": [
"tier"
],
"properties": {
"tier": {
"type": "string",
"enum": [
"tier_1_read",
"tier_2_write_limited",
"tier_3_write_elevated",
"tier_4_policy"
],
"description": "Access tier level: tier_1_read (analyzers), tier_2_write_limited (workers), tier_3_write_elevated (operators), tier_4_policy (governors)"
},
"permissions": {
"type": "array",
"description": "Explicit permissions granted to this agent",
"items": {
"type": "string",
"enum": [
"read_code",
"read_configs",
"read_metrics",
"read_logs",
"read_issues",
"read_mrs",
"execute_queries",
"write_docs",
"write_tests",
"write_scaffolds",
"write_configs_draft",
"create_issues",
"create_mrs_draft",
"execute_sandboxed",
"write_production_code",
"merge_mrs",
"delete_branches",
"modify_infrastructure",
"modify_secrets",
"execute_deployments",
"modify_pipelines",
"modify_configs",
"execute_commands",
"define_policies",
"publish_policies",
"audit_compliance",
"report_violations"
]
},
"uniqueItems": true
},
"prohibited": {
"type": "array",
"description": "Explicitly prohibited actions for this agent",
"items": {
"type": "string"
},
"uniqueItems": true
},
"audit_level": {
"type": "string",
"enum": [
"standard",
"detailed",
"comprehensive"
],
"default": "standard",
"description": "Audit logging level: standard (30 days), detailed (90 days), comprehensive (365 days)"
},
"requires_approval": {
"type": "boolean",
"default": false,
"description": "Whether operations require approval chain"
},
"approval_chain": {
"type": "string",
"enum": [
"standard",
"elevated",
"critical"
],
"description": "Approval workflow to use when requires_approval is true"
},
"isolation": {
"type": "string",
"enum": [
"none",
"standard",
"strict"
],
"default": "none",
"description": "Isolation level: none (default), standard (limited delegation), strict (no execution, policy only)"
}
},
"additionalProperties": false
},
"SeparationOfDuties": {
"type": "object",
"description": "Role separation rules for preventing conflicts of interest",
"properties": {
"role": {
"type": "string",
"description": "Primary role of this agent",
"enum": [
"analyzer",
"auditor",
"scanner",
"reviewer",
"monitor",
"generator",
"scaffolder",
"documenter",
"test_writer",
"deployer",
"operator",
"executor",
"maintainer",
"governor",
"policy_definer",
"compliance_officer",
"approver",
"critic",
"remediator",
"enforcer"
]
},
"conflicts_with": {
"type": "array",
"description": "Roles that this agent must NOT also perform (separation of duties)",
"items": {
"type": "string"
},
"uniqueItems": true
},
"can_delegate_to": {
"type": "array",
"description": "Roles/tiers this agent can delegate tasks to",
"items": {
"type": "string"
},
"uniqueItems": true
},
"prohibited_actions": {
"type": "array",
"description": "Specific actions this role must never perform",
"items": {
"type": "string",
"enum": [
"approve",
"merge",
"execute",
"deploy",
"delete",
"modify_production",
"define_policies",
"bypass_approvals"
]
},
"uniqueItems": true
}
},
"additionalProperties": false
},
"DelegationConfig": {
"type": "object",
"description": "Configuration for delegating tasks to other agents",
"properties": {
"enabled": {
"type": "boolean",
"default": true,
"description": "Whether this agent can delegate to others"
},
"allowed_tiers": {
"type": "array",
"description": "Tiers this agent can delegate to",
"items": {
"type": "string",
"enum": [
"tier_1_read",
"tier_2_write_limited",
"tier_3_write_elevated"
]
},
"uniqueItems": true
},
"allowed_operations": {
"type": "array",
"description": "Operations that can be delegated",
"items": {
"type": "string"
}
},
"requires": {
"type": "array",
"description": "Requirements for delegation",
"items": {
"type": "string",
"enum": [
"delegation_token",
"audit_trail",
"violation_report",
"task_specification",
"approval"
]
}
}
},
"additionalProperties": false
},
"TaxonomyClassification": {
"type": "object",
"description": "Hierarchical taxonomy classification for agents (v0.3.2+). Links to taxonomy.yaml spec.",
"required": [
"domain"
],
"properties": {
"domain": {
"type": "string",
"enum": [
"security",
"infrastructure",
"documentation",
"backend",
"frontend",
"data",
"agents",
"development",
"content"
],
"description": "Primary domain classification - every agent belongs to exactly one domain"
},
"subdomain": {
"type": "string",
"description": "Subdomain within the primary domain (e.g., auth, ci-cd, api-docs)"
},
"capability": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]*$",
"description": "Primary capability this agent provides"
},
"concerns": {
"type": "array",
"description": "Cross-cutting concerns that apply to this agent",
"items": {
"type": "string",
"enum": [
"quality",
"observability",
"governance",
"performance",
"architecture",
"cost",
"reliability"
]
},
"uniqueItems": true
},
"recommended_tier": {
"type": "string",
"enum": [
"tier_1_read",
"tier_2_write_limited",
"tier_3_write_elevated",
"tier_4_policy"
],
"description": "Recommended access tier based on domain defaults"
}
},
"additionalProperties": false
},
"AgentIdentity": {
"type": "object",
"description": "Comprehensive agent identity configuration for service accounts, authentication, and observability",
"properties": {
"provider": {
"type": "string",
"enum": [
"gitlab",
"github",
"azure-devops",
"bitbucket",
"generic"
],
"description": "Identity provider type for service account integration"
},
"service_account": {
"type": "object",
"description": "Service account details for automated operations",
"required": [
"username",
"email"
],
"properties": {
"id": {
"oneOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Provider-specific account ID"
},
"username": {
"type": "string",
"pattern": "^[a-z0-9_\\[\\]-]+$",
"minLength": 1,
"maxLength": 64,
"description": "Service account username"
},
"email": {
"type": "string",
"format": "email",
"description": "Service account email for git attribution"
},
"display_name": {
"type": "string",
"description": "Human-readable display name"
},
"roles": {
"type": "array",
"items": {
"type": "string",
"enum": [
"developer",
"maintainer",
"owner",
"reporter",
"guest"
]
},
"description": "Roles assigned to this service account"
}
}
},
"authentication": {
"type": "object",
"description": "Authentication method configuration",
"properties": {
"method": {
"type": "string",
"enum": [
"personal_access_token",
"project_access_token",
"group_access_token",
"deploy_token",
"oauth2",
"ssh_key",
"mtls",
"github_app",
"azure_service_principal"
],
"default": "personal_access_token",
"description": "Authentication method type"
},
"scopes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Required token scopes (provider-specific)"
},
"auto_refresh": {
"type": "boolean",
"default": false,
"description": "Automatically refresh token before expiry"
},
"expiry_warning_days": {
"type": "integer",
"default": 7,
"minimum": 1,
"maximum": 90,
"description": "Days before expiry to warn about token rotation"
},
"rotation_policy": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"default": false
},
"interval_days": {
"type": "integer",
"default": 90,
"minimum": 7,
"maximum": 365
},
"notify_on_rotation": {
"type": "boolean",
"default": true
}
}
}
}
},
"token_source": {
"type": "object",
"description": "Token/credential source configuration with priority order",
"properties": {
"env_var": {
"type": "string",
"pattern": "^[A-Z][A-Z0-9_]*$",
"description": "Environment variable name containing the token (highest priority)"
},
"file_path": {
"type": "string",
"description": "Path to token file (second priority, supports ~ expansion)"
},
"vault": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "Vault secret path"
},
"key": {
"type": "string",
"default": "value"
},
"role": {
"type": "string",
"description": "Vault role for authentication"
}
}
},
"kubernetes_secret": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"namespace": {
"type": "string"
},
"key": {
"type": "string",
"default": "token"
}
}
}
}
},
"patterns": {
"type": "array",
"items": {
"type": "string"
},
"description": "Glob patterns for auto-detection based on working directory (picomatch syntax)"
},
"fallback": {
"type": "array",
"items": {
"type": "object",
"required": [
"provider",
"service_account"
],
"properties": {
"provider": {
"type": "string",
"enum": [
"gitlab",
"github",
"azure-devops",
"bitbucket",
"generic"
]
},
"service_account": {
"$ref": "#/definitions/AgentIdentity/properties/service_account"
},
"token_source": {
"$ref": "#/definitions/AgentIdentity/properties/token_source"
},
"condition": {
"type": "object",
"properties": {
"pattern_match": {
"type": "array",
"items": {
"type": "string"
}
},
"platform_unavailable": {
"type": "boolean"
}
}
}
}
},
"description": "Fallback identity chain for high availability"
},
"dora_tracking": {
"type": "object",
"description": "DORA metrics tracking configuration",
"properties": {
"enabled": {
"type": "boolean",
"default": false
},
"metrics": {
"type": "array",
"items": {
"type": "string",
"enum": [
"deployment_frequency",
"lead_time",
"change_failure_rate",
"mttr"
]
},
"uniqueItems": true
},
"labels": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Additional labels for metrics"
},
"prometheus": {
"type": "object",
"properties": {
"push_gateway": {
"type": "string",
"format": "uri"
},
"job_name": {
"type": "string"
}
}
}
}
},
"session": {
"type": "object",
"description": "Session management for Claude Code integration",
"properties": {
"init_on_start": {
"type": "boolean",
"default": true
},
"propagate_to_subprocesses": {
"type": "boolean",
"default": true
},
"git_attribution": {
"type": "boolean",
"default": true
},
"heartbeat_interval": {
"type": "integer",
"default": 300,
"minimum": 30,
"maximum": 3600
},
"timeout": {
"type": "integer",
"default": 3600,
"minimum": 60,
"maximum": 86400
},
"hooks": {
"type": "object",
"properties": {
"pre_prompt_submit": {
"type": "boolean",
"default": true
},
"post_session": {
"type": "boolean",
"default": false
}
}
}
}
},
"observability": {
"type": "object",
"description": "OpenTelemetry service identity for distributed tracing",
"properties": {
"service_name": {
"type": "string"
},
"service_namespace": {
"type": "string"
},
"service_version": {
"type": "string",
"pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+(-[a-zA-Z0-9.]+)?$"
},
"service_instance_id": {
"type": "string"
},
"resource_attributes": {
"type": "object",
"additionalProperties": {
"type": "string"
}
}
}
},
"security": {
"type": "object",
"description": "Security policies for identity management",
"properties": {
"token_encryption": {
"type": "string",
"enum": [
"none",
"at_rest",
"in_transit",
"both"
],
"default": "both"
},
"minimum_token_length": {
"type": "integer",
"default": 32
},
"prohibited_actions": {
"type": "array",
"items": {
"type": "string"
}
},
"required_approvals": {
"type": "object",
"properties": {
"force_push": {
"type": "boolean",
"default": true
},
"delete_protected_branch": {
"type": "boolean",
"default": true
},
"modify_ci_config": {
"type": "boolean",
"default": false
}
}
},
"rate_limits": {
"type": "object",
"properties": {
"requests_per_minute": {
"type": "integer",
"default": 60
},
"requests_per_hour": {
"type": "integer",
"default": 1000
},
"git_operations_per_hour": {
"type": "integer",
"default": 100
}
}
}
}
}
},
"additionalProperties": false
},
"Metadata": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$",
"maxLength": 253,
"description": "Resource identifier (DNS-1123 subdomain format for Kubernetes compatibility)"
},
"version": {
"type": "string",
"pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$",
"description": "Semantic version (semver 2.0.0)"
},
"description": {
"type": "string",
"maxLength": 2000,
"description": "Human-readable description"
},
"labels": {
"type": "object",
"additionalProperties": {
"type": "string",
"maxLength": 63
},
"description": "Key-value labels for organization and filtering"
},
"annotations": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Arbitrary metadata for tooling"
}
},
"additionalProperties": false
},
"TaskSpec": {
"type": "object",
"description": "Specification for deterministic, non-agentic workflow steps (kind: Task)",
"required": [
"execution"
],
"properties": {
"execution": {
"type": "object",
"description": "Execution configuration for the task",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"enum": [
"deterministic",
"idempotent",
"transactional"
],
"default": "deterministic",
"description": "Execution type: deterministic (pure function), idempotent (safe to retry), transactional (all-or-nothing)"
},
"runtime": {
"type": "string",
"description": "Target runtime environment",
"examples": [
"drupal",
"symfony",
"node",
"python",
"any"
]
},
"entrypoint": {
"type": "string",
"description": "Entry point for execution (class::method, function name, or script path)"
},
"timeout_seconds": {
"type": "integer",
"minimum": 1,
"maximum": 86400,
"default": 300,
"description": "Maximum execution time in seconds"
}
},
"additionalProperties": false
},
"capabilities": {
"type": "array",
"description": "Abstract capabilities this task requires (bound at runtime)",
"items": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]*$",
"description": "Capability identifier (e.g., publish_content, send_email)"
},
"uniqueItems": true,
"examples": [
[
"publish_content",
"send_notification"
],
[
"transform_data",
"validate_schema"
]
]
},
"input": {
"$ref": "#/definitions/JSONSchemaDefinition",
"description": "JSON Schema for task input validation"
},
"output": {
"$ref": "#/definitions/JSONSchemaDefinition",
"description": "JSON Schema for task output validation"
},
"batch": {
"type": "object",
"description": "Batch processing configuration",
"properties": {
"enabled": {
"type": "boolean",
"default": false,
"description": "Enable batch processing mode"
},
"parallelism": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"default": 10,
"description": "Maximum parallel executions"
},
"chunk_size": {
"type": "integer",
"minimum": 1,
"default": 100,
"description": "Items per batch chunk"
},
"retry": {
"type": "object",
"properties": {
"max_attempts": {
"type": "integer",
"minimum": 1,
"maximum": 10,
"default": 3
},
"backoff_strategy": {
"type": "string",
"enum": [
"fixed",
"exponential",
"linear"
],
"default": "exponential"
},
"initial_delay_ms": {
"type": "integer",
"minimum": 100,
"default": 1000
}
},
"additionalProperties": false
},
"on_item_error": {
"type": "string",
"enum": [
"skip",
"fail",
"retry"
],
"default": "retry",
"description": "Behavior when individual item fails"
}
},
"additionalProperties": false
},
"dependencies": {
"type": "array",
"description": "Other tasks or agents this task depends on",
"items": {
"type": "object",
"required": [
"ref"
],
"properties": {
"ref": {
"type": "string",
"description": "Reference to dependency (file path or name)"
},
"kind": {
"type": "string",
"enum": [
"Task",
"Agent"
],
"description": "Kind of dependency"
},
"optional": {
"type": "boolean",
"default": false,
"description": "Whether this dependency is optional"
}
},
"additionalProperties": false
}
},
"preconditions": {
"type": "array",
"description": "Conditions that must be true before task execution",
"items": {
"type": "object",
"required": [
"expression"
],
"properties": {
"expression": {
"type": "string",
"description": "Condition expression (e.g., '${{ input.status == \"draft\" }}')"
},
"error_message": {
"type": "string",
"description": "Error message if condition fails"
}
},
"additionalProperties": false
}
},
"postconditions": {
"type": "array",
"description": "Conditions that must be true after task execution",
"items": {
"type": "object",
"required": [
"expression"
],
"properties": {
"expression": {
"type": "string",
"description": "Condition expression"
},
"error_message": {
"type": "string"
}
},
"additionalProperties": false
}
},
"error_handling": {
"type": "object",
"description": "Error handling configuration",
"properties": {
"on_error": {
"type": "string",
"enum": [
"fail",
"retry",
"fallback",
"ignore"
],
"default": "fail"
},
"fallback_task": {
"type": "string",
"description": "Reference to fallback task on failure"
},
"error_mapping": {
"type": "object",
"description": "Map error codes to actions",
"additionalProperties": {
"type": "string",
"enum": [
"fail",
"retry",
"fallback",
"ignore"
]
}
}
},
"additionalProperties": false
},
"observability": {
"type": "object",
"description": "Observability configuration",
"properties": {
"logging": {
"type": "object",
"properties": {
"level": {
"type": "string",
"enum": [
"debug",
"info",
"warn",
"error"
],
"default": "info"
},
"include_input": {
"type": "boolean",
"default": false,
"description": "Log input data (caution: may contain sensitive data)"
},
"include_output": {
"type": "boolean",
"default": false,
"description": "Log output data"
}
}
},
"metrics": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"default": true
},
"custom_labels": {
"type": "object",
"additionalProperties": {
"type": "string"
}
}
}
},
"tracing": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"default": true
},
"sample_rate": {
"type": "number",
"minimum": 0,
"maximum": 1,
"default": 1
}
}
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"AgentSpec": {
"type": "object",
"description": "Specification for agentic loops with LLM (kind: Agent) - inherits from v0.2.9. Either 'role' or 'prompts.system.template' is required.",
"properties": {
"role": {
"type": "string",
"minLength": 1,
"description": "Agent role/system prompt (alternative: use prompts.system.template)"
},
"prompts": {
"type": "object",
"description": "Structured prompts configuration (alternative to role)",
"properties": {
"system": {
"type": "object",
"properties": {
"template": {
"type": "string",
"description": "System prompt template"
},
"version": {
"type": "string",
"description": "Prompt version"
}
}
}
},
"additionalProperties": true
},
"llm": {
"$ref": "#/definitions/LLMConfig"
},
"tools": {
"type": "array",
"items": {
"$ref": "#/definitions/Tool"
}
},
"autonomy": {
"$ref": "#/definitions/Autonomy"
},
"constraints": {
"$ref": "#/definitions/Constraints"
},
"state": {
"$ref": "#/definitions/State"
},
"observability": {
"$ref": "#/definitions/AgentObservability"
},
"safety": {
"$ref": "#/definitions/Safety"
},
"messaging": {
"$ref": "#/definitions/MessagingExtension",
"description": "Agent-to-agent messaging configuration (v0.3.2+)"
},
"functions": {
"type": "array",
"description": "A2A/OpenAI-style function definitions for structured tool calling",
"items": {
"$ref": "#/definitions/FunctionDefinition"
}
},
"identity": {
"$ref": "#/definitions/AgentIdentity",
"description": "Agent identity configuration including service accounts, authentication, and observability (v0.3.2+)"
},
"access": {
"$ref": "#/definitions/AccessTier",
"description": "Access tier configuration for separation of duties (v0.3.2+). Defines privilege level and allowed operations."
},
"separation": {
"$ref": "#/definitions/SeparationOfDuties",
"description": "Role separation configuration to prevent conflicts of interest (v0.3.2+)"
},
"delegation": {
"$ref": "#/definitions/DelegationConfig",
"description": "Delegation configuration for multi-agent hierarchies (v0.3.2+)"
},
"type": {
"type": "string",
"enum": [
"analyzer",
"worker",
"operator",
"supervisor",
"orchestrator",
"governor",
"specialist",
"critic"
],
"description": "Agent type classification aligned with access tiers (v0.3.2+)"
},
"taxonomy": {
"$ref": "#/definitions/TaxonomyClassification",
"description": "Taxonomy classification for domain and cross-cutting concerns (v0.3.2+)"
},
"compliance": {
"type": "object",
"description": "Regulatory compliance and data governance configuration",
"properties": {
"frameworks": {
"type": "array",
"description": "Applicable compliance frameworks",
"items": {
"type": "string",
"enum": [
"SOC2",
"HIPAA",
"GDPR",
"FedRAMP",
"PCI-DSS",
"ISO27001"
]
},
"uniqueItems": true
},
"data_residency": {
"type": "string",
"description": "Required data residency region (e.g., us-east-1, eu-west-1)"
},
"audit_logging": {
"type": "string",
"enum": [
"required",
"optional",
"disabled"
],
"default": "optional",
"description": "Audit logging requirement level"
},
"pii_handling": {
"type": "string",
"enum": [
"encrypt_at_rest",
"anonymize",
"redact",
"none"
],
"default": "none",
"description": "Personally Identifiable Information handling strategy"
}
},
"additionalProperties": false
},
"lifecycle": {
"type": "object",
"description": "Agent lifecycle and environment management configuration",
"properties": {
"environments": {
"type": "object",
"description": "Environment-specific configurations",
"additionalProperties": {
"type": "object",
"description": "Configuration for a specific environment (e.g., development, staging, production)",
"additionalProperties": true
}
},
"dependencies": {
"type": "array",
"description": "External dependencies required by this agent",
"items": {
"type": "object",
"required": [
"name",
"version"
],
"properties": {
"name": {
"type": "string",
"description": "Dependency name"
},
"version": {
"type": "string",
"description": "Dependency version (semver recommended)"
},
"type": {
"type": "string",
"enum": [
"runtime",
"build",
"optional"
],
"default": "runtime",
"description": "Dependency type"
},
"source": {
"type": "string",
"description": "Dependency source (e.g., npm, pip, composer, docker)"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
},
"additionalProperties": true
},
"WorkflowSpec": {
"type": "object",
"description": "Specification for workflow composition (kind: Workflow) - composes Tasks and Agents into executable pipelines",
"required": [
"steps"
],
"properties": {
"triggers": {
"type": "array",
"description": "Events that trigger workflow execution",
"items": {
"$ref": "#/definitions/Trigger"
}
},
"inputs": {
"$ref": "#/definitions/JSONSchemaDefinition",
"description": "JSON Schema for workflow input validation"
},
"outputs": {
"$ref": "#/definitions/JSONSchemaDefinition",
"description": "JSON Schema for workflow output validation"
},
"steps": {
"type": "array",
"description": "Workflow steps (Tasks and/or Agents)",
"minItems": 1,
"items": {
"$ref": "#/definitions/WorkflowStep"
}
},
"context": {
"type": "object",
"description": "Shared context available to all steps",
"properties": {
"variables": {
"type": "object",
"description": "Workflow-level variables",
"additionalProperties": true
},
"secrets": {
"type": "array",
"description": "Secret references available to steps",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Secret name available to steps"
},
"ref": {
"type": "string",
"description": "Secret reference (e.g., vault://secret/api-key)"
}
},
"required": [
"name",
"ref"
]
}
}
},
"additionalProperties": false
},
"concurrency": {
"type": "object",
"description": "Concurrency control",
"properties": {
"group": {
"type": "string",
"description": "Concurrency group name (workflows in same group are serialized)"
},
"cancel_in_progress": {
"type": "boolean",
"default": false,
"description": "Cancel running workflow if new one starts in same group"
}
},
"additionalProperties": false
},
"error_handling": {
"type": "object",
"description": "Workflow-level error handling",
"properties": {
"on_failure": {
"type": "string",
"enum": [
"halt",
"continue",
"rollback",
"notify",
"compensate",
"compensation"
],
"default": "halt",
"description": "Action on step failure"
},
"compensation_steps": {
"type": "array",
"description": "Steps to run on rollback/compensate",
"items": {
"$ref": "#/definitions/WorkflowStep"
}
},
"notification": {
"type": "object",
"description": "Notification on failure",
"properties": {
"channels": {
"type": "array",
"items": {
"type": "string",
"enum": [
"email",
"slack",
"webhook",
"pagerduty"
]
}
},
"template": {
"type": "string",
"description": "Notification template reference"
}
}
},
"retry_policy": {
"type": "object",
"properties": {
"max_attempts": {
"type": "integer",
"minimum": 1,
"maximum": 10,
"default": 3
},
"backoff": {
"type": "string",
"enum": [
"fixed",
"exponential",
"linear"
],
"default": "exponential"
},
"initial_delay_ms": {
"type": "integer",
"minimum": 100,
"default": 1000
},
"max_delay_ms": {
"type": "integer",
"default": 60000
}
}
}
},
"additionalProperties": true
},
"timeout_seconds": {
"type": "integer",
"minimum": 1,
"maximum": 86400,
"description": "Maximum workflow execution time in seconds"
},
"observability": {
"type": "object",
"description": "Workflow observability configuration",
"properties": {
"tracing": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"default": true
},
"propagate_context": {
"type": "boolean",
"default": true,
"description": "Propagate trace context to steps"
}
}
},
"metrics": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"default": true
},
"custom_labels": {
"type": "object",
"additionalProperties": {
"type": "string"
}
}
}
},
"logging": {
"type": "object",
"properties": {
"level": {
"type": "string",
"enum": [
"debug",
"info",
"warn",
"error"
],
"default": "info"
}
}
}
},
"additionalProperties": true
}
},
"additionalProperties": true
},
"RuntimeBinding": {
"type": "object",
"description": "Multi-runtime compatibility declaration",
"properties": {
"type": {
"type": "string",
"description": "Primary runtime type",
"enum": [
"unified",
"google-a2a",
"gitlab-duo",
"ossa-mesh",
"mcp",
"local",
"drupal",
"symfony_messenger",
"kagent",
"temporal",
"node"
],
"default": "unified"
},
"supports": {
"type": "array",
"description": "List of compatible runtimes",
"items": {
"type": "string",
"enum": [
"google-a2a",
"gitlab-duo",
"ossa-mesh",
"mcp",
"local-execution",
"kubernetes",
"serverless",
"lambda",
"cloudflare-workers",
"drupal",
"symfony"
]
},
"uniqueItems": true
},
"transport": {
"type": "string",
"description": "Message transport for async runtimes",
"examples": [
"async",
"sync",
"amqp",
"redis"
]
},
"scheduling": {
"$ref": "#/definitions/SchedulingConfig",
"description": "Agent scheduling configuration"
},
"resource_limits": {
"$ref": "#/definitions/ResourceLimits",
"description": "Compute resource constraints"
},
"extensions": {
"type": "array",
"description": "External runtime extensions",
"items": {
"$ref": "#/definitions/RuntimeExtension"
}
},
"bindings": {
"type": "object",
"description": "Map of capability names to runtime-specific handlers",
"additionalProperties": {
"type": "object",
"properties": {
"handler": {
"type": "string",
"description": "Handler class/function (e.g., 'Drupal\\node\\NodeQuery::getList')"
},
"mcp_server": {
"type": "string",
"description": "MCP server name for MCP-based bindings"
},
"tool": {
"type": "string",
"description": "Tool name within MCP server"
},
"config": {
"type": "object",
"description": "Additional binding configuration",
"additionalProperties": true
}
},
"additionalProperties": false
}
},
"kubernetes": {
"$ref": "#/definitions/KubernetesConfig",
"description": "Kubernetes-specific configuration (KAS-inspired)"
}
},
"additionalProperties": false
},
"Trigger": {
"type": "object",
"description": "Workflow trigger configuration",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"enum": [
"webhook",
"cron",
"event",
"manual"
],
"description": "Trigger type"
},
"path": {
"type": "string",
"description": "Webhook path (for type=webhook)"
},
"schedule": {
"type": "string",
"description": "Cron expression (for type=cron)",
"examples": [
"0 8 * * *",
"*/15 * * * *"
]
},
"source": {
"type": "string",
"description": "Event source (for type=event)",
"examples": [
"drupal",
"kafka",
"webhook"
]
},
"event": {
"type": "string",
"description": "Event name (for type=event)",
"examples": [
"node.created",
"user.login",
"order.placed"
]
},
"filter": {
"type": "object",
"description": "Event filter conditions",
"additionalProperties": true
}
},
"additionalProperties": true
},
"WorkflowStep": {
"type": "object",
"description": "A step in a workflow - can be a Task, Agent, or control structure",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"pattern": "^[a-z][a-z0-9_-]*$",
"description": "Step identifier (unique within workflow)"
},
"name": {
"type": "string",
"description": "Human-readable step name for display"
},
"kind": {
"type": "string",
"enum": [
"Task",
"Agent",
"Parallel",
"Conditional",
"Loop"
],
"description": "Step type"
},
"ref": {
"type": "string",
"description": "Reference to Task or Agent manifest file",
"examples": [
"./tasks/publish-content.yaml",
"./agents/content-reviewer.yaml"
]
},
"inline": {
"type": "object",
"description": "Inline Task or Agent specification (alternative to ref)"
},
"input": {
"type": "object",
"description": "Input mapping using expression syntax",
"additionalProperties": true,
"examples": [
{
"content": "${{ steps.fetch.output.content }}",
"priority": "${{ workflow.input.priority }}"
}
]
},
"output": {
"type": "object",
"description": "Output mapping to workflow context",
"properties": {
"to": {
"type": "string",
"description": "Variable name to store output"
},
"fields": {
"type": "array",
"items": {
"type": "string"
},
"description": "Specific fields to extract from output"
}
}
},
"condition": {
"type": "string",
"description": "Condition expression for conditional execution",
"examples": [
"${{ steps.review.output.approved }}",
"${{ workflow.input.priority == 'high' }}",
"${{ steps.check.output.status == 'ready' && context.retry_count < 3 }}"
]
},
"depends_on": {
"type": "array",
"description": "Explicit dependencies on other steps",
"items": {
"type": "string"
},
"examples": [
[
"fetch",
"validate"
]
]
},
"parallel": {
"type": "array",
"description": "Steps to run in parallel (for kind: Parallel)",
"items": {
"$ref": "#/definitions/WorkflowStep"
}
},
"branches": {
"type": "array",
"description": "Conditional branches (for kind: Conditional)",
"items": {
"type": "object",
"properties": {
"condition": {
"type": "string",
"description": "Branch condition expression"
},
"steps": {
"type": "array",
"items": {
"$ref": "#/definitions/WorkflowStep"
}
}
},
"required": [
"condition",
"steps"
]
}
},
"else": {
"type": "array",
"description": "Steps to run if no branch condition matches (for kind: Conditional)",
"items": {
"$ref": "#/definitions/WorkflowStep"
}
},
"loop": {
"type": "object",
"description": "Loop configuration (for kind: Loop)",
"properties": {
"over": {
"type": "string",
"description": "Expression returning array to iterate over",
"examples": [
"${{ steps.fetch.output.items }}",
"${{ workflow.input.recipients }}"
]
},
"as": {
"type": "string",
"description": "Variable name for current item",
"default": "item"
},
"index": {
"type": "string",
"description": "Variable name for current index",
"default": "index"
},
"parallelism": {
"type": "integer",
"minimum": 1,
"description": "Maximum parallel iterations"
}
},
"required": [
"over"
]
},
"steps": {
"type": "array",
"description": "Nested steps (for Loop and Conditional kinds)",
"items": {
"$ref": "#/definitions/WorkflowStep"
}
},
"retry": {
"type": "object",
"description": "Step-specific retry configuration",
"properties": {
"max_attempts": {
"type": "integer",
"minimum": 1,
"maximum": 10,
"default": 3
},
"backoff_strategy": {
"type": "string",
"enum": [
"fixed",
"exponential",
"linear"
],
"default": "exponential"
},
"initial_delay_ms": {
"type": "integer",
"minimum": 100,
"default": 1000
},
"retryable_errors": {
"type": "array",
"items": {
"type": "string"
},
"description": "Error codes that should trigger retry"
}
}
},
"timeout_seconds": {
"type": "integer",
"minimum": 1,
"maximum": 86400,
"description": "Step-specific timeout"
},
"continue_on_error": {
"type": "boolean",
"default": false,
"description": "Continue workflow even if this step fails"
},
"on_error": {
"type": "object",
"description": "Step-specific error handling",
"properties": {
"action": {
"type": "string",
"enum": [
"fail",
"continue",
"goto",
"compensate"
],
"default": "fail"
},
"goto": {
"type": "string",
"description": "Step ID to jump to on error (for action: goto)"
},
"compensation": {
"$ref": "#/definitions/WorkflowStep",
"description": "Compensation step to run on error"
}
}
},
"labels": {
"type": "object",
"description": "Step labels for filtering and organization",
"additionalProperties": {
"type": "string"
}
}
},
"additionalProperties": true
},
"JSONSchemaDefinition": {
"type": "object",
"description": "JSON Schema definition for input/output validation",
"properties": {
"type": {
"type": "string",
"enum": [
"object",
"array",
"string",
"number",
"integer",
"boolean",
"null"
]
},
"properties": {
"type": "object",
"additionalProperties": true
},
"required": {
"type": "array",
"items": {
"type": "string"
}
},
"items": {
"type": "object"
},
"additionalProperties": {
"type": [
"boolean",
"object"
]
}
},
"additionalProperties": true
},
"LLMConfig": {
"type": "object",
"required": [
"provider",
"model"
],
"properties": {
"provider": {
"description": "LLM provider - literal value or environment variable with default (e.g., ${LLM_PROVIDER:-anthropic})",
"anyOf": [
{
"type": "string",
"enum": [
"openai",
"anthropic",
"google",
"azure",
"ollama",
"mistral",
"cohere",
"groq",
"together",
"fireworks",
"deepseek",
"custom"
]
},
{
"type": "string",
"pattern": "^[$]\\{[A-Za-z_][A-Za-z0-9_]*(?::-[a-zA-Z0-9_-]+)?\\}$",
"description": "Environment variable reference with optional default"
}
]
},
"model": {
"type": "string",
"description": "Model identifier (e.g., gpt-4o, claude-sonnet-4.5-20250929)"
},
"temperature": {
"type": "number",
"minimum": 0,
"maximum": 2,
"description": "Sampling temperature for response generation"
},
"maxTokens": {
"type": "integer",
"minimum": 1,
"description": "Maximum tokens in response"
},
"fallback_models": {
"type": "array",
"description": "Ordered list of fallback LLM configurations for resilience",
"items": {
"$ref": "#/definitions/FallbackLLM"
}
},
"retry_config": {
"$ref": "#/definitions/RetryConfig",
"description": "Retry and backoff configuration for transient failures"
},
"cost_tracking": {
"$ref": "#/definitions/CostTracking",
"description": "Cost governance and allocation tracking"
},
"profile": {
"description": "Execution profile for task-specific optimization (A2A compatible)",
"anyOf": [
{
"type": "string",
"enum": [
"fast",
"balanced",
"deep",
"safe"
]
},
{
"type": "string",
"pattern": "^[$]\\{[A-Za-z_][A-Za-z0-9_]*(?::-[a-zA-Z0-9_-]+)?\\}$",
"description": "Environment variable reference with optional default"
}
],
"default": "balanced"
},
"execution_profiles": {
"$ref": "#/definitions/ExecutionProfiles",
"description": "Custom execution profile definitions"
}
},
"additionalProperties": true
},
"FallbackLLM": {
"type": "object",
"description": "Fallback LLM configuration for resilience",
"required": [
"provider",
"model"
],
"properties": {
"provider": {
"description": "LLM provider - literal value or environment variable",
"anyOf": [
{
"type": "string",
"enum": [
"openai",
"anthropic",
"google",
"azure",
"ollama",
"mistral",
"cohere",
"groq",
"together",
"fireworks",
"deepseek",
"custom"
]
},
{
"type": "string",
"pattern": "^[$]\\{[A-Za-z_][A-Za-z0-9_]*(?::-[a-zA-Z0-9_-]+)?\\}$"
}
]
},
"model": {
"type": "string",
"description": "Model identifier"
},
"temperature": {
"type": "number",
"minimum": 0,
"maximum": 2
},
"trigger": {
"type": "object",
"description": "Conditions that trigger fallback",
"properties": {
"on_error": {
"type": "boolean",
"description": "Trigger on any error from primary"
},
"max_retries": {
"type": "integer",
"description": "Retries before falling back"
},
"error_codes": {
"type": "array",
"items": {
"type": "integer"
},
"description": "Specific error codes to trigger on"
},
"latency_threshold_ms": {
"type": "integer",
"description": "Trigger when latency exceeds this threshold"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
},
"RetryConfig": {
"type": "object",
"description": "Retry and backoff configuration for LLM calls",
"properties": {
"max_attempts": {
"type": "integer",
"minimum": 1,
"maximum": 10,
"default": 3,
"description": "Maximum number of retry attempts"
},
"backoff_strategy": {
"type": "string",
"enum": [
"none",
"linear",
"exponential"
],
"default": "exponential",
"description": "Backoff strategy between retries"
},
"initial_delay_ms": {
"type": "integer",
"minimum": 0,
"default": 1000,
"description": "Initial delay in milliseconds before first retry"
},
"max_delay_ms": {
"type": "integer",
"minimum": 0,
"default": 30000,
"description": "Maximum delay between retries"
}
},
"additionalProperties": false
},
"CostTracking": {
"type": "object",
"description": "Cost governance and allocation tracking for LLM usage",
"properties": {
"enabled": {
"type": "boolean",
"default": false,
"description": "Enable cost tracking for this agent"
},
"budget_alert_threshold": {
"type": "number",
"minimum": 0,
"description": "Alert threshold in dollars for budget monitoring"
},
"cost_allocation_tags": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Tags for cost allocation and chargeback (e.g., project, team, service)"
}
},
"additionalProperties": false
},
"Tool": {
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"enum": [
"mcp",
"kubernetes",
"http",
"api",
"grpc",
"function",
"a2a",
"webhook",
"schedule",
"pipeline",
"workflow",
"artifact",
"git-commit",
"ci-status",
"comment",
"library",
"custom"
],
"description": "Tool/trigger type: mcp (Model Context Protocol), kubernetes (K8s API), http (HTTP endpoints), api (REST APIs), grpc (gRPC), function (local), a2a (agent-to-agent), webhook (event triggers), schedule (cron triggers), pipeline (CI/CD events), workflow (status changes), artifact (file outputs), git-commit (commit outputs), ci-status (pipeline status), comment (MR/issue comments), library (reusable logic), custom"
},
"name": {
"type": "string"
},
"capabilities": {
"type": "array",
"items": {
"$ref": "#/definitions/Capability"
}
}
},
"additionalProperties": true
},
"Capability": {
"description": "Capability definition - can be a simple string name or a detailed object",
"anyOf": [
{
"type": "string",
"description": "Simple capability name"
},
{
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"version": {
"type": "string",
"description": "Capability version"
},
"description": {
"type": "string"
},
"scopes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Required scopes/permissions"
},
"transport": {
"type": "object",
"description": "Transport binding configuration"
},
"input_schema": {
"type": "object"
},
"output_schema": {
"type": "object"
}
},
"additionalProperties": true
}
]
},
"Autonomy": {
"type": "object",
"description": "Agent autonomy configuration",
"properties": {
"level": {
"type": "string",
"enum": [
"supervised",
"assisted",
"semi_autonomous",
"autonomous",
"fully_autonomous"
],
"description": "Autonomy level: supervised (all approval), assisted (guidance with approval), semi_autonomous (limited autonomy), autonomous (self-directed), fully_autonomous (no oversight)"
},
"approval_required": {
"description": "Whether human approval is required, or list of specific actions requiring approval",
"anyOf": [
{
"type": "boolean"
},
{
"type": "array",
"items": {
"type": "string"
},
"description": "List of action types that require human approval"
}
]
},
"allowed_actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Actions the agent is allowed to perform"
},
"blocked_actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Actions the agent is explicitly blocked from"
},
"escalation_policy": {
"type": "object",
"description": "Policy for escalating to humans or other agents",
"properties": {
"triggers": {
"type": "array",
"items": {
"type": "string"
},
"description": "Conditions that trigger escalation"
},
"notify": {
"type": "array",
"items": {
"type": "string"
},
"description": "Notification channels (e.g., slack:#channel, gitlab:@team)"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
},
"Constraints": {
"type": "object",
"description": "Agent resource and operational constraints",
"properties": {
"cost": {
"type": "object",
"description": "Cost constraints for LLM usage",
"properties": {
"maxTokensPerDay": {
"type": "integer",
"description": "Maximum tokens per day"
},
"maxTokensPerRequest": {
"type": "integer",
"description": "Maximum tokens per request"
},
"maxCostPerDay": {
"type": "number",
"description": "Maximum cost per day"
},
"currency": {
"type": "string",
"description": "Currency for cost tracking (e.g., USD, EUR)"
}
},
"additionalProperties": true
},
"performance": {
"type": "object",
"description": "Performance constraints",
"properties": {
"maxLatencySeconds": {
"type": "number",
"description": "Maximum response latency in seconds"
},
"maxConcurrentRequests": {
"type": "integer",
"description": "Maximum concurrent requests"
},
"timeoutSeconds": {
"type": "number",
"description": "Request timeout in seconds"
}
},
"additionalProperties": true
},
"resources": {
"type": "object",
"description": "Compute resource constraints (Kubernetes-style)",
"properties": {
"cpu": {
"type": "string",
"description": "CPU limit (e.g., '1', '500m')"
},
"memory": {
"type": "string",
"description": "Memory limit (e.g., '2Gi', '512Mi')"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
},
"State": {
"type": "object",
"description": "Agent state management configuration",
"properties": {
"mode": {
"type": "string",
"enum": [
"stateless",
"session",
"long_running"
],
"description": "State persistence mode"
},
"storage": {
"type": "object",
"description": "State storage configuration",
"properties": {
"type": {
"type": "string",
"enum": [
"memory",
"vector-db",
"kv",
"rdbms",
"custom"
],
"description": "Storage backend type"
},
"retention": {
"type": "string",
"description": "Data retention period (e.g., '30d', '1h')"
},
"config": {
"type": "object",
"description": "Storage-specific configuration",
"properties": {
"provider": {
"type": "string",
"description": "Storage provider (e.g., redis, postgres, pinecone)"
},
"prefix": {
"type": "string",
"description": "Key prefix for namespacing"
},
"endpoint": {
"type": "string",
"description": "Storage endpoint URL"
}
},
"additionalProperties": true
},
"encryption": {
"type": "object",
"description": "Storage encryption configuration",
"properties": {
"enabled": {
"type": "boolean"
},
"algorithm": {
"type": "string",
"description": "Encryption algorithm (e.g., aes-256-gcm)"
},
"keyRef": {
"type": "string",
"description": "Reference to encryption key (e.g., env:ENCRYPTION_KEY)"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
},
"context_window": {
"type": "object",
"description": "Context window management for conversation history",
"properties": {
"max_messages": {
"type": "integer",
"description": "Maximum messages to retain"
},
"max_tokens": {
"type": "integer",
"description": "Maximum tokens in context"
},
"strategy": {
"type": "string",
"enum": [
"truncation",
"summarization",
"sliding_window"
],
"description": "Strategy for managing context overflow"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
},
"AgentObservability": {
"type": "object",
"description": "Agent observability configuration",
"properties": {
"tracing": {
"type": "object",
"description": "Distributed tracing configuration",
"properties": {
"enabled": {
"type": "boolean"
},
"exporter": {
"type": "string",
"description": "Trace exporter (e.g., otlp, jaeger, zipkin)"
},
"endpoint": {
"type": "string",
"description": "Trace collector endpoint"
}
},
"additionalProperties": true
},
"metrics": {
"type": "object",
"description": "Metrics collection configuration",
"properties": {
"enabled": {
"type": "boolean"
},
"exporter": {
"type": "string",
"description": "Metrics exporter (e.g., prometheus, otlp)"
},
"endpoint": {
"type": "string",
"description": "Metrics endpoint"
},
"port": {
"type": "integer",
"description": "Metrics server port"
},
"customMetrics": {
"type": "array",
"description": "Custom metrics definitions",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"counter",
"gauge",
"histogram"
]
},
"description": {
"type": "string"
}
}
}
}
},
"additionalProperties": true
},
"logging": {
"type": "object",
"description": "Logging configuration",
"properties": {
"level": {
"type": "string",
"enum": [
"debug",
"info",
"warn",
"error"
],
"description": "Log level"
},
"format": {
"type": "string",
"enum": [
"json",
"text"
],
"description": "Log format"
}
},
"additionalProperties": true
},
"alerting": {
"type": "object",
"description": "Alerting configuration",
"properties": {
"enabled": {
"type": "boolean"
},
"channels": {
"type": "array",
"items": {
"type": "string"
}
},
"rules": {
"type": "array",
"items": {
"type": "object"
}
}
},
"additionalProperties": true
},
"slo": {
"type": "object",
"description": "Service level objectives",
"properties": {
"availability": {
"type": "number"
},
"latency_p95_ms": {
"type": "integer"
},
"error_budget": {
"type": "number"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
},
"Safety": {
"type": "object",
"description": "Agent safety and security configuration",
"properties": {
"content_filtering": {
"type": "object",
"description": "Content filtering for inputs/outputs",
"properties": {
"enabled": {
"type": "boolean"
},
"categories": {
"type": "array",
"items": {
"type": "string"
},
"description": "Categories to filter (e.g., pii, credentials)"
},
"threshold": {
"type": "string",
"enum": [
"low",
"medium",
"high"
],
"description": "Filtering sensitivity"
},
"action": {
"type": "string",
"enum": [
"warn",
"block",
"redact"
],
"description": "Action when content matches"
}
},
"additionalProperties": true
},
"pii_detection": {
"type": "object",
"description": "PII detection and handling",
"properties": {
"enabled": {
"type": "boolean"
},
"types": {
"type": "array",
"items": {
"type": "string"
},
"description": "PII types to detect (email, phone, ssn, api_key, etc.)"
},
"action": {
"type": "string",
"enum": [
"warn",
"block",
"redact"
],
"description": "Action when PII detected"
}
},
"additionalProperties": true
},
"rate_limiting": {
"type": "object",
"description": "Rate limiting configuration",
"properties": {
"enabled": {
"type": "boolean"
},
"requests_per_minute": {
"type": "integer"
},
"burst_limit": {
"type": "integer"
}
},
"additionalProperties": true
},
"guardrails": {
"type": "object",
"description": "Guardrails for agent behavior",
"properties": {
"enabled": {
"type": "boolean"
},
"policies": {
"type": "array",
"items": {
"type": "object"
},
"description": "Policy definitions"
},
"max_tool_calls": {
"type": "integer",
"description": "Maximum tool calls per turn"
},
"max_execution_time_seconds": {
"type": "integer",
"description": "Maximum execution time"
}
},
"additionalProperties": true
},
"human_in_loop": {
"type": "object",
"description": "Human-in-the-loop configuration",
"properties": {
"enabled": {
"type": "boolean"
},
"triggers": {
"type": "array",
"items": {
"type": "string"
},
"description": "Conditions that require human approval"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
},
"MCPExtension": {
"type": "object",
"description": "Model Context Protocol (MCP) extension for agents - supports tools, resources, and prompts",
"properties": {
"enabled": {
"type": "boolean",
"default": true,
"description": "Whether MCP is enabled for this agent"
},
"server_type": {
"type": "string",
"enum": [
"stdio",
"http",
"sse"
],
"description": "MCP server transport mechanism"
},
"server_name": {
"type": "string",
"description": "Name of the MCP server"
},
"tools": {
"type": "array",
"description": "MCP tools (functions/actions the agent can invoke)",
"items": {
"$ref": "#/definitions/MCPTool"
}
},
"resources": {
"type": "array",
"description": "MCP resources (read-only context/data sources)",
"items": {
"$ref": "#/definitions/MCPResource"
}
},
"prompts": {
"type": "array",
"description": "MCP prompts (templated workflows and interactions)",
"items": {
"$ref": "#/definitions/MCPPrompt"
}
}
},
"additionalProperties": false
},
"MCPTool": {
"type": "object",
"description": "MCP tool definition - actions/functions the agent can invoke",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"description": "Unique tool name"
},
"description": {
"type": "string",
"description": "Human-readable description of what the tool does"
},
"input_schema": {
"$ref": "#/definitions/JSONSchemaDefinition",
"description": "JSON Schema for tool input parameters (snake_case)"
},
"inputSchema": {
"$ref": "#/definitions/JSONSchemaDefinition",
"description": "JSON Schema for tool input parameters (camelCase - MCP SDK convention)"
}
},
"additionalProperties": true
},
"MCPResource": {
"type": "object",
"description": "MCP resource definition - read-only context and data sources",
"required": [
"uri",
"name"
],
"properties": {
"uri": {
"type": "string",
"format": "uri",
"description": "Unique resource identifier (URI)"
},
"name": {
"type": "string",
"description": "Human-readable resource name"
},
"description": {
"type": "string",
"description": "Description of the resource and its contents"
},
"mimeType": {
"type": "string",
"description": "MIME type of the resource content",
"examples": [
"text/plain",
"application/json",
"text/markdown",
"image/png"
]
},
"metadata": {
"type": "object",
"description": "Additional resource metadata",
"additionalProperties": true
}
},
"additionalProperties": false
},
"MCPPrompt": {
"type": "object",
"description": "MCP prompt definition - templated messages and workflows",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"description": "Unique prompt identifier"
},
"description": {
"type": "string",
"description": "Human-readable description of the prompt purpose"
},
"arguments": {
"type": "array",
"description": "Template arguments that can be substituted",
"items": {
"$ref": "#/definitions/MCPPromptArgument"
}
}
},
"additionalProperties": false
},
"MCPPromptArgument": {
"type": "object",
"description": "Argument definition for MCP prompts",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"description": "Argument name"
},
"description": {
"type": "string",
"description": "Description of what this argument represents"
},
"required": {
"type": "boolean",
"default": false,
"description": "Whether this argument is required"
}
},
"additionalProperties": false
},
"MessagingExtension": {
"type": "object",
"description": "Agent-to-agent messaging configuration (v0.3.2+)",
"properties": {
"publishes": {
"type": "array",
"description": "Channels this agent publishes to",
"items": {
"$ref": "#/definitions/PublishedChannel"
}
},
"subscribes": {
"type": "array",
"description": "Channels this agent subscribes to",
"items": {
"$ref": "#/definitions/Subscription"
}
},
"commands": {
"type": "array",
"description": "Commands this agent accepts (RPC-style operations)",
"items": {
"$ref": "#/definitions/Command"
}
},
"reliability": {
"$ref": "#/definitions/ReliabilityConfig",
"description": "Message reliability configuration"
}
},
"additionalProperties": false
},
"PublishedChannel": {
"type": "object",
"description": "Channel that an agent publishes messages to",
"required": [
"channel",
"schema"
],
"properties": {
"channel": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)*$",
"description": "Channel name (e.g., 'security.vulnerabilities')"
},
"description": {
"type": "string",
"description": "Human-readable description of the channel"
},
"schema": {
"type": "object",
"description": "JSON Schema for published messages",
"additionalProperties": true
},
"examples": {
"type": "array",
"description": "Example messages",
"items": {
"type": "object",
"additionalProperties": true
}
},
"contentType": {
"type": "string",
"description": "Content type of messages",
"default": "application/json"
},
"tags": {
"type": "array",
"description": "Tags for categorization",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
},
"Subscription": {
"type": "object",
"description": "Channel subscription configuration",
"required": [
"channel"
],
"properties": {
"channel": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)*$",
"description": "Channel name to subscribe to"
},
"description": {
"type": "string",
"description": "Human-readable description"
},
"schema": {
"type": "object",
"description": "Expected message schema",
"additionalProperties": true
},
"handler": {
"type": "string",
"description": "Handler function name"
},
"filter": {
"type": "object",
"description": "Message filter configuration - supports JSONPath-style filtering",
"properties": {
"expression": {
"type": "string",
"description": "Filter expression"
},
"fields": {
"type": "object",
"description": "Field-based filters",
"additionalProperties": true
}
},
"additionalProperties": true
},
"priority": {
"type": "string",
"enum": [
"low",
"normal",
"high",
"critical"
],
"default": "normal",
"description": "Message priority"
},
"maxConcurrency": {
"type": "integer",
"minimum": 1,
"description": "Maximum concurrent message processing"
}
},
"additionalProperties": false
},
"Command": {
"type": "object",
"description": "RPC-style command that an agent accepts",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]*$",
"description": "Command name (snake_case)"
},
"description": {
"type": "string",
"description": "Human-readable description"
},
"inputSchema": {
"type": "object",
"description": "JSON Schema for command input (camelCase)",
"additionalProperties": true
},
"input_schema": {
"type": "object",
"description": "JSON Schema for command input (snake_case alias)",
"additionalProperties": true
},
"outputSchema": {
"type": "object",
"description": "JSON Schema for command output (camelCase)",
"additionalProperties": true
},
"output_schema": {
"type": "object",
"description": "JSON Schema for command output (snake_case alias)",
"additionalProperties": true
},
"timeoutSeconds": {
"type": "integer",
"minimum": 1,
"maximum": 3600,
"description": "Command execution timeout in seconds"
},
"timeout_seconds": {
"type": "integer",
"minimum": 1,
"maximum": 3600,
"description": "Command execution timeout (snake_case alias)"
},
"idempotent": {
"type": "boolean",
"default": false,
"description": "Whether the command is idempotent"
},
"async": {
"type": "boolean",
"default": false,
"description": "Whether the command executes asynchronously"
}
},
"additionalProperties": true
},
"ReliabilityConfig": {
"type": "object",
"description": "Message delivery reliability configuration",
"properties": {
"deliveryGuarantee": {
"type": "string",
"enum": [
"at-least-once",
"at-most-once",
"exactly-once",
"at_least_once",
"at_most_once",
"exactly_once"
],
"default": "at-least-once",
"description": "Message delivery guarantee"
},
"delivery": {
"type": "string",
"enum": [
"at-least-once",
"at-most-once",
"exactly-once",
"at_least_once",
"at_most_once",
"exactly_once"
],
"description": "Message delivery guarantee (alias for deliveryGuarantee)"
},
"retry": {
"type": "object",
"description": "Retry configuration",
"properties": {
"maxAttempts": {
"type": "integer",
"minimum": 0,
"maximum": 10,
"default": 3,
"description": "Maximum retry attempts"
},
"backoff": {
"type": "object",
"description": "Backoff strategy configuration",
"properties": {
"strategy": {
"type": "string",
"enum": [
"exponential",
"linear",
"constant"
],
"default": "exponential",
"description": "Backoff strategy"
},
"initialDelayMs": {
"type": "integer",
"minimum": 0,
"default": 1000,
"description": "Initial delay in milliseconds"
},
"maxDelayMs": {
"type": "integer",
"minimum": 0,
"default": 60000,
"description": "Maximum delay in milliseconds"
},
"multiplier": {
"type": "number",
"minimum": 1,
"default": 2,
"description": "Backoff multiplier"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"dlq": {
"type": "object",
"description": "Dead letter queue configuration",
"properties": {
"enabled": {
"type": "boolean",
"default": false,
"description": "Enable dead letter queue"
},
"channel": {
"type": "string",
"description": "Dead letter queue channel name"
},
"retentionDays": {
"type": "integer",
"minimum": 1,
"maximum": 90,
"default": 7,
"description": "Message retention in days"
}
},
"additionalProperties": false
},
"ordering": {
"type": "object",
"description": "Message ordering configuration",
"properties": {
"guarantee": {
"type": "string",
"enum": [
"per-source",
"global"
],
"default": "per-source",
"description": "Ordering guarantee level"
},
"mode": {
"type": "string",
"enum": [
"global",
"per_channel",
"per-channel",
"none"
],
"description": "Ordering mode (alias for guarantee)"
},
"timeoutSeconds": {
"type": "integer",
"minimum": 1,
"description": "Ordering timeout in seconds"
}
},
"additionalProperties": true
},
"acknowledgment": {
"type": "object",
"description": "Message acknowledgment configuration",
"properties": {
"mode": {
"type": "string",
"enum": [
"manual",
"automatic"
],
"default": "automatic",
"description": "Acknowledgment mode"
},
"timeoutSeconds": {
"type": "integer",
"minimum": 1,
"default": 30,
"description": "Acknowledgment timeout in seconds"
}
},
"additionalProperties": false
}
},
"additionalProperties": true
},
"ExecutionProfiles": {
"type": "object",
"description": "Execution profile presets for different use cases",
"properties": {
"default": {
"type": "string",
"description": "Default profile name"
},
"profiles": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/ExecutionProfileConfig"
}
}
}
},
"ExecutionProfileConfig": {
"type": "object",
"description": "Individual execution profile configuration",
"properties": {
"maxTokens": {
"type": "integer",
"minimum": 1,
"description": "Maximum tokens for this profile"
},
"temperature": {
"type": "number",
"minimum": 0,
"maximum": 2,
"description": "Sampling temperature"
},
"reasoning_enabled": {
"type": "boolean",
"default": false,
"description": "Enable extended thinking/reasoning"
},
"validation_required": {
"type": "boolean",
"default": false,
"description": "Require output validation"
},
"audit_log": {
"type": "boolean",
"default": false,
"description": "Enable detailed audit logging"
},
"description": {
"type": "string",
"description": "Profile description"
}
},
"additionalProperties": false
},
"FunctionDefinition": {
"type": "object",
"description": "Function definition in A2A/OpenAI format",
"required": [
"name",
"description",
"parameters"
],
"properties": {
"name": {
"type": "string",
"pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$",
"description": "Function name"
},
"description": {
"type": "string",
"description": "What the function does"
},
"parameters": {
"$ref": "#/definitions/JSONSchemaDefinition",
"description": "JSON Schema for function parameters"
},
"returns": {
"$ref": "#/definitions/JSONSchemaDefinition",
"description": "JSON Schema for return value"
},
"strict": {
"type": "boolean",
"default": true,
"description": "Enforce strict schema validation"
}
},
"additionalProperties": false
},
"SchedulingConfig": {
"type": "object",
"description": "Agent scheduling configuration",
"properties": {
"strategy": {
"type": "string",
"enum": [
"fair",
"priority",
"deadline",
"cost-optimized"
],
"default": "fair",
"description": "Scheduling strategy"
},
"priority": {
"type": "string",
"enum": [
"critical",
"high",
"normal",
"low",
"background"
],
"default": "normal",
"description": "Execution priority"
},
"max_concurrent": {
"type": "integer",
"minimum": 1,
"default": 10,
"description": "Maximum concurrent executions"
},
"timeout_seconds": {
"type": "integer",
"minimum": 1,
"default": 300,
"description": "Execution timeout in seconds"
}
},
"additionalProperties": false
},
"ResourceLimits": {
"type": "object",
"description": "Compute resource constraints (Kubernetes-style)",
"properties": {
"memory_mb": {
"type": "integer",
"minimum": 64,
"description": "Memory limit in megabytes"
},
"cpu_millicores": {
"type": "integer",
"minimum": 100,
"description": "CPU limit in millicores (1000 = 1 CPU)"
},
"gpu_required": {
"type": "boolean",
"default": false,
"description": "Requires GPU acceleration"
},
"gpu_type": {
"type": "string",
"description": "Required GPU type (e.g., nvidia-a100, nvidia-h100)"
}
},
"additionalProperties": false
},
"RuntimeExtension": {
"type": "object",
"description": "External runtime extension (A2A compatible)",
"required": [
"type",
"name"
],
"properties": {
"type": {
"type": "string",
"enum": [
"http",
"grpc",
"mcp",
"websocket",
"kafka",
"pubsub"
],
"description": "Extension protocol type"
},
"name": {
"type": "string",
"description": "Extension name"
},
"endpoint": {
"type": "string",
"description": "Extension endpoint URL"
},
"credentials_ref": {
"type": "string",
"description": "Reference to credentials for authentication"
}
},
"additionalProperties": false
},
"KubernetesConfig": {
"type": "object",
"description": "Kubernetes-specific runtime configuration (KAS-inspired)",
"properties": {
"namespace": {
"type": "string",
"pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$",
"description": "Kubernetes namespace (DNS-1123 subdomain)"
},
"service_account": {
"type": "string",
"pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$",
"description": "Kubernetes service account name"
},
"api_server_url": {
"type": "string",
"format": "uri",
"description": "Kubernetes API server URL (similar to KAS private API URL)"
},
"network_family": {
"type": "string",
"enum": [
"tcp",
"tcp4",
"tcp6"
],
"default": "tcp",
"description": "Network family (KAS pattern: tcp, tcp4, tcp6)"
},
"health_check_endpoint": {
"type": "string",
"format": "uri",
"description": "Health check endpoint URL"
},
"config_map_ref": {
"type": "string",
"description": "Reference to Kubernetes ConfigMap"
},
"secret_ref": {
"type": "string",
"description": "Reference to Kubernetes Secret"
},
"rbac": {
"type": "object",
"properties": {
"role": {
"type": "string",
"description": "Kubernetes Role name"
},
"cluster_role": {
"type": "string",
"description": "Kubernetes ClusterRole name"
},
"role_binding": {
"type": "string",
"description": "Kubernetes RoleBinding name"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
}
}