Emil Shanaty
fb3b4935d9
- AGENTS.md: build instructions for AI coding agents - docs/: AICC core spec copy, JSON schema, testbed design notes - scripts/: setup.sh, BUILDLOG.md - README.md: overview and reading order
370 lines
13 KiB
JSON
370 lines
13 KiB
JSON
{
|
|
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
"$id": "https://aicc.dev/schemas/0.1/aicc.schema.json",
|
|
"title": "AICC Protocol",
|
|
"description": "Schema for the AI-Controlled Character Protocol (AICC) version 0.1. Defines the message envelope, session manifest, tool definitions, and all message types.",
|
|
"type": "object",
|
|
"oneOf": [
|
|
{ "$ref": "#/$defs/sessionInit" },
|
|
{ "$ref": "#/$defs/sessionResume" },
|
|
{ "$ref": "#/$defs/sessionClose" },
|
|
{ "$ref": "#/$defs/manifestRequest" },
|
|
{ "$ref": "#/$defs/toolCall" },
|
|
{ "$ref": "#/$defs/toolResult" },
|
|
{ "$ref": "#/$defs/event" },
|
|
{ "$ref": "#/$defs/errorMessage" },
|
|
{ "$ref": "#/$defs/heartbeat" }
|
|
],
|
|
"$defs": {
|
|
"protocolString": {
|
|
"type": "string",
|
|
"const": "aicc/0.1",
|
|
"description": "Protocol version string. Must be exactly 'aicc/0.1' for this version."
|
|
},
|
|
"uuid": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
|
|
},
|
|
"sessionId": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "UUID assigned by the bridge at handshake."
|
|
},
|
|
"messageId": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "UUID for this message. Used for correlation."
|
|
},
|
|
"callId": {
|
|
"type": "string",
|
|
"minLength": 1,
|
|
"description": "Agent-assigned id. Echoed in tool_result for correlation."
|
|
},
|
|
"envelope": {
|
|
"type": "object",
|
|
"required": ["protocol", "type", "session_id", "message_id"],
|
|
"properties": {
|
|
"protocol": { "$ref": "#/$defs/protocolString" },
|
|
"type": {
|
|
"type": "string",
|
|
"enum": [
|
|
"session_init",
|
|
"session_resume",
|
|
"session_close",
|
|
"manifest_request",
|
|
"tool_call",
|
|
"tool_result",
|
|
"event",
|
|
"error",
|
|
"heartbeat"
|
|
]
|
|
},
|
|
"session_id": { "$ref": "#/$defs/sessionId" },
|
|
"message_id": { "$ref": "#/$defs/messageId" }
|
|
},
|
|
"additionalProperties": false
|
|
},
|
|
"tickMode": {
|
|
"type": "string",
|
|
"enum": ["fixed", "event", "hybrid"],
|
|
"description": "How the environment advances over time. fixed: regular intervals. event: only on tool calls or triggers. hybrid: fixed physics but agents may request immediate evaluation."
|
|
},
|
|
"worldKind": {
|
|
"type": "string",
|
|
"enum": ["2d", "3d", "text", "abstract"],
|
|
"description": "Visual / spatial style of the world. Does not constrain tool implementations."
|
|
},
|
|
"modelClass": {
|
|
"type": "string",
|
|
"enum": ["edge_small", "edge_medium", "cloud_medium", "cloud_large"],
|
|
"description": "Declared class of the agent's reasoning model. Advisory only — used by the bridge to tune tick rate and sensor cadence."
|
|
},
|
|
"toolClass": {
|
|
"type": "string",
|
|
"enum": ["sensor", "actuator", "generator"]
|
|
},
|
|
"errorCode": {
|
|
"type": "string",
|
|
"enum": [
|
|
"protocol_mismatch",
|
|
"session_expired",
|
|
"tool_unknown",
|
|
"tool_unavailable",
|
|
"invalid_input",
|
|
"execution_failed",
|
|
"timeout",
|
|
"internal_error"
|
|
]
|
|
},
|
|
"error": {
|
|
"type": "object",
|
|
"required": ["code", "message", "retryable"],
|
|
"properties": {
|
|
"code": { "$ref": "#/$defs/errorCode" },
|
|
"message": { "type": "string", "minLength": 1 },
|
|
"retryable": { "type": "boolean" }
|
|
},
|
|
"additionalProperties": false
|
|
},
|
|
"meta": {
|
|
"type": "object",
|
|
"description": "Optional environment-supplied metadata for any message that reports state.",
|
|
"properties": {
|
|
"tick": { "type": "integer", "minimum": 0 },
|
|
"latency_ms": { "type": "integer", "minimum": 0 },
|
|
"source": { "type": "string" }
|
|
},
|
|
"additionalProperties": true
|
|
},
|
|
"tool": {
|
|
"type": "object",
|
|
"required": ["id", "class", "description", "input_schema", "output_schema"],
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"pattern": "^[a-z][a-z0-9_]*$",
|
|
"description": "Lowercase snake_case identifier, unique within the session."
|
|
},
|
|
"class": { "$ref": "#/$defs/toolClass" },
|
|
"description": {
|
|
"type": "string",
|
|
"minLength": 1,
|
|
"description": "Human-readable description surfaced to the agent. Should make the tool's purpose and any non-obvious side effects clear."
|
|
},
|
|
"input_schema": {
|
|
"type": "object",
|
|
"description": "JSON Schema describing the tool's input object."
|
|
},
|
|
"output_schema": {
|
|
"type": "object",
|
|
"description": "JSON Schema describing the tool's output object."
|
|
},
|
|
"limits": {
|
|
"type": "object",
|
|
"description": "Rate limits and quotas. Enforced by the bridge.",
|
|
"properties": {
|
|
"calls_per_minute": { "type": "integer", "minimum": 1 },
|
|
"calls_per_session": { "type": "integer", "minimum": 1 }
|
|
},
|
|
"additionalProperties": false
|
|
},
|
|
"requires_capability": {
|
|
"type": "string",
|
|
"description": "Capability the agent must hold to invoke this tool."
|
|
},
|
|
"strict_input": {
|
|
"type": "boolean",
|
|
"default": false,
|
|
"description": "If true, the bridge rejects tool calls with input fields not declared in input_schema. Default false (extra fields ignored)."
|
|
}
|
|
},
|
|
"additionalProperties": false
|
|
},
|
|
"capabilities": {
|
|
"type": "object",
|
|
"required": ["sensors", "actuators", "generators"],
|
|
"properties": {
|
|
"sensors": {
|
|
"type": "array",
|
|
"items": { "type": "string" },
|
|
"description": "Reserved capability names enabled for sensors."
|
|
},
|
|
"actuators": {
|
|
"type": "array",
|
|
"items": { "type": "string" },
|
|
"description": "Reserved capability names enabled for actuators."
|
|
},
|
|
"generators": {
|
|
"type": "array",
|
|
"items": { "type": "string" },
|
|
"description": "Reserved capability names enabled for generators."
|
|
}
|
|
},
|
|
"additionalProperties": false
|
|
},
|
|
"modelDecl": {
|
|
"type": "object",
|
|
"required": ["class"],
|
|
"properties": {
|
|
"class": { "$ref": "#/$defs/modelClass" },
|
|
"expected_first_token_ms": {
|
|
"type": "integer",
|
|
"minimum": 0,
|
|
"description": "Advisory budget for time-to-first-token."
|
|
},
|
|
"expected_full_response_ms": {
|
|
"type": "integer",
|
|
"minimum": 0,
|
|
"description": "Advisory budget for a full tool-call decision cycle."
|
|
}
|
|
},
|
|
"additionalProperties": false
|
|
},
|
|
"sessionInit": {
|
|
"type": "object",
|
|
"required": ["protocol", "type", "session_id", "message_id", "tick_rate_hz", "tick_mode", "world", "capabilities", "tools", "agent_model"],
|
|
"properties": {
|
|
"protocol": { "$ref": "#/$defs/protocolString" },
|
|
"type": { "const": "session_init" },
|
|
"session_id": { "$ref": "#/$defs/sessionId" },
|
|
"message_id": { "$ref": "#/$defs/messageId" },
|
|
"tick_rate_hz": {
|
|
"type": "number",
|
|
"exclusiveMinimum": 0,
|
|
"description": "Environment's nominal tick rate in Hertz. Informational; bridges may exceed or undershoot."
|
|
},
|
|
"tick_mode": { "$ref": "#/$defs/tickMode" },
|
|
"world": {
|
|
"type": "object",
|
|
"required": ["name", "kind"],
|
|
"properties": {
|
|
"name": { "type": "string", "minLength": 1 },
|
|
"kind": { "$ref": "#/$defs/worldKind" }
|
|
},
|
|
"additionalProperties": false
|
|
},
|
|
"agent_model": { "$ref": "#/$defs/modelDecl" },
|
|
"capabilities": { "$ref": "#/$defs/capabilities" },
|
|
"tools": {
|
|
"type": "array",
|
|
"items": { "$ref": "#/$defs/tool" },
|
|
"minItems": 0,
|
|
"description": "Full catalog of tools available in this session."
|
|
},
|
|
"event_subscriptions": {
|
|
"type": "array",
|
|
"items": { "type": "string" },
|
|
"description": "Optional. Topics the agent is subscribed to. Empty or omitted means only events emitted as direct responses are sent."
|
|
}
|
|
},
|
|
"additionalProperties": false
|
|
},
|
|
"sessionResume": {
|
|
"type": "object",
|
|
"required": ["protocol", "type", "session_id", "message_id"],
|
|
"properties": {
|
|
"protocol": { "$ref": "#/$defs/protocolString" },
|
|
"type": { "const": "session_resume" },
|
|
"session_id": { "$ref": "#/$defs/sessionId" },
|
|
"message_id": { "$ref": "#/$defs/messageId" }
|
|
},
|
|
"additionalProperties": false
|
|
},
|
|
"sessionClose": {
|
|
"type": "object",
|
|
"required": ["protocol", "type", "session_id", "message_id"],
|
|
"properties": {
|
|
"protocol": { "$ref": "#/$defs/protocolString" },
|
|
"type": { "const": "session_close" },
|
|
"session_id": { "$ref": "#/$defs/sessionId" },
|
|
"message_id": { "$ref": "#/$defs/messageId" },
|
|
"reason": { "type": "string" }
|
|
},
|
|
"additionalProperties": false
|
|
},
|
|
"manifestRequest": {
|
|
"type": "object",
|
|
"required": ["protocol", "type", "session_id", "message_id"],
|
|
"properties": {
|
|
"protocol": { "$ref": "#/$defs/protocolString" },
|
|
"type": { "const": "manifest_request" },
|
|
"session_id": { "$ref": "#/$defs/sessionId" },
|
|
"message_id": { "$ref": "#/$defs/messageId" }
|
|
},
|
|
"additionalProperties": false
|
|
},
|
|
"toolCall": {
|
|
"type": "object",
|
|
"required": ["protocol", "type", "session_id", "message_id", "call_id", "tool", "input"],
|
|
"properties": {
|
|
"protocol": { "$ref": "#/$defs/protocolString" },
|
|
"type": { "const": "tool_call" },
|
|
"session_id": { "$ref": "#/$defs/sessionId" },
|
|
"message_id": { "$ref": "#/$defs/messageId" },
|
|
"call_id": { "$ref": "#/$defs/callId" },
|
|
"tool": {
|
|
"type": "string",
|
|
"pattern": "^[a-z][a-z0-9_]*$",
|
|
"description": "Tool id from the manifest."
|
|
},
|
|
"input": {
|
|
"type": "object",
|
|
"description": "Must validate against the tool's input_schema."
|
|
}
|
|
},
|
|
"additionalProperties": false
|
|
},
|
|
"toolResult": {
|
|
"type": "object",
|
|
"required": ["protocol", "type", "session_id", "message_id", "call_id", "ok"],
|
|
"properties": {
|
|
"protocol": { "$ref": "#/$defs/protocolString" },
|
|
"type": { "const": "tool_result" },
|
|
"session_id": { "$ref": "#/$defs/sessionId" },
|
|
"message_id": { "$ref": "#/$defs/messageId" },
|
|
"call_id": { "$ref": "#/$defs/callId" },
|
|
"ok": { "type": "boolean" },
|
|
"output": {
|
|
"type": "object",
|
|
"description": "Tool output. Must conform to the tool's output_schema when ok is true. Absent or null when ok is false."
|
|
},
|
|
"error": {
|
|
"$ref": "#/$defs/error",
|
|
"description": "Present only when ok is false."
|
|
},
|
|
"meta": { "$ref": "#/$defs/meta" }
|
|
},
|
|
"additionalProperties": false
|
|
},
|
|
"event": {
|
|
"type": "object",
|
|
"required": ["protocol", "type", "session_id", "message_id", "topic", "payload"],
|
|
"properties": {
|
|
"protocol": { "$ref": "#/$defs/protocolString" },
|
|
"type": { "const": "event" },
|
|
"session_id": { "$ref": "#/$defs/sessionId" },
|
|
"message_id": { "$ref": "#/$defs/messageId" },
|
|
"topic": {
|
|
"type": "string",
|
|
"enum": ["tick", "collision", "audio", "state_change", "agent_message"],
|
|
"description": "Event topic. Reserved topics are listed; bridges may define additional topics but agents may not rely on them."
|
|
},
|
|
"payload": {
|
|
"type": "object",
|
|
"description": "Topic-specific payload. Bridges MAY extend with additional fields; agents SHOULD ignore unknown fields."
|
|
},
|
|
"meta": { "$ref": "#/$defs/meta" }
|
|
},
|
|
"additionalProperties": false
|
|
},
|
|
"errorMessage": {
|
|
"type": "object",
|
|
"required": ["protocol", "type", "session_id", "message_id", "error"],
|
|
"properties": {
|
|
"protocol": { "$ref": "#/$defs/protocolString" },
|
|
"type": { "const": "error" },
|
|
"session_id": { "$ref": "#/$defs/sessionId" },
|
|
"message_id": { "$ref": "#/$defs/messageId" },
|
|
"error": { "$ref": "#/$defs/error" }
|
|
},
|
|
"additionalProperties": false
|
|
},
|
|
"heartbeat": {
|
|
"type": "object",
|
|
"required": ["protocol", "type", "session_id", "message_id"],
|
|
"properties": {
|
|
"protocol": { "$ref": "#/$defs/protocolString" },
|
|
"type": { "const": "heartbeat" },
|
|
"session_id": { "$ref": "#/$defs/sessionId" },
|
|
"message_id": { "$ref": "#/$defs/messageId" },
|
|
"manifest_update": {
|
|
"type": "object",
|
|
"description": "If present, replaces the current manifest (e.g. capability changes). Same shape as session_init minus session_id and message_id."
|
|
}
|
|
},
|
|
"additionalProperties": false
|
|
}
|
|
}
|
|
}
|