> ## Documentation Index
> Fetch the complete documentation index at: https://jobo.world/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# LangChain

> Tools, a retriever and a feed loader that give a LangChain agent live job search over Jobo's index, with a capped cost per call.

`langchain-jobo` is a LangChain integration package for the Jobo API. It depends on `langchain-core`, `httpx`, and `pydantic` only, and needs Python 3.10 or later.

> [!NOTE]
>
> The package is built and tested but not on PyPI yet, so `pip install langchain-jobo` does not resolve today.

| Component | What it does | Endpoint | Billed |
| - | - | - | - |
| `JoboSearchTool` (`jobo_job_search`) | Search jobs with the full filter set | [`POST /api/jobs/search`](https://jobo.world/docs/api-reference/jobs/search-jobs) | Per job returned |
| `JoboJobDetailsTool` (`jobo_job_details`) | One listing as readable prose | `GET /api/jobs/{id}` | Free |
| `JoboCompanySearchTool` (`jobo_company_search`) | A company name or domain to company ids | Company suggest | Free |
| `JoboRetriever` | A query to job `Document`s | `POST /api/jobs/search` | Per job returned |
| `JoboFeedLoader` | The job feed as `Document`s | `POST /api/jobs/feed` | Per new job |
| `get_jobo_tools()` | The three tools in one call | | |

For what all connectors share, see the [connectors overview](https://jobo.world/docs/connectors/overview.md).

***

## Install and authenticate

```bash theme={null}
pip install -U langchain-jobo
export JOBO_API_KEY="jbe_live_..."
```

Every component reads `JOBO_API_KEY`, or takes `api_key=...`. The key is held as a `SecretStr` and is only written into the `X-Api-Key` header.

A [sandbox key](https://jobo.world/docs/sandbox.md) works with the search tool, the details tool, and the retriever. `JoboFeedLoader` needs a live key.

***

## Agent

```python theme={null}
import os

from langchain.agents import create_agent
from langchain_jobo import get_jobo_tools

agent = create_agent(
    # A "provider:model" string for the chat model you use, or a chat model instance.
    model=os.environ["AGENT_MODEL"],
    tools=get_jobo_tools(max_page_size=10, handle_tool_error=True),
    system_prompt=(
        "You help people find jobs. Search with jobo_job_search, read a posting with "
        "jobo_job_details before describing it, and cite each job's listing URL."
    ),
)

result = agent.invoke(
    {"messages": [{"role": "user", "content": "Find three remote senior Python jobs paying over $150k."}]}
)
print(result["messages"][-1].content)
```

`handle_tool_error=True` hands an API error, such as a rate limit or an empty wallet, back to the model as the tool's answer. Without it the tool raises a `ToolException` and the run stops.

***

## Search tool

```python theme={null}
from langchain_jobo import JoboSearchTool

tool = JoboSearchTool(max_page_size=10)

print(
    tool.invoke(
        {
            "query": "backend engineer",
            "location": "Berlin, Germany",
            "work_model": ["remote", "hybrid"],
            "experience_level": ["senior"],
            "exclude_skills": ["PHP"],
            "min_salary_usd": 90000,
            "page_size": 3,
        }
    )
)
```

* The arguments are the filters of `POST /api/jobs/search`, with `query` in place of `q`. Each include filter has an `exclude_` twin where the API has one.
* Enum filters take the API's lowercase values. An unknown value is rejected before any request, because the API answers it with zero results rather than an error.
* `page_size` defaults to 5. The tool never requests more than `max_page_size` (default 25, at most 100), whatever the model asks for.
* Called with a `ToolCall`, the tool returns a `ToolMessage` whose `artifact` holds the raw jobs, paging, warnings, and the usage the API reported.

***

## Retriever

```python theme={null}
from langchain_jobo import JoboRetriever

retriever = JoboRetriever(k=5, filters={"location": "London", "work_model": ["remote", "hybrid"]})

for doc in retriever.invoke("staff data engineer"):
    print(doc.metadata["title"], "-", doc.metadata["company"], doc.metadata["url"])
```

`page_content` is self-contained prose. `metadata` carries the id, URLs, title, company, location, salary, and dates; a key is present only when the posting has the value. Each query bills up to `k` jobs.

***

## Feed loader

```python theme={null}
from langchain_jobo import JoboFeedLoader

loader = JoboFeedLoader(max_jobs=500, filters={"sources": ["greenhouse"], "work_models": ["remote"]})

for doc in loader.lazy_load():
    print(doc.metadata["title"])

if loader.has_more:
    print("resume from:", loader.last_cursor)
```

* `max_jobs` is required and has no default, because the feed streams every matching job and bills each one that is [new to you](https://jobo.world/docs/billing.md#unique-jobs-on-feed-export-and-outbound). Pass `max_jobs=None` to opt in to reading the whole feed.
* `max_jobs` is an upper bound. The loader reads whole, equal batches that fit under it, so `max_jobs=2500` loads 2,499 jobs in three batches of 833.
* Persist `loader.last_cursor` and pass it back as `cursor=` to resume. A cursor keeps the filters of the scan it came from.
* The filters are the feed's own, not the search tool's: see [`POST /api/jobs/feed`](https://jobo.world/docs/api-reference/feed/stream-the-job-feed).

***

## Cost

Search bills every job a response returns; the feed bills a job once per 30 days; job and company lookups are free ([cost model](https://jobo.world/docs/connectors/overview.md#cost-model)). `402` is never retried.

An agent that searches in a loop spends per job returned on every call. Keep `max_page_size` low and say in the prompt when to stop searching.

***

> [card] [Related: MCP server](https://jobo.world/docs/connectors/mcp.md)
>
> For an assistant or coding agent you don't write yourself, the MCP server exposes the same search without any code.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.