Run an agent from your app

Once an agent exists and Who may run it allows your caller, you can run it from your app with the SDK or plain HTTP.

Your servers can run any agent with a secret key. A browser can run an agent only when its Who may run it rule allows the signed-in user (or anyone). See Create an agent.

List the agents you can run

const agents = await pawabase.ai.agents.list();   // [{ name, description }]

agents = pb.ai.agents.list()

You only see agents that are switched on and that you are allowed to run.

Ask it something

const run = await pawabase.ai.agents.run("support", "Where is my order #1042?");
console.log(run.output);    // the answer
console.log(run.status);    // "done"

run = pb.ai.agents.run("support", "Where is my order #1042?")
print(run["output"], run["status"])

The call waits until the agent has finished (or is waiting for approval). A run has:

Field	Meaning
`id`	The run’s id, for looking it up later
`status`	`running`, `waiting` (needs a decision), `done` or `failed`
`output`	The agent’s answer, once it has one
`error`	Why it failed, if it did
`thread_id`	The conversation this run belongs to
`pending`	What it is waiting on, when `status` is `waiting`
`step_count`, `input_tokens`, `output_tokens`, `cost`	What it used

Continue a conversation

Pass the thread of an earlier run to carry on, so the agent remembers what was said.

const first = await pawabase.ai.agents.run("support", "Where is my order #1042?");
const next = await pawabase.ai.agents.run("support", "Can you change the address?", { thread: first.thread_id });

first = pb.ai.agents.run("support", "Where is my order #1042?")
nxt = pb.ai.agents.run("support", "Can you change the address?", thread=first["thread_id"])

A thread remembers its most recent messages. Start a new thread for a new topic.

Stream each step

Show the answer as it is written, and show what the agent is doing:

for await (const event of pawabase.ai.agents.stream("support", "Summarise my open tickets")) {
  if (event.type === "text") process.stdout.write(String(event.text));
  if (event.type === "tool_call") console.log("using", event.name);
  if (event.type === "waiting") console.log("needs approval");
}

for event in pb.ai.agents.stream("support", "Summarise my open tickets"):
    if event["type"] == "text":
        print(event["text"], end="")
    elif event["type"] == "tool_call":
        print("using", event["name"])

The events you can expect:

`type`	Meaning
`text`	A piece of the agent’s words
`tool_call`	The agent started using a tool
`tool_result`	A tool answered
`waiting`	The run stopped to ask a person
`done`	The run finished; carries the final run

A failure ends the stream with an error.

Don’t wait: run in the background

For long jobs, start the run and come back to it:

const started = await pawabase.ai.agents.run("report", "Write this week's summary", { background: true });
const done = await pawabase.ai.agents.wait(started.id);          // polls until it stops running

started = pb.ai.agents.run("report", "Write this week's summary", background=True)
done = pb.ai.agents.wait(started["id"])

You can also look at a run with get(id), or have a flow start when it finishes, so you never poll.

Approve or decline what it asks

When status is waiting, pending lists what the agent wants to do. Show it to the right person, then decide:

if (run.status === "waiting") {
  const ask = run.pending[0];                           // { id, name, arguments, why }
  const after = await pawabase.ai.agents.decide(run.id, { decisions: { [ask.id]: true } });
}
// or approve everything that is waiting
await pawabase.ai.agents.decide(run.id, { approve: true });

if run["status"] == "waiting":
    ask = run["pending"][0]
    after = pb.ai.agents.decide(run["id"], decisions={ask["id"]: True})
# or decline everything that is waiting
pb.ai.agents.decide(run["id"], approve=False)

decisions is a yes or no for each waiting call by its id, and approve answers any you did not name. Approving carries the run on; declining tells the agent no. Only the person who started the run, or someone allowed by the agent’s approval rule, can decide.

Over HTTP

curl "$URL/ai/v1/agents/support/runs" \
  -H "apikey: $PAWABASE_SECRET_KEY" -H "content-type: application/json" \
  -d '{"input":"Where is my order #1042?"}'

Add "stream": true for server-sent events, "background": true to return at once, and "thread": "<id>" to continue a conversation. Read a run with GET /ai/v1/agent-runs/<id> and decide it with POST /ai/v1/agent-runs/<id>/decide.

Errors

Status	Meaning
401	The agent needs a signed-in user
403	The agent’s rule does not let this caller run it
404	No such agent, it is switched off, or no such run
422	The request is missing `input`, or too long

Getting started

Models

Agents

Knowledge bases

Connections and tools

Help

Run an agent from your app

List the agents you can run

Ask it something

Continue a conversation

Stream each step

Don’t wait: run in the background

Approve or decline what it asks

Over HTTP

Errors

​List the agents you can run

​Ask it something

​Continue a conversation

​Stream each step

​Don’t wait: run in the background

​Approve or decline what it asks

​Over HTTP

​Errors

List the agents you can run

Ask it something

Continue a conversation

Stream each step

Don’t wait: run in the background

Approve or decline what it asks

Over HTTP

Errors