Agent Registration JSON

The dashboard’s Agents → Register agent drawer supports uploading or pasting a single JSON object to register (or update) an agent in Kyra.

Sample JSON

{
  "agentName": "payments-agent",
  "agentRole": "Handles refunds and payment status inquiries",
  "systemPrompt": "You are the Payments Agent for ACME. You may only use the tools listed. Never move money unless explicitly authorized by policy. Escalate anything ambiguous.",
  "framework": "langchain",
  "tools": [
    {
      "name": "get_payment_status",
      "description": "Fetch the current status of a payment by paymentId.",
      "parametersSchema": {
        "type": "object",
        "properties": {
          "paymentId": { "type": "string", "description": "The payment identifier." }
        },
        "required": ["paymentId"]
      },
      "requestedTier": "T1",
      "explicitTier": null
    },
    {
      "name": "issue_refund",
      "description": "Issue a refund for a completed payment.",
      "parametersSchema": {
        "type": "object",
        "properties": {
          "paymentId": { "type": "string" },
          "amountCents": { "type": "integer", "minimum": 1 },
          "reason": { "type": "string" }
        },
        "required": ["paymentId", "amountCents", "reason"]
      },
      "requestedTier": "T3",
      "explicitTier": "T4"
    }
  ],
  "topology": {
    "delegationWhitelist": {
      "payments-agent": ["acme-risk-agent", "acme-support-agent"]
    },
    "delegationBlacklist": {
      "payments-agent": ["acme-infra-agent"]
    }
  },
  "policies": [
    {
      "policyId": "refunds-require-ticket-v1",
      "description": "Refunds must only be issued when a support ticket is provided and the user is verified.",
      "appliesToTools": ["issue_refund"],
      "condition": "params.supportTicketId != null AND params.userVerified == true",
      "action": "ESCALATE",
      "tier": "T0"
    },
    {
      "policyId": "never-refund-over-limit-v1",
      "description": "Never issue a refund over $500 without human approval.",
      "appliesToTools": ["issue_refund"],
      "condition": "params.amountCents > 50000",
      "action": "BLOCK",
      "tier": "T0"
    }
  ]
}

Field meanings (focused on topology, tools, policies)

Topology (topology)

This tells Kyra which agents are allowed to hand work off to which other agents (delegation).

• delegationWhitelist: Allowed delegation list.

  • Shape: { "<fromAgentId>": ["<toAgentId>", "..."] }
  • Meaning: If <fromAgentId> delegates, it may only delegate to agents in this list (for that key).
  • Typical use: Prevent a sensitive agent from delegating to unknown agents even if they exist in your org.

• delegationBlacklist: Forbidden delegation list.

  • Shape: { "<fromAgentId>": ["<toAgentId>", "..."] }
  • Meaning: Even if delegation is generally allowed, <fromAgentId> must never delegate to agents listed here.
  • Typical use: Block delegating to agents that can take high-impact actions (infra, prod deploy, payments), or to agents outside a compliance boundary.

Notes:

• If you omit topology, Kyra stores empty maps (no explicit allow/deny lists from registration).
• Keys/values are agent IDs/names you use in your system (Kyra treats them as strings).

Tools (tools[])

This is the tool inventory Kyra uses to understand what your agent can do.

For each tool object:

• name: The tool’s canonical identifier. Use the exact name your runtime uses when the agent calls the tool.
• description: Plain-English statement of what the tool does. Kyra uses this to understand intent and risk.
• parametersSchema: The tool’s input contract (JSON-schema-like object stored as a generic map).
• requestedTier (optional): Tier hint / minimum bar. Treated as a floor during classification (don’t classify it safer than this).
• explicitTier (optional): Hard override. If set, classification is skipped and this tier is used as truth.

Internally tiers are strings like "T0"–"T4".

Explicit policies (policies[])

Developer-declared rules attached at registration time. Kyra stores them as EXPLICIT compliance policies and uses them to gate behavior.

For each policy object:

• policyId: Unique stable identifier (version it like something-v1).
• description: Human-readable rule explanation (also used in violation/escalation messaging).
• appliesToTools: Tool names this policy gates. Empty means not tool-scoped.
• condition: When the rule triggers. Natural language or a structured expression.
  • Best practice: refer to tool-call parameters as params.<field> consistently.
• action: What to do on violation. Expected values like "BLOCK" or "ESCALATE".
• tier: Minimum tier threshold for enforcing this rule (T0–T4).