readme updates

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,28 @@
+<!--
+Please make sure you've read and understood our contributing guidelines;
+https://github.com/humanlayer/humanlayer/blob/master/CONTRIBUTING.md
+
+If this is a bug fix, make sure your description includes "fixes #xxxx", or
+"closes #xxxx"
+
+Please provide the following information:
+
+-->
+
+**- What I did**
+
+**- How I did it**
+
+**- How to verify it**
+
+**- Description for the changelog**
+
+<!--
+Write a short (one line) summary that describes the changes in this
+pull request for inclusion in the changelog:
+-->
+
+<!--
+**- A picture of a cute animal (not mandatory but encouraged)**
+
+-->

README.md

@@ -129,7 +129,7 @@ To better define what is meant by "high stakes", some examples:
 
 <div align="center"><img style="width: 600px" alt="Image showing the levels of function stakes stacked on top of one another" src="./docs/images/function_stakes.png"></div>
 
-The high stakes functions are the ones that are the most valuable and promise the most impact in automating away human workflows. The sooner teams can get Agents reliably and safely calling these tools, the sooner they can reap massive benefits.
+The high stakes functions are the ones that are the most valuable and promise the most impact in automating away human workflows. But they are also the ones where "90% accuracy" is not acceptable. Reliability is further impacted by today's LLMs' tendency to hallucinate or craft low-quality text that is clearly AI generated. The sooner teams can get Agents reliably and safely calling these tools with high-quality inputs, the sooner they can reap massive benefits.
 
 HumanLayer provides a set of tools to _deterministically_ guarantee human oversight of high stakes function calls. Even if the LLM makes a mistake or hallucinates, HumanLayer is baked into the tool/function itself, guaranteeing a human in the loop.
 
@@ -141,6 +141,24 @@ HumanLayer provides a set of tools to *deterministically* guarantee human oversi
 </blockquote></h3>
 </div>
 
+### The Future: Autonomous Agents and the "Outer Loop"
+
+Between `require_approval` and `human_as_tool`, HumanLayer is built to empower the next generation of AI agents - Autonomous Agents, but it's just a piece of the puzzle. To clarify "next generation", we can summarize briefly the history of LLM applications.
+
+- **Gen 1**: Chat - human-initiated question / response interface
+- **Gen 2**: Agentic Assistants - frameworks drive prompt routing, tool calling, chain of thought, and context window management to get much more reliability and functionality. Most workflows are initiated by humans in single-shot "here's a task, go do it" or rolling chat interfaces.
+- **Gen 3**: Autonomous Agents - no longer human initiated, agents will live in the "outer loop" driving toward their goals using various tools and functions. Human/Agent communication is Agent-initiated rather than human-initiated.
+
+![gen2 vs gen 3 agents](./docs/images/gen-2-gen-3-agents.png)
+
+Gen 3 autonomous agents will need ways to consult humans for input on various tasks. In order for these agents to perform actual useful work, they'll need human oversight for sensitive operations.
+
+These agents will require ways to contact one or more humans across various channels including chat, email, sms, and more.
+
+While early versions of these agents may technically be "human initiated" in that they get kicked off on a regular schedule by e.g. a cron or similar, the best ones will be managing their own scheduling and costs. This will require toolkits for inspecting costs and something akin to `sleep_until`. They'll need to run in orchestration frameworks that can durably serialize and resume agent workflows across tool calls that might not return for hours or days. These frameworks will need to support context window management by a "manager LLM" and enable agents to fork sub-chains to handle specialized tasks and roles.
+
+Example use cases for these outer loop agents include [the linkedin inbox assistant](./examples/langchain/04-human_as_tool_linkedin.py) and [the customer onboarding assistant](./examples/langchain/05-approvals_and_humans_composite.py), but that's really just scratching the surface.
+
 ## Key Features
 
 - **Require Human Approval for Function Calls**: the `@hl.require_approval()` decorator blocks specifc function calls until a human has been consulted - upon denial, feedback will be passed to the LLM

examples/langchain/05-approvals_and_humans_composite.py

@@ -1,3 +1,20 @@
+"""
+the summer marketing intern wrote an onboarding assistant
+to keep up to date with customers by emailing
+them suggestions.
+
+they want the agent to collaborate with their boss, the head of
+marketing to ensure emails are well-written and likely to
+achieve the desired outcome.
+
+The intern doesn't want the agent to annoy the head of marketing
+or ask questions that don't make sense, so they
+wrap the "contact head of marketing" tool in an
+approval requirement, so they can review any messages that would
+be sent to the head of marketing.
+
+"""
+
 import langchain_core.tools as langchain_tools
 from dotenv import load_dotenv
 from langchain_openai import ChatOpenAI
@@ -8,7 +25,6 @@ from humanlayer import (
 from langchain.agents import AgentType, initialize_agent
 
 from channels import (
-    dm_with_ceo,
     dm_with_head_of_marketing,
     dm_with_summer_intern,
 )
@@ -50,15 +66,11 @@ tools = [
     langchain_tools.StructuredTool.from_function(send_email),
     langchain_tools.StructuredTool.from_function(
         # allow the agent to contact the head of marketing,
-        # but require approval from the CEO before sending
-        hl.require_approval(contact_channel=dm_with_ceo).wrap(
+        # but require approval from the summer intern before sending
+        hl.require_approval(contact_channel=dm_with_summer_intern).wrap(
             hl.human_as_tool(contact_channel=dm_with_head_of_marketing)
         )
     ),
-    langchain_tools.StructuredTool.from_function(
-        # allow the agent to contact the summer intern
-        hl.human_as_tool(contact_channel=dm_with_summer_intern)
-    ),
 ]
 
 llm = ChatOpenAI(model="gpt-4o", temperature=0)