Skip to content
NewAgents for every project: your AI designs them, you watch them workAgents for every project
Docs · AI

Agents

A model with standing instructions and a chosen set of Harakumo tools, run when asked, on a schedule, on a signed event from your app or from a visitor's chat. Tools are real platform actions on the agent's project, and every step is logged and metered.

View as Markdown
All topics
On this page

An agent calls tools in a loop until the task is done or it reaches its step limit. The tools are Harakumo's own actions on the agent's project (read the project and its deployments, search vectors … and, when allowed, query a database, deploy, create or delete). They run with an API key made for the run and revoked afterwards. That key is limited to the agent's project and is never more than whoever started the run: it is read-only unless the agent may make changes and the starter could make them too, and a key limited to another project cannot start the run.

So a run never has a tool that covers the whole workspace (projects, usage, domains, repos, the Balance), or one its key can never use, such as list_env_vars on an agent without writes (environment variables need the developer role). When you build an agent they are not offered as usable (they are shown greyed out with the reason, or left out), and saving an agent with one is refused with the reason. Sending email is kept: it sends as the agent's project.

Agents are for acting on your own Harakumo resources today. A run starts when you ask for one (the API, the SDK, the dashboard or an AI assistant), now or in the background; on a schedule; when your app sends the agent a signed event; or when a visitor writes to it from your site (see How an agent starts). Custom HTTP tools, memory attached to an agent and a callback when a background run ends are not available yet.

inputagenttoolsrun logstep 1 · modelstep 2 · tool call✓ completedstanding instructions, chosen tools, every step logged

In plain words

An AI helper that does a job step by step with the tools you allow, such as reading your data or sending an email. You see every step and what it cost.

For example: Each time you run it, an agent reads the new support messages and drafts replies for you to check.

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. A schedule, event or chat start runs the agent once it is set up (below); until then, the flow says so and the agent runs when asked.

How an agent starts

StartSet it upWhen it runs
When askedPOST /api/agents/:id { input }, the SDK's hk.agents.run, the dashboard or the connector's run_agent.At once; the answer carries the finished run.
In the backgroundPOST /api/agents/:id { input, background: true } (run_agent with background).Answers 202 with the queued run at once; the run starts within about ten minutes, as whoever asked, and shows among the agent's runs once it has. Up to 20 can wait per agent.
On a schedulePATCH /api/agents/:id { schedule: "0 9 * * *" } (five cron fields in UTC, or @hourly, @daily, @weekly, @monthly), or { schedule: { cron, input } }; null removes it. Also on the agent's page and in update_agent.At the first look at or after each time; the platform looks every ten minutes, so a run can start up to ten minutes late, and a schedule that asks for runs closer together than that is refused. schedule on the agent shows the next run and what the last one did.
On an app eventPATCH /api/agents/:id { events: true } answers the signing secret once (events: "rotate" gives a new one, false turns events off). Your server POSTs JSON (16 KB at most) to /api/agents/:id/events, signed as payment webhooks are: Harakumo-Signature: t=<seconds>,v1=<HMAC-SHA256 of "<t>.<raw body>">, with Harakumo-Event naming the event and Harakumo-Delivery its id.The endpoint answers 202 at once; a run starts within about ten minutes. A second delivery of the same id is not a second run. 30 events a minute and 100 waiting per agent.
From a visitor's chatPATCH /api/agents/:id { chat: true } answers a publishable chat id (hkchat_…) and its URL; { chat: { allowedOrigins, dailyLimit } } changes them. Your page POSTs { message, history? } to /api/agents/chat/<chatId> from the project's own addresses or an origin you allow.At once, one run per message, answered in the same request with { reply, run_id }. The run is read-only and has only the project's data tools (its vector collections), and 60 seconds. 10 messages a minute per visitor's address, and a daily limit (200 unless you set another).

An agent starts on its own one way at a time: a schedule, app events or visitor chat. A scheduled, event or background run uses a key cut from the access of whoever set it up, as it stands when the run starts, the plan's limit on runs at once and the same credit checks as any run, and has 5 minutes to finish (stop_reason time_limit past it). When one could not start, the reason is kept on its schedule, events or chat (last_error) for you to read.

Create and run

SDK
const { agent } = await hk.agents.create(project.id, {
  name: 'ops', model: 'claude-sonnet-5',
  instructions: 'Report failed deploys of this project and what their logs say went wrong.',
  tools: ['get_project', 'list_deployments', 'get_deployment'],
  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. With background: true it answers 202 with the queued run instead, and GET /api/agents/:id lists the run once it has started.

FieldMeaning
statuscompleted or failed (running while it is still going).
stop_reasonEmpty when it completed. step_limit: it reached maxSteps without finishing. credits: the AI credit ran out. spend_limit: the monthly spending limit was reached. error: the model or the run failed. vendor: the AI service was unavailable on Harakumo's side (our fault, not yours). time_limit: a scheduled, event or background run reached its 5 minutes, or a visitor's chat run its 60 seconds. stale: the process running it stopped.
outputThe answer or, for a run that stopped, why it stopped and what to do.
stepsEvery step in order: step, kind (tool or text), tool_name, arguments, result (its first 4,000 characters) and ok.
tokens_used, cost_micros, cost_usdWhat its steps used and were charged, whether it finished, stopped or failed.
model, duration_msThe model that ran it, and how long it took.

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

FieldMeaning
modelA tool-capable model (Claude, GPT, Grok, Kimi) or auto (runs on claude-sonnet-5). On Hobby, vendor models need the workspace owner's verified email.
toolsTool names from GET /api/agents/tools (add ?writes=1 to see the ones that change things); a name that is not a tool is refused with 400. Left empty, the agent gets every tool it is allowed. A run gets only the tools its key, limited to the agent's project, can use, so the listing, list_agent_tools and the dashboard's New Agent form offer only those: a tool that covers the whole workspace, or that the run's key could never use (list_env_vars without writes), is left out or marked available: false with a reason, and saving an agent with one is refused with 400 and that reason. With ?writes=1, the tools only an agent with allowWrites can use (everything that changes something, and list_env_vars) are marked needsWrites: true with a writesReason. Tools that manage API keys, switch workspace, run agents or need an admin (members, the audit log, the Balance, service settings) are never given to an agent.
allowWritesfalse by default: the run's key is read-only, so only read tools. true lets the agent use tools that change things in its own project: deploy files, create, change and delete the project's resources, run SQL, set environment variables and send mail. Turn it on deliberately.
maxSteps1–24, default 8. A run that hits it stops as failed with stop_reason step_limit.
instructionsUp to 16,000 characters.

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 (on a paid plan, the Balance of the workspace that pays for the plan, for every workspace it covers, under that workspace's spending limit; on Hobby, the workspace's own). 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, 10 at once on team, 20 at once on scale (429 plan_limit with limit and current). Input up to 32,000 characters.
  • A run asked for without background finishes inside the HTTP request; scheduled, event and background runs have 5 minutes, and a visitor's chat run 60 seconds. A run still marked running after 60 minutes is marked failed (stale).
  • A paused agent answers 409 until it is resumed, and its schedule, events and chat start nothing meanwhile.
  • Edit an agent with PATCH /api/agents/:id (model, instructions, tools, maxSteps, allowWrites, schedule, events, chat); its run history is kept.
  • Billing → Balance breaks this month's AI spend down by model, agent runs included: each step is recorded under the model that ran it. Charges recorded before that, without a model, are one Unattributed row; each run also shows its own model and cost.

Reference

SDK
const { agent } = await hk.agents.create(project.id, { name: 'triage', model: 'auto', tools: ['list_deployments'] });
const { run } = await hk.agents.run(agent.id, 'Is this project live, and when was it last deployed?');
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