암호화폐 신원, A2A 메시징, x402 USDC 결제를 갖춘 연구 에이전트를 Bindufy하세요

# Making Your Agent Network-Addressable with Bindu

## 1. Verify Python 3.12+ and uv, add bindu

```bash
python --version   # must be >= 3.12
uv --version       # install via: curl -LsSf https://astral.sh/uv/install.sh | sh
```

Add the dependency (adjust to your project layout):

```bash
uv add bindu
```

If you're on a `pyproject.toml`-based project, this updates it and the lockfile. For a plain `requirements.txt` setup, add `bindu` to it and run `uv pip install -r requirements.txt`.

## 2. Locate your agent entrypoint

Your handler should have the signature `(messages) -> response`. Common shapes:

- **Agno**: `agent.run(messages)` or a thin wrapper around it
- **LangChain**: a `Runnable` or a function calling `chain.invoke(messages)`
- **Custom**: any callable taking a list of messages and returning a response

Identify the exact callable and the module path, e.g. `my_agent.handler:run`. You will not modify it.

## 3. Wrap with `bindufy` (handler unchanged)

Create a new file, e.g. `serve.py`, at the repo root:

```python
# serve.py
import os
from bindu.penguin.bindufy import bindufy
from my_agent.handler import run  # <-- your existing handler, unchanged

bindufy(
    handler=run,
    name="my-agent",
    description="My existing agent, now reachable over A2A.",
    skills=[
        {
            "id": "chat",
            "name": "Chat",
            "description": "General-purpose conversational responses.",
        },
    ],
    # x402 payment gating (see step 5)
    payment={
        "address": os.environ["X402_RECEIVING_ADDRESS"],
        "price": os.environ["X402_PRICE"],
        "chain": "base",  # EVM chain used for settlement
    },
)
```

`bindufy` wraps your handler as-is; it does not touch internal logic. It exposes the agent over A2A and advertises the name/description/skills in the agent card so other agents can discover it.

## 4. Agent config for discovery

The `name`, `description`, and `skills` passed to `bindufy` are what other agents see when they fetch your agent card over A2A. Keep skill `id`s stable — they're the contract other agents reference. If you prefer config-as-data, move these into a `agent_config.yaml` and load it before calling `bindufy`; the fields are the same.

## 5. x402 payment gating

Read the receiving address and price from env vars (never hardcode):

```bash
export X402_RECEIVING_ADDRESS=0xYourReceivingAddress
export X402_PRICE="0.01"
```

**EVM chain used:** Base (mainnet). If you need a different chain, change `"chain": "base"` in `serve.py` to the target chain identifier supported by your x402 facilitator (e.g. `base-sepolia` for testnet). Document the chosen chain in your README so callers know where to settle payment.

## 6. LLM provider key from env

Ensure your agent reads its key from the environment. In your existing handler (or a small config module it already imports), the key should come from:

```python
import os

api_key = (
    os.environ.get("OPENROUTER_API_KEY")
    or os.environ.get("OPENAI_API_KEY")
    or os.environ.get("MINIMAX_API_KEY")
)
if not api_key:
    raise RuntimeError("No LLM provider key set (OPENROUTER_API_KEY / OPENAI_API_KEY / MINIMAX_API_KEY)")
```

If your handler already does this, leave it alone. If it currently hardcodes a key, replace the literal with the env lookup above — that's the only change, and it doesn't alter logic.

## 7. Smoke test

```python
# tests/test_smoke.py
import os
import pytest
from bindu.client import A2AClient  # adjust import to your bindu version

@pytest.mark.asyncio
async def test_agent_responds_over_a2a():
    # Assumes the agent is running locally (see README) at this URL.
    client = A2AClient(base_url=os.environ.get("AGENT_URL", "http://localhost:8000"))

    response = await client.send_message(
        messages=[{"role": "user", "content": "Hello, are you there?"}],
    )

    assert response is not None
    assert response.get("signature"), "expected a signed response"
    assert response.get("content"), "expected non-empty content"
```

Run it against a locally started agent:

```bash
uv run python serve.py &          # start agent
uv run pytest tests/test_smoke.py # send sample A2A message, assert signed response
```

If your bindu version exposes a different client helper, swap `A2AClient` for the equivalent — the assertion (signed, non-empty response) stays the same.

## 8. README section

```markdown
## Running locally

1. Set required env vars:
   ```bash
   export OPENROUTER_API_KEY=...        # or OPENAI_API_KEY / MINIMAX_API_KEY
   export X402_RECEIVING_ADDRESS=0x...
   export X402_PRICE=0.01
   ```
2. Start the agent:
   ```bash
   uv run python serve.py
   ```
3. The agent is now reachable over A2A at `http://localhost:8000`. Other agents can discover it via its agent card (name, description, skills).

## Viewing traffic in the Bindu inbox

Open the Bindu inbox UI (default `http://localhost:8000/inbox`) to see incoming A2A messages, responses, and payment-gated requests in real time. Use it to confirm your agent is receiving and answering messages as expected.

## Payments

Requests are gated by x402. Settlement happens on **Base** (mainnet). Set `X402_RECEIVING_ADDRESS` and `X402_PRICE` before starting the agent.
```

---

**Summary of changes:** added `bindu` as a dependency; created `serve.py` that wraps your existing handler with `bindufy` (handler untouched); configured name/description/skills for A2A discovery; wired x402 payment via env vars with Base as the documented EVM chain; ensured the LLM key is read from env; added a smoke test asserting a signed A2A response; and documented local run + Bindu inbox in the README. Your agent's internal logic is unchanged.