Agents

Agents for your project

Harakumo suggests the agents a kind of app usually needs (a store gets a shopping assistant, order follow-up and a low-stock alert; a booking app a booking assistant and reminders) and creates them in one step: the project's Agents tab, GET/POST /api/projects/:id/agents/suggested, or the AI connector's suggest_agents and create_suggested_agents.

An AI assistant can also design any agent itself with the connector (create_agent, get_agent, update_agent, set_agent_status, delete_agent, list_agent_tools), test it with run_agent and improve it from its steps.

Each agent records what starts it (trigger: manual, chat, schedule or event, with a label in plain words) and what it does (purpose). The project's Agents tab draws every agent as a flow: what starts it, the agent, and the services it uses. Schedule, event and chat starts are recorded and drawn; until they ship, such an agent runs when asked.

Create and run

const { agent } = await hk.agents.create(project.id, {
  name: 'ops', model: 'claude-sonnet-5',
  instructions: 'Report failed deploys and projects close to their plan limits.',
  tools: ['list_projects', 'get_usage', 'list_deployments'],
  maxSteps: 8,
});
const { run } = await hk.agents.run(agent.id, 'What needs attention today?');
// run.status, run.output, run.steps, run.cost_micros, run.model, run.stop_reason

What a run returns

POST /api/agents/:id answers 202 with { run } once the run has finished, and hk.agents.run resolves with it.

See what a run did

Dashboard → Agents → an agent lists its recent runs. Open one to see its input, its output or why it stopped, the model, the tokens and the cost, and every step: the tool it called, the arguments it passed and what came back, with failed tool calls marked. GET /api/agents/:id (hk.agents.get) returns the same for the 20 most recent runs.

Settings

Limits and cost

• Before a run starts, Harakumo sets aside an estimate of a few steps. With no AI credit left, or no room under the monthly spending limit, the run is refused with 402 (the same codes as an AI Gateway call) and never starts; nothing is charged.
• Each step is charged as it happens at the model's price, from included AI credit and then the Balance. A run stops as failed when the money runs out (stop_reason credits) or the monthly spending limit is reached (spend_limit); its output says which, and where on the Billing page to add funds or raise the limit.
• A run's tokens_used and cost_micros are what its steps used and were charged, whether it finished, stopped or failed.
• Runs: 6 a minute per workspace (429 rate_limited past it); 1 at once on hobby, 5 at once on pro, 20 at once on enterprise (429 plan_limit with limit and current). Input up to 32,000 characters.
• A run finishes inside the HTTP request; a run still marked running after 60 minutes is marked failed (stale).
• A paused agent answers 409 until it is resumed.
• Edit an agent with PATCH /api/agents/:id (model, instructions, tools, maxSteps, allowWrites); its run history is kept.
• Billing → Balance breaks this month's AI spend down by model; agent runs are one Unattributed row there for now, and each run shows its own model and cost.

Reference

const { agent } = await hk.agents.create(project.id, { name: 'triage', model: 'auto', tools: ['list_projects'] });
const { run } = await hk.agents.run(agent.id, 'List my projects and which are live.');
console.log(run.status, run.stop_reason, run.cost_usd, run.steps.length);
const { agent: a, runs } = await hk.agents.get(agent.id);   // the 20 most recent runs with their steps
await hk.agents.update(agent.id, { maxSteps: 12 });          // run history is kept
await hk.agents.pause(agent.id);                             // hk.agents.resume(agent.id) to run again

GET    /api/agents/tools?writes=1
POST   /api/projects/:id/agents   { "name", "model", "instructions"?, "tools"?: [], "maxSteps"?, "allowWrites"?, "trigger"?: { "kind", "label" }, "purpose"? }
GET    /api/projects/:id/agents/suggested?appType=store     # the agents this kind of app usually needs
POST   /api/projects/:id/agents/suggested   { "appType", "keys": [] }   # create them
POST   /api/agents/:id            { "input": "…" }      # run; 202 { run } once it has finished, with its steps
GET    /api/agents/:id            # the agent and its recent runs
PATCH  /api/agents/:id            { "model"?, "instructions"?, "tools"?, "maxSteps"?, "allowWrites"? } | { "action": "pause"|"resume" }
DELETE /api/agents/:id