Metadata-Version: 2.4
Name: agentdraft-langchain
Version: 0.1.0
Summary: LangChain tools for AgentDraft — let LangChain, LangGraph, CrewAI, and AutoGen agents book calendars through the coordination layer without colliding.
Author-email: AgentDraft Labs <hello@agentdraft.io>
License: MIT
Project-URL: Homepage, https://agentdraft.io
Project-URL: Documentation, https://agentdraft.io/docs
Project-URL: Specification, https://agentdraft.io/spec
Project-URL: Changelog, https://agentdraft.io/changelog
Keywords: agentdraft,langchain,langgraph,crewai,autogen,ai-agents,agents,calendar,scheduling,tools
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Scheduling
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: agentdraft>=0.1.0
Requires-Dist: langchain-core>=0.3
Provides-Extra: dev
Requires-Dist: pytest>=8.3.0; extra == "dev"
Dynamic: license-file

# agentdraft-langchain — LangChain tools for AgentDraft

[![PyPI](https://img.shields.io/pypi/v/agentdraft-langchain.svg)](https://pypi.org/project/agentdraft-langchain/)
[![Python](https://img.shields.io/pypi/pyversions/agentdraft-langchain.svg)](https://pypi.org/project/agentdraft-langchain/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://agentdraft.io/legal/license)

LangChain tools that let an agent book calendars through
[AgentDraft](https://agentdraft.io) — the coordination layer for AI
scheduling agents — so two agents racing for the same slot resolve to a
single deterministic winner instead of double-booking your calendar.

Each tool is a `langchain_core.tools.BaseTool`: **LangChain** and
**LangGraph** consume it directly, **CrewAI** accepts LangChain tools
natively, and **AutoGen** uses it through its `LangChainToolAdapter`.

## Install

```bash
pip install agentdraft-langchain
```

Requires Python 3.9+, `langchain-core>=0.3`, and a valid `avs_live_…`
agent key from the AgentDraft dashboard.

## Quickstart

```python
from agentdraft_langchain import get_agentdraft_tools

# Reads AGENTDRAFT_API_KEY (and optional AGENTDRAFT_BASE_URL) from the env.
tools = get_agentdraft_tools()

# Hand `tools` to any langchain-core-compatible agent. With LangGraph:
from langgraph.prebuilt import create_react_agent
from langchain_openai import ChatOpenAI

agent = create_react_agent(ChatOpenAI(model="gpt-4o"), tools)
agent.invoke({"messages": [("user", "Book me a 30-min call tomorrow at 2pm UTC.")]})
```

`get_agentdraft_tools()` returns two tools: `agentdraft_get_availability`
and a booking tool. By default the booking tool is **conflict-aware** —
see below.

## The tools

| Tool | `name` | Purpose |
|---|---|---|
| `AvailabilityTool` | `agentdraft_get_availability` | List the slots open to this agent between two times |
| `ConflictAwareBookingTool` | `agentdraft_commit_booking_safe` | Commit a booking; on a lost race, return guidance instead of raising |
| `BookingTool` | `agentdraft_commit_booking` | Commit a booking; raise `ToolException` if outranked |

All times are ISO 8601 strings (`2026-06-01T14:00:00Z`). The booking
tools accept an optional `idempotency_key` for safe retries.

You can also construct tools directly against an explicit client:

```python
from agentdraft import Client
from agentdraft_langchain import AvailabilityTool, ConflictAwareBookingTool

client = Client(api_key="avs_live_...")
tools = [AvailabilityTool(client=client), ConflictAwareBookingTool(client=client)]
```

## How a lost race surfaces

When two agents race for the same slot, exactly one wins. The booking
tools differ only in how the *losing* agent finds out:

- **`ConflictAwareBookingTool`** (default in `get_agentdraft_tools()`)
  returns a plain-language message so the LLM can react:

  ```
  OUTRANKED — your booking was not committed. A higher-priority agent
  (agent_id=agt_sales, priority=1) already holds this slot
  (winning_booking_id=bkg_…). Your priority is 3. Do not retry the same
  slot — call agentdraft_get_availability and propose a different time
  to your user.
  ```

  An autonomous agent reads this and proposes an alternate slot.

- **`BookingTool`** raises `langchain_core.tools.ToolException` with the
  same message. Use it when you want the surrounding framework to handle
  the failure explicitly.

A lost race is a normal, expected outcome of a coordination layer — not
a bug. Prefer the conflict-aware tool for agents that run unattended.

## Use with CrewAI / AutoGen

CrewAI accepts LangChain tools directly — pass the list
`get_agentdraft_tools()` returns to a CrewAI `Agent(tools=...)`. AutoGen
wraps each tool with `LangChainToolAdapter` from `autogen_ext.tools.langchain`.
Either way the conflict semantics are identical to the LangChain path.

## How this differs from the other AgentDraft packages

| | `agentdraft` (SDK) | `agentdraft-langchain` | `agentdraft-mcp` |
|---|---|---|---|
| **Caller** | App code you wrote | A LangChain-family agent | An MCP host (Claude Desktop, etc.) |
| **Surface** | `Client` methods | `BaseTool` objects | MCP tools over stdio |
| **Conflict** | `Conflict` exception | Message or `ToolException` | Structured JSON result |

All three wrap the same REST API with the same auth and semantics.

## Links

- Protocol spec: <https://agentdraft.io/spec>
- API docs: <https://agentdraft.io/docs>
- Python SDK: [`agentdraft`](https://pypi.org/project/agentdraft/)
- Changelog: <https://agentdraft.io/changelog>
- Source & issues: <https://github.com/GipsyChef/agentdraft>

## Security

Found a vulnerability? See <https://agentdraft.io/security> — **do not**
open a public issue for a security report.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). This package lives inside the
[`GipsyChef/agentdraft`](https://github.com/GipsyChef/agentdraft)
monorepo under `sdks/langchain/`.

## License

MIT — see <https://agentdraft.io/legal/license>.
