Client configuration
python
import os
from agentrun import AgentRun, Agent, AgentRunError
client = AgentRun(
api_key=os.environ["AGENTRUN_API_KEY"],
base_url="https://api.grep.ai/api/v2",
timeout=30,
)Methods are synchronous and return response dictionaries, except artifact downloads return bytes. Agent extends AgentRun and inherits all management methods below. All durations are seconds; keyword-only arguments are shown by name.
Agent execution
Use Agent(api_key=..., agent_id=...) for an existing agent or Agent(api_key=..., build_id=...) to resume a build. Both accept base_url and timeout. client.agent(agent_id) inherits the client's settings. client.create_agent(**definition) saves a manual definition and returns a dictionary; pass its id to client.agent(). Definitions accept name, instructions, skills, tools, run_mode, campaign_plan, and input_form.
| Method | Behavior |
|---|---|
| Agent.create(api_key=..., prompt=..., context=None, depth="standard", base_url=..., timeout=30) | Start a generated build and return an Agent. Depth is standard or deep. |
| agent.wait_until_ready(timeout=1200, interval=2) | Await generation and activation; returns the same agent. |
| agent.run(input, **options) | Submit a run and return its ID/status. |
| agent.batch(questions, **options) | Submit a batch and return its ID/status. |
| agent.loop(questions, cadence, **options) | Start a recurring batch; returns id, first_batch_id, status. |
| agent.campaign(inputs, records=None, idempotency_key=None) | Execute the configured campaign template immediately. |
Save agent.id and agent.build_id. Run options: effort (low, medium, high, build), max_cost_usd, response_language, output_schema, idempotency_key. Batch and loop options: name, effort, response_language, max_concurrent, max_credits, output_schema, form_inputs, idempotency_key. form_inputs aligns positionally with questions. CSV input is {"csv": csv_text, "input_column": "question"}.
Agents and builds
| Method | Result / behavior |
|---|---|
| agent(agent_id) | Return an Agent wrapper. TypeScript accepts a definition or {id}; Python accepts an existing ID. |
| list_agents() | Return agents and count. |
| get_build(build_id, timeout=None) | Read a saved build. |
| get_agent(agent_id) | Read an agent definition. |
| update_agent(agent_id, **changes) | Update name, instructions, skills, tools, or campaign configuration. |
| delete_agent(agent_id) | Delete an agent. |
Skills, integrations, and usage
| Method | Result / behavior |
|---|---|
| list_skills(**filters) | Search skills by query, category, and limit. |
| create_skill(name=..., description=..., content=...) | Create or update your own named Markdown skill. |
| get_skill(name) | Read skill content. |
| list_integrations(**filters) | Search tools; supports query, category, limit, and server. |
| get_usage() | Read account usage; requires billing:read. |
Runs
| Method | Result / behavior |
|---|---|
| list_runs(cursor=None, limit=None) | Read a page of items and next_cursor. |
| get_run(run_id, timeout=None) | Read status, report, and structured output. |
| cancel_run(run_id) | Request cancellation. |
| wait(run_id, timeout=1200, interval=2) | Wait for completed, failed, cancelled, or blocked. |
Batches
| Method | Result / behavior |
|---|---|
| list_batches(cursor=None, limit=None, status=None) | Read a page of batches. |
| get_batch(batch_id, include_rows=None) | Read a batch, optionally including rows. |
| get_batch_results(batch_id, row_status=None) | Return results; filter queued, running, completed, or failed. |
| cancel_batch(batch_id) | Stop new dispatches; running rows may finish. |
| retry_batch(batch_id, row_number=None) | Explicitly retry a row or eligible failed work; may consume credits. |
| wait_batch(batch_id, timeout=1200, interval=2) | Return on terminal state or a pause requiring attention. |
Loops
| Method | Result / behavior |
|---|---|
| get_loop(loop_id) | Return loop configuration and runs history. |
| update_loop(loop_id, **changes) | Change name, frequency, schedule_config, or timezone. Inputs remain frozen. |
| pause_loop(loop_id) | Stop future occurrences. |
| resume_loop(loop_id) | Resume future occurrences. |
| run_loop_now(loop_id) | Start an extra batch without shifting cadence; returns batch_id and run_number. |
| delete_loop(loop_id, cancel_active=False) | Delete the loop; optionally cancel pending work in the latest batch. |
Campaigns
| Method | Result / behavior |
|---|---|
| create_campaign(plan, records=None, idempotency_key=None) | Create a draft requiring review and approval. |
| list_campaigns(cursor=None, limit=None) | Read a page of campaigns. |
| get_campaign(campaign_id) | Read plan, stages, review digest, and deliverables. |
| get_campaign_portfolio(campaign_id, stage_key, **filters) | Read stage coverage, items, and next_cursor; filters cursor, limit, status, search. |
| approve_campaign(campaign_id, review_digest) | Approve exactly the plan that was reviewed. Stale digest returns conflict. |
| cancel_campaign(campaign_id) | Cancel pending work. |
| wait_campaign(campaign_id, timeout=1200, interval=2) | Return on completed, failed, cancelled, needs_attention, or draft awaiting review. |
| download_campaign_artifact(campaign_id, deliverable_key) | Download original artifact bytes: Blob in TypeScript, bytes in Python. |
Polling and errors
The per-request timeout defaults to 30 seconds. All wait methods default to timeout=1200 and interval=2. Polling bounds requests by the remaining deadline. AgentRunError.status exposes HTTP status; TimeoutError means the local deadline expired; ValueError means invalid input. Standard-library network errors may propagate.
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.