The agent lifecycle
An agent defines the reusable job. A run is one execution of that definition. Agent creation and execution are asynchronous: wait for the build to finish before running, then wait for the run before consuming its result.
Start an agent build with REST
create-agent.shbash
curl "$AGENTRUN_API_BASE/agents/build" \
-H "Authorization: Bearer $AGENTRUN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"domain":"Invoice extraction","context":"Extract invoice numbers, totals, and due dates. Return JSON and flag missing fields.","depth":"standard"}'This starts a build; it does not return a ready-to-run agent immediately. The SDK quickstart handles polling and activation. The build request takes domain, optional context (up to 5,000 characters), and depth (standard or deep); the SDK sends its prompt argument as domain. Confirm field names against your deployment's live schema.
Run an existing agent
run-agent.shbash
curl "$AGENTRUN_API_BASE/runs" \
-H "Authorization: Bearer $AGENTRUN_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"expert_id\":\"$AGENT_ID\",\"question\":\"Invoice INV-1042. Total USD 250. Due 2026-10-15.\"}"Use the active agent ID from the completed build; the run request names it expert_id and takes the input as question. The response starts a run; poll GET $AGENTRUN_API_BASE/runs/{id} or use the SDK wait method to retrieve its terminal result. Keep the same agent ID when the next input arrives.
Existing Grep v2 integrations
The Grep v2 research endpoints remain documented for existing integrations. POST /api/v2/research and POST /api/v2/runs accept the same request body on production; confirm against your deployment's live schema before relying on either path.