Agent definition import guide

Use agent.import_definition when you already have a bounded agent description and want to turn it into a draft ROST agent setup. Import is a starting point, not go-live.

The command creates a draft agent Seat, starts the canonical setup flow, maps the definition into operational answers, and returns agent_setup.get state. It does not sign the Charter, grant tools, store credentials, run a dry run, or approve go-live.

Safety rules

• The file must use "format": "rost.agent_definition" and "version": 1.
• Unknown fields are rejected.
• Credentials, vault refs, API keys, tokens, tenant ids, Seat ids, parent ids, steward ids, and integration ids are rejected.
• Secret-shaped string values are rejected even when they appear in otherwise allowed fields.
• Requested tools are review context only. Grants and credential ingress still happen through setup.
• Placement is server-side. The import file cannot choose a parent Seat or Steward.

Example

{
  "format": "rost.agent_definition",
  "version": 1,
  "agent": {
    "name": "Customer Follow-up Agent",
    "purpose": "Prepare account follow-ups for steward review.",
    "responsibilities": ["Summarize recent customer signals", "Draft follow-up tasks"],
    "success_criteria": ["Stewards receive concise weekly follow-up drafts"],
    "never_do_alone": ["Send external customer messages", "Change billing or credentials"],
    "lane": "cloud",
    "model_tier": "balanced",
    "requested_tools": [
      {
        "capability_id": "google.gmail.read",
        "access": "read",
        "rationale": "Read recent customer context"
      }
    ]
  }
}

After import, continue from the draft Seat page. Review the Charter, choose a Steward, configure tools and connections, sign the manifest, run a dry run, and approve go-live only when the human review is complete.