How withHuman works

At a high level, there are just three concepts you need to understand: agents, approval pipelines and escalation paths. These form the core of withHuman. Everything else supports them.

Here's how they fit together when an agent makes a request.

flowchart TD
    request["Agent sends a request"] --> pipeline["Approval pipelines"]
    pipeline --> automaticApproval["Automatically approved"]
    pipeline --> path["Escalation path"]
    pipeline --> automaticDenial["Automatically denied"]
    path --> review["Human review"]
    review --> approved["Approved"]
    review --> denied["Denied"]

Following a request

1. The agent goes to take an action via a tool call. This is intercepted by an AAP adapter. The AAP adapter then sends withHuman an approval request. The request contains the exact arguments of the tool call and identifies which agent and agent instance is sending it. You don't need to know about AAP to use withHuman, but it's a short read so it might be worth it.

2. The request then goes through the approval pipeline. The approval pipeline is where you define automated rules to decide what to do with a request. These rules can approve the request, deny it, or ask for human review via an escalation path.

3. An escalation path brings in the reviewers. When a request needs human review, its escalation path chooses which people or teams to contact and when. Several pipelines can share the same path, and each team can have its own rules for notifying members.

4. A reviewer makes the decision. They look at the proposed action and approve or deny it. The agent continues waiting while the request is being reviewed.

5. The agent receives the result. Approval lets it proceed with the action. Denial stops that action.

That's it, that's withHuman in a nutshell.

An example: issuing a refund

Imagine a support agent handling refunds. You could set these rules:

• Automatically approve refunds up to $20.
• Ask the support team to review refunds over $20 and up to $500.
• Automatically deny refunds above $500.

An instance of the agent asks to refund $75. The pipelines send the request for human review. Its escalation path contacts a support team member, who checks the refund and approves it. The agent can then issue the refund.

For a $10 refund, the agent gets approval automatically. For a $600 refund, it gets a denial.

Now that's the basics. If you want to go deeper, you can look at each of the core concepts (and a couple more) on their own pages. We go into all the fun details there.