aevatar-team-builder

Build an Aevatar team and its members

You create a team, fill it with members (each backed by a workflow, script, or gagent), bind their implementations, and set the team's entry member — all via REST. The output is an invocable team. Publishing it as a NyxID service is a separate step (aevatar-service-publisher); scheduling is another (aevatar-scheduler).

Bootstrap

# Drive aevatar THROUGH the NyxID broker: it injects your scope_id claim AND auto-refreshes your
# token. A raw curl to the aevatar backend with ~/.nyxid/access_token resolves NO scope
# (scopeResolved:false) and the stored token expires — it is not a usable path.
# Prerequisite once: the `aevatar` service must be connected — `nyxid service add aevatar`.
# NOTE: the aevatar backend requires `Content-Type: application/json` on writes (POST/PUT) —
# omit it and every write returns HTTP 415 Unsupported Media Type. The helper sets it on
# every call (harmless on bodyless GETs), so the POST/PUT examples below work as written.
aev() { nyxid proxy request aevatar "$@" -H 'Content-Type: application/json'; }   # aev "<path>" [-m POST|PUT|DELETE] [-d '<json>'] [--stream]
scopeId=$(aev "api/studio/context" | jq -r .scopeId)

jq is only for convenience — any JSON reader works (replace | jq -r .scopeId with | python3 -c 'import sys,json;print(json.load(sys.stdin)["scopeId"])'). All calls go through the NyxID broker (nyxid proxy request aevatar), which injects your scope_id claim and auto-refreshes the token. And because the create/bind calls are async and can occasionally return a transient empty body, always read the response status/JSON back — retry once on an empty body — rather than assuming success.

Member implementation kinds are the lowercase strings workflow, script, gagent.

Step 1 — Create the team

teamId=$(aev "api/scopes/$scopeId/teams" -m POST \
  -d '{"displayName":"My Team","description":"what it does"}' | jq -r '.teamId // .id')

CreateStudioTeamRequest: displayName (required), description?, teamId? (omit to let the server mint one). Read the returned id back — do not invent it.

Step 2 — Create the member shell

Create the member as a shell. Do not pass implementationRef here — the concrete implementation (the workflow + its YAML) is attached in Step 3. Passing a forward workflowId that does not exist yet returns HTTP 500.

wfId="my-workflow"   # the id you will bind in Step 3 (pick a stable kebab-case id)
memberId=$(aev "api/scopes/$scopeId/members" -m POST -d "{
  \"displayName\": \"My Workflow Member\",
  \"implementationKind\": \"workflow\",
  \"teamId\": \"$teamId\"
}" | jq -r '.memberId')

CreateStudioMemberRequest: displayName + implementationKind (required, workflow|script|gagent); description?, memberId?, teamId? (attach now, or add later via PATCH). The new member returns at lifecycleStage:"created" and is already assigned a publishedServiceId; its implementationRef stays null until Step 3 fills it in. (Verified: omitting implementationRef returns 201; sending it with a not-yet-bound workflowId returns 500.)

• script / gagent members are created the same way — just set implementationKind to "script" or "gagent". Discover valid gagent kinds with GET /api/scopes/gagent-types. The concrete scriptId / agentKind is supplied in the Step 3 binding, not here.

Step 3 — Bind the member's implementation (attach the YAML)

This is where the real implementation lands. It starts an async binding run.

# Author the YAML first with aevatar-workflow-authoring; pass it inline.
runId=$(aev "api/scopes/$scopeId/members/$memberId/binding" -m PUT -d "{
  \"workflow\": { \"workflowId\": \"$wfId\", \"workflowYamls\": [ $(jq -Rs . < workflow.yaml) ] }
}" | jq -r '.bindingRunId')      # returns {status:"accepted", bindingRunId:"bind-...", ...}

UpdateStudioMemberBindingRequest carries exactly one of:

• workflow: {workflowId, workflowYamls:[<yaml strings>]}
• script: {scriptId, scriptRevision?}
• gAgent: {agentKind, endpoints?}

(jq -Rs . safely JSON-encodes the YAML file as a string.)

Wait for the bind to succeed (it is asynchronous — typically ~1–2 minutes)

Poll the binding run by its id until status is succeeded:

aev "api/scopes/$scopeId/members/$memberId/binding-runs/$runId" \
  | jq '{status, failure}'

Status progresses accepted → admission_pending → admitted → platform_binding_pending → … → succeeded (or failed/rejected). It commonly sits at platform_binding_pending for a minute or two before flipping to succeeded — keep polling (e.g. every 5s, up to ~3 min). On succeeded the response carries result.publishedServiceId + result.revisionId, and the member reaches lifecycleStage:"bind_ready":

aev "api/scopes/$scopeId/members/$memberId" \
  | jq '{stage:.summary.lifecycleStage, svc:.summary.publishedServiceId, ref:.implementationRef}'

Do not report success on the 2xx from the PUT alone — that is only accepted; wait for the run to reach succeeded.

Step 4 — Set the team entry member

The entry member is the team's front door (what callers hit by default).

aev "api/scopes/$scopeId/teams/$teamId/entry-member" -m PUT \
  -d "{\"memberId\":\"$memberId\"}"

Add more members by repeating Steps 2–3 with the same teamId. List the roster: GET /api/scopes/$scopeId/teams/$teamId/members.

Verify

aev "api/scopes/$scopeId/teams/$teamId"          | jq .
aev "api/scopes/$scopeId/teams/$teamId/members"  | jq .

Confirm the team exists, the roster contains your member(s), and the entry member is set.

Edit / clean up

• Rename: PATCH /api/scopes/{scopeId}/teams/{teamId} and PATCH …/members/{memberId}.
• Move a member into the team later: PATCH …/members/{memberId} with {teamId}.
• Archive a team: POST …/teams/{teamId}/archive.
• Re-bind (new YAML/revision): repeat Step 3; each bind is a new revision.

Next

• Publish it as a NyxID-registered service: aevatar-service-publisher.
• Run it on a schedule: aevatar-scheduler.
• Lost? Load aevatar-platform-map for the full panorama.

If you genuinely cannot complete a step server-side, hand the original request back to your caller rather than fabricating — see the fallback skill in this family.