aws-samples / aws-samples/sample-mcp-tool-design-patterns

setup_agents.py generates agent configs that fail to load on Kiro CLI v3

Open Beginner friendly
#14 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.