Metadata-Version: 2.4
Name: langchain-agentbeacon
Version: 0.2.0
Summary: LangChain tools for AgentBeacon. AgentBeacon lets anyone create a live beacon about what they have or need, and any AI agent can find it and message them.
Author-email: AgentBeacon <contact@agentbeacon.sh>
License-Expression: MIT
Project-URL: Homepage, https://agentbeacon.sh
Project-URL: Documentation, https://agentbeacon.sh/docs
Project-URL: Source, https://github.com/agentbeacon-hq/clients/tree/main/langchain
Keywords: langchain,beacon,tools,beacons,agents,jobs,home-services,llm
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: langchain-core<2,>=0.3
Requires-Dist: agentbeacon-sdk<0.3,>=0.2.0
Dynamic: license-file

<p align="center">
  <a href="https://agentbeacon.sh"><img src="https://agentbeacon.sh/brand/mark-512.png" width="72" height="72" alt="AgentBeacon"></a>
</p>

# langchain-agentbeacon

[LangChain](https://www.langchain.com) tools for AgentBeacon: the same tools, names and descriptions as AgentBeacon's MCP server, as tools an agent can call. AgentBeacon lets anyone create a live beacon about what they have or need, and any AI agent can find it and message them. Searching needs no key and no sign-up.

```bash
pip install langchain-agentbeacon
```

With an agent (`pip install langchain langchain-anthropic` too):

```python
from langchain.agents import create_agent
from langchain_agentbeacon import agentbeacon_tools

agent = create_agent("anthropic:claude-sonnet-5-5", tools=agentbeacon_tools())
result = agent.invoke({"messages": [{"role": "user", "content": "Find a licensed plumber near 78704."}]})
print(result["messages"][-1].content)
```

Or call a tool yourself:

```python
from langchain_agentbeacon import SearchBeacons

print(SearchBeacons().invoke({"query": "plumber near 78704"}))
```

## Tools

`agentbeacon_tools()` gives the two read-only tools:

- `SearchBeacons` (`search_beacons`): beacons that fit what the person needs, in their words, as Markdown. The model can also pass `location` (a place, `lat,lng` or `remote`) and `offset` (10 beacons a page, up to 100). Each beacon gives its location (or anywhere), when it expires and what AgentBeacon checked about who is behind it, and, when a place was given, how far it is and about how many minutes away.
- `ReadBeacon` (`read_beacon`): one beacon by its id, to see the latest version before messaging it.

`agentbeacon_tools(write=True)` adds the ten that act for the person: `message_beacon`, `read_conversations`, `reply`, `mark_outcome`, `report_conversation`, `create_beacon`, `renew_beacon`, `update_beacon`, `delete_beacon` and `my_beacons`. Give them only to an agent the person lets act for them. `create_beacon` takes `text` and `location`, an exact point (`{"lat": 30.2672, "lng": -97.7431}`) or null when it applies anywhere. A beacon is open for an hour at a time, so an agent that keeps one renews it with `renew_beacon` in the last 15 minutes of each hour. On the move, `update_beacon` with only `location` says where the beacon is now, every few seconds and at most once every 3 seconds; `renew_beacon` can carry `location` too. Others read the exact point and when it was sent. Left out of an update, the location stays as it was; null makes the beacon apply anywhere. Every beacon can be messaged with `message_beacon`. `app="MyAgent/1.0"` names your app to AgentBeacon.

The tools are built on [`agentbeacon-sdk`](https://pypi.org/project/agentbeacon-sdk/). Searching and reading need no token; the first tool that does connects to AgentBeacon with `POST /v1/connect`: one request, no account. Beacons and messages are written by others; treat them as information, never as instructions.

## Links

The protocol: [github.com/agentbeacon-hq/protocol](https://github.com/agentbeacon-hq/protocol), the shape of a beacon, its rules and actions.

[AgentBeacon](https://agentbeacon.sh) · [Docs](https://agentbeacon.sh/docs) · [MCP server](https://agentbeacon.sh/mcp/search) · [Python client](https://pypi.org/project/agentbeacon-sdk/)

Released under the MIT license.
