---
name: grix-egg
description: Program-driven hatching: AI only organizes parameters and calls `grix_egg`; the program handles creation, installation, binding, acceptance, and status reporting.
---

# Grix Egg

`grix-egg` follows a "program-first, AI-assists" approach.
AI no longer manually relays create/bind/accept.

## 1. AI Role Boundary

You only do three things:

1. Organize user input into standard parameters
2. Call `grix_egg`
3. Report results / request supplementary parameters based on the returned JSON

Do not manually execute these actions:

1. Remote agent creation
2. Local bind
3. Gateway operations
4. Test group acceptance

## 2. Standard Call Entry

Prefer passing the raw install card:

```json
{ "installContext": "<raw json>" }
```

If there is no install card, pass structured parameters:

1. `route`: `create_new` | `existing` | `existing_claude`
2. `agentName`
3. `agentIdSlug` or `localAgentName`
4. `downloadUrl`
5. `existingCredentials` (required for `existing`)
6. Optional: `packageHash`, `soulContent`, `soulFile`, `categoryId`, `categoryName`, `isMain`, `expectedSubstring`, `statusTarget`, `resume`, `installId`

## 3. Route Behavior

1. `create_new`: program automatically completes creation, installation, binding, acceptance, and status reporting
2. `existing`: program automatically completes existing credential installation and acceptance
3. `existing_claude`: program returns `unsupported_route`, handled by a standalone Claude installer

## 4. Acceptance Rules

Program has fixed acceptance logic:

1. Test group members must include: main agent, trigger user, target agent
2. Probe uses `@<target_agent_id>` mention
3. Only the first non-empty reply after the probe from the target agent is accepted
4. `expectedSubstring` is only an optional enhancement condition

## 5. Result Reporting

When `ok=true`:

1. Report `install_id`, `route`, target agent, acceptance result
2. If `acceptance.reply_content` and `testGroup` are present, include them for the user
3. If `interaction_status=degraded`, explain that the main flow succeeded but status reporting partially failed

When `ok=false`:

1. Use `reason` and `suggestion` directly to explain the failure
2. Only supplement external inputs that the program explicitly identifies as missing
3. Use `resume=true` + `installId` when continuation is needed

## 6. Prohibited Actions

1. Do not use `curl`/`fetch`/`axios` to directly connect to `/v1/agent-api`
2. Do not manually modify `openclaw.json`
3. Remote actions must only go through typed tools: `grix_admin`, `grix_group`, `grix_query`
4. Do not claim installation success before acceptance is complete

## References

1. [references/api-contract.md](references/api-contract.md)