> For the complete documentation index, see [llms.txt](https://black-sheep-finance.gitbook.io/black-sheep-finance-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://black-sheep-finance.gitbook.io/black-sheep-finance-docs/guides/nous-hermes.md).

# Nous Hermes agent integration

Black Sheep was built with **NousResearch/hermes-agent** — the agent framework that grows with you. Hermes provides the reasoning layer; Black Sheep provides the wallet layer. Together they let an LLM think, plan, and pay — without ever touching a private key.

## What Hermes brings

Hermes is a modular agent runtime from Nous Research designed for long-horizon tasks, tool use, and safe execution. It handles:

* **Planning** — decompose user requests into sub-tasks and decide which tools to call.
* **Memory** — retain context across multi-turn sessions and tool executions.
* **Reflection** — self-correct when a tool call fails or returns unexpected data.
* **Safety** — structured output and constrained action spaces by default.

## What Black Sheep adds

Black Sheep plugs into Hermes as a set of native tools (`send_usdc`, `get_wallet_info`, `list_recent_transactions`). Every tool call is gated by a server-side policy:

* The agent **cannot** see or export private keys.
* The agent **cannot** raise its own spending limits.
* The agent **cannot** send to addresses outside the allowlist.
* Any spend above the approval threshold **pauses** and waits for a human.

## Architecture

```
┌─────────────────┐      plan / reason      ┌──────────────────┐
│  Nous Hermes    │ ◀────────────────────── │   User prompt    │
│  agent runtime  │                         └──────────────────┘
└────────┬────────┘
         │
         ▼  tool call
┌─────────────────┐      policy check       ┌──────────────────┐
│  Black Sheep    │ ─────────────────────▶ │  Policy engine   │
│  wallet tools   │                         │  (server-side)   │
└────────┬────────┘                         └────────┬─────────┘
         │                                            │
         ▼ allow / approve / deny                     ▼
┌─────────────────┐                         ┌──────────────────┐
│  Solana mainnet │                         │  Slack / webhook │
│  USDC settlement│                         │  human approval  │
└─────────────────┘                         └──────────────────┘
```

## Wiring Hermes to Black Sheep

Register the Black Sheep tool pack in your Hermes agent config:

```ts
import { blackSheepTools } from "@blacksheep/sdk/hermes";

const walletTools = blackSheepTools({
  apiKey: process.env.BS_API_KEY!,
  agentId: process.env.BS_AGENT_ID!, // the wallet you issued in the dashboard
});

const agent = new HermesAgent({
  model: "nous-hermes-2-pro",
  tools: [
    ...walletTools,
    myCustomLookupTool,
    myCustomDataTool,
  ],
  systemPrompt:
    "You are a research assistant with a budgeted USDC wallet. " +
    "When the user asks for paid data, confirm the recipient address " +
    "and amount, then use send_usdc. You cannot spend more than your policy allows.",
});

const result = await agent.run({
  input: "Pay 10 USDC to 7xKX...abc for the population dataset.",
});
```

## Safety model

Hermes already constrains the action space to registered tools. Black Sheep adds a second layer: even if the agent is prompt-injected or hallucinates a tool argument, the server-side policy is the final gate.

| Layer              | What it blocks                                             |
| ------------------ | ---------------------------------------------------------- |
| Hermes tool schema | Invalid arguments, missing fields                          |
| Black Sheep policy | Over-budget spends, unknown recipients, daily cap breaches |
| Approval threshold | Any spend above the threshold pauses for human review      |

## Tips

* Set `approval_threshold_usdc` low while you are tuning prompts and observing agent behaviour.
* Use distinct agent wallets per workflow — Hermes supports multi-agent orchestration and each wallet gets its own policy.
* Combine Hermes reflection loops with Black Sheep webhooks: when a spend is blocked, the agent can reason about why and suggest alternatives within budget.

## Learn more

* [Nous Hermes on Hugging Face](https://huggingface.co/NousResearch) — model cards and inference examples.
* [LangChain integration →](/black-sheep-finance-docs/guides/langchain.md) — if you are using LangChain instead of the native Hermes runtime.
* [Multi-agent budgets →](/black-sheep-finance-docs/guides/multi-agent.md) — run a flock of Hermes agents, each with its own wallet and policy.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://black-sheep-finance.gitbook.io/black-sheep-finance-docs/guides/nous-hermes.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.