Client configuration
typescript
import { AgentRun, Agent, Skill, AgentAPIError, AgentBuildError } from '@parcha/agentrun';
const client = new AgentRun({
apiKey: process.env.AGENTRUN_API_KEY!,
baseURL: 'https://api.grep.ai/api/v2',
timeoutMs: 30_000,
});Methods return promises. Agent extends AgentRun and inherits the management methods below. Optional request controls use an options object with signal where supported; definition reads, updates, and deletes do not take a signal option. Polling options are timeoutMs, intervalMs, and signal.
Agent execution
Use new Agent({apiKey, id}) for an existing agent, {apiKey, buildId} to resume a build, or {apiKey, name, instructions} for a manual definition. Definitions support skills, tools, run_mode, campaign_plan, and input_form. client.agent(definition) inherits client settings.
| Method | Behavior |
|---|---|
| Agent.create({apiKey, prompt, context?, depth?, baseURL?, timeoutMs?, signal?}) | Start a generated build and return an Agent. Depth is standard or deep. |
| agent.create() | Save a manual definition and return its ID. |
| agent.waitUntilReady(options?) | Await generation and activation; returns the same agent. |
| agent.run(input, options?) | Submit a run and return its ID/status. |
| agent.batch(questionsOrCSV, options?) | Submit a batch and return its ID/status. |
| agent.loop(inputs, cadence, options?) | Start a recurring batch; returns id, first_batch_id, status. |
| agent.campaign(inputs, {records?, idempotencyKey?, signal?}) | Execute the configured campaign template immediately. |
Save agent.id and agent.buildId. Run options: effort (low, medium, high, build), maxCostUsd, responseLanguage, outputSchema, idempotencyKey, signal. Batch and loop options: name, effort, responseLanguage, maxConcurrent, maxCredits, outputSchema, formInputs, idempotencyKey, signal. formInputs aligns positionally with questions. CSV input is {csv: stringOrBlob, inputColumn: 'question'}.
Skill.create({apiKey, name, description, content, baseURL?, timeoutMs?, signal?}) provides standalone skill creation.
Agents and builds
| Method | Result / behavior |
|---|---|
| agent(definition) | Return an Agent wrapper. TypeScript accepts a definition or {id}; Python accepts an existing ID. |
| listAgents() | Return agents and count. |
| getBuild(id) | Read a saved build. |
| getAgent(id) | Read an agent definition. |
| updateAgent(id, definition) | Update name, instructions, skills, tools, or campaign configuration. |
| deleteAgent(id) | Delete an agent. |
Skills, integrations, and usage
| Method | Result / behavior |
|---|---|
| listSkills(filter?) | Search skills by query, category, and limit. |
| createSkill({name, description, content}) | Create or update your own named Markdown skill. |
| getSkill(name) | Read skill content. |
| listIntegrations(filter?) | Search tools; supports query, category, limit, and server. |
| getUsage() | Read account usage; requires billing:read. |
Runs
| Method | Result / behavior |
|---|---|
| listRuns({cursor?, limit?}) | Read a page of items and next_cursor. |
| getRun(id) | Read status, report, and structured output. |
| cancelRun(id) | Request cancellation. |
| wait(id, options?) | Wait for completed, failed, cancelled, or blocked. |
Batches
| Method | Result / behavior |
|---|---|
| listBatches({cursor?, limit?, status?}) | Read a page of batches. |
| getBatch(id, {includeRows?}) | Read a batch, optionally including rows. |
| getBatchResults(id, {rowStatus?}) | Return results; filter queued, running, completed, or failed. |
| cancelBatch(id) | Stop new dispatches; running rows may finish. |
| retryBatch(id, {rowNumber?}) | Explicitly retry a row or eligible failed work; may consume credits. |
| waitBatch(id, options?) | Return on terminal state or a pause requiring attention. |
Loops
| Method | Result / behavior |
|---|---|
| getLoop(id) | Return loop configuration and runs history. |
| updateLoop(id, changes) | Change name, frequency, schedule_config, or timezone. Inputs remain frozen. |
| pauseLoop(id) | Stop future occurrences. |
| resumeLoop(id) | Resume future occurrences. |
| runLoopNow(id) | Start an extra batch without shifting cadence; returns batch_id and run_number. |
| deleteLoop(id, {cancelActive?}) | Delete the loop; optionally cancel pending work in the latest batch. |
Campaigns
| Method | Result / behavior |
|---|---|
| createCampaign(plan, {records?, idempotencyKey?}) | Create a draft requiring review and approval. |
| listCampaigns({cursor?, limit?}) | Read a page of campaigns. |
| getCampaign(id) | Read plan, stages, review digest, and deliverables. |
| getCampaignPortfolio(id, stageKey, filter?) | Read stage coverage, items, and next_cursor; filters cursor, limit, status, search. |
| approveCampaign(id, reviewDigest) | Approve exactly the plan that was reviewed. Stale digest returns conflict. |
| cancelCampaign(id) | Cancel pending work. |
| waitCampaign(id, options?) | Return on completed, failed, cancelled, needs_attention, or draft awaiting review. |
| downloadCampaignArtifact(id, deliverableKey) | Download original artifact bytes: Blob in TypeScript, bytes in Python. |
CSV utility
parseBatchCSV(csv, inputColumn) parses CSV text locally and returns {inputs, rows}. Inputs are the selected column; rows retain all header/value pairs. It rejects duplicate or blank headers, malformed rows, missing input columns, and CSV larger than 1 MB. It makes no API request. Most callers can pass the CSV object directly to agent.batch or agent.loop instead.
Polling and errors
Request timeoutMs defaults to 30,000. wait defaults to 600,000 ms; waitUntilReady, waitBatch, and waitCampaign default to 1,200,000 ms. All default intervals are 1,000 ms. AgentAPIError.status exposes HTTP status; AgentBuildError.build contains a failed build. Abort, timeout, validation, and network failures may be other error types.
No request is retried automatically. Aborting or timing out stops local waiting only. Use explicit cancellation to stop remote work. A terminal result can indicate failure. See errors and recovery, results, and version availability.