Create and run your first agent

1. Set up your SDK and credentials

install.shbash

npm install @parcha/agentrun
# Or, for Python:
python -m pip install parcha-agentrun

The Python distribution is parcha-agentrun; the module you import is agentrun. Keep AGENTRUN_API_KEY in your server-side environment. Set AGENTRUN_API_BASE to your deployment's API base URL; for production that is https://api.grep.ai/api/v2, which is also the SDK default when no base URL is passed. The SDK appends /agents and /runs to that URL. Use credentials for that same deployment.

2. Create and run with TypeScript

create-agent.tstypescript

import { Agent } from '@parcha/agentrun';

const agent = await Agent.create({
  apiKey: process.env.AGENTRUN_API_KEY!,
  baseURL: process.env.AGENTRUN_API_BASE!,
  prompt: 'Extract invoice numbers, totals, and due dates. Return JSON and flag missing fields.',
});
await agent.waitUntilReady();
console.log('Save this agent ID:', agent.id);

const run = await agent.run('Invoice INV-1042. Total USD 250. Due 2026-10-15.');
const result = await agent.wait(run.id);
console.log(result);

Agent.create starts an asynchronous build. waitUntilReady waits for completion and activates the resulting agent. Keep the build ID if you need to inspect a failure; a local wait timeout does not cancel the build.

Or use Python

create_agent.pypython

import os
from agentrun import Agent

agent = Agent.create(
    api_key=os.environ['AGENTRUN_API_KEY'],
    base_url=os.environ['AGENTRUN_API_BASE'],
    prompt='Extract invoice numbers, totals, and due dates. Return JSON and flag missing fields.',
)
agent.wait_until_ready(timeout=1200)
print('Save this agent ID:', agent.id)

run = agent.run('Invoice INV-1042. Total USD 250. Due 2026-10-15.')
result = agent.wait(run['id'], timeout=1200)
print(result)

3. Reuse the agent on the next input

Save the agent ID returned after the build. Load that same agent for subsequent requests instead of calling create for each input.

run-existing-agent.tstypescript

import { Agent } from '@parcha/agentrun';

const agent = new Agent({
  apiKey: process.env.AGENTRUN_API_KEY!,
  baseURL: process.env.AGENTRUN_API_BASE!,
  id: process.env.AGENT_ID!,
});
const run = await agent.run('Invoice INV-1043. Total USD 480. Due 2026-11-01.');
console.log(await agent.wait(run.id));

run_existing_agent.pypython

import os
from agentrun import Agent

agent = Agent(
    api_key=os.environ['AGENTRUN_API_KEY'],
    base_url=os.environ['AGENTRUN_API_BASE'],
    agent_id=os.environ['AGENT_ID'],
)
run = agent.run('Invoice INV-1043. Total USD 480. Due 2026-11-01.')
print(agent.wait(run['id']))

4. Build on the same agent

Add reusable skills, run the same agent over a batch of inputs, schedule recurring work with loops, or connect agents in a campaign. Research is one possible job; extraction, classification, reconciliation, and monitoring use the same create/run pattern.