aws-samples / aws-samples/sample-mcp-tool-design-patterns
setup_agents.py generates agent configs that fail to load on Kiro CLI v3
- Dominant language
- Python
- Stars
- 5
- Forks
- 1
- PR merge metrics
- No merged PRs in 30d
Description
## Summary
`scripts/setup_agents.py` writes Kiro agent configuration files
(`~/.kiro/agents/v1-passthrough.json` through `v6-agent.json`) using fields that
were valid in Kiro CLI v2 but are rejected by the stricter schema in Kiro CLI v3.
Users who run the script on CLI v3 get six agents that silently fail to load and
do not appear in the agent selector.
## Environment
- Kiro CLI v3 (observed on 2.16.0)
- Script: `scripts/setup_agents.py`
## Symptom
On session start, the profile loader rejects each generated config, e.g.:
```
[ProfileLoader] Failed to parse .../v1-passthrough.json:
Schema validation failed: model: Expected string, received null
```
## Root cause (hints)
Two fields in the agent dict are v2-isms the v3 schema no longer accepts:
1. **`"model": None`** (around line 44). Serializes to JSON `null`. In v3 `model`
is optional but must be a string when the key is present; `null` is rejected.
Fix: omit the key (falls back to the default model) or set a valid model id.
(Confirmed: this is the error reproduced above.)
2. **`"hooks": {}`** (around line 42). In v3 `hooks` must be an array, not an
object. An empty object is expected to fail with
`hooks: Expected array, received object`. Fix: use `"hooks": []`.
(Likely, based on the same error observed for object-form hooks elsewhere;
worth confirming.)
Other emitted fields (`prompt: null`, `tools`, `toolAliases`, `allowedTools`,
`resources`, `toolsSettings`, `includeMcpJson`) load fine in v3.
## Suggested change
Update `setup_agents.py` so generated configs validate under the v3 agent schema.
Both changes remain compatible with v2:
- remove `"model": None` (or set a string)
- change `"hooks": {}` to `"hooks": []`
## References
- Agent config (v3 format): https://kiro.dev/docs/cli/v3/agent-config/
- Agent configuration reference: https://kiro.dev/docs/cli/custom-agents/configuration-reference/
- Upgrading agent configs (`/upgrade-agent`): https://kiro.dev/docs/cli/v3/upgrade-agent/
- Permissions (v3): https://kiro.dev/docs/cli/v3/permissions/
Contributor guide
Research direction
Start in scripts/setup_agents.py around the agent dictionary fields near lines 42–44 and inspect how the six JSON files are generated. Run the script with Kiro CLI v3, verify the generated configs against the v3 schema, and confirm all six agents load and appear in the agent selector.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- cli, tooling
- Issue type
- Bug
- Difficulty
- 1/5
- Estimated time
- Under an hour
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 85/100