Hire an actor
Hiring is how a customer creates a worker. The console flow is Staff → Staff → Hire (/staff/hire on staff.orkestia.dev). Under the hood it starts governed workflows: draft a config from your description, create the config, attach skills and MCP servers, then register the actor in a unit.
The wizard
- Describe the role in natural language ("triage failed deploys and open tickets", "draft social posts for inbox review"). Staff drafts a name, description, and standing system prompt.
- Pick a model profile from your connected providers.
- Pick an agent-eligible runner group — this is where sessions will launch.
- Pick an org unit (or the org root). Units are trust boundaries, not an HR chart. Start with one unit if you are a single team.
- Attach skills. A skill names the workflows the actor may call. An actor with no workflow-backed skills can reason but not act — every tool call is blocked.
- Attach MCP servers. Every org gets the built-in Orkestia workflow MCP (discover, schema, start, watch, retry). Add your own MCP servers for extra tools. Hire defaults to the built-in server.
- Confirm. Staff creates the config, attaches what you selected, and hires the actor. If a later step fails, retry continues from the last finished step so you do not orphan a config.
You can also start from Configs if you already have a config and only need to bind an actor to it. The inbox checklist only ticks when staff.list-actors returns at least one actor — not when a config exists alone.
After hire
| Action | What it does |
|---|---|
| Invoke / chat | Starts a session on the runner group (validate config → secrets → skills → MCP → memory → launch → watch) |
| Pause / resume | Stops new work without deleting history |
| Archive | Retires the actor; journal and audit remain |
| Inspect | State, inbox, outbox, journal |
Session mechanics: Agents substrate. Day-to-day buttons: Console.
Skills are the guardrail
Tool calls are policy-gated against attached skills. Reach = (skills' workflows) ∩ (role bindings) ∩ (budget). Three independent brakes, all data.
Grant least privilege: a finance actor gets finance/data skills, not Kubernetes. Promoting an actor from propose-only to actuation is a skill + role change, itself an audited workflow.
Built-in workflow MCP
Actors that should use Orkestia (list types, start runs, watch them) need the built-in workflow MCP attached. That is the same catalog an IDE agent uses over MCP, scoped to your org from the actor's identity.
Do not paste a member JWT into the child runtime. If the actor must call Orkestia from outside Staff, mint an agt_ token bound to that actor.
First invoke
- Open the actor.
- Send a bounded task ("list our AWS connections and stop").
- Watch Sessions / Activity. You should see heartbeats, then a terminal state.
- If it never heartbeats, read Troubleshooting — almost always runner eligibility or a missing model profile.