Anthropic Claude — Direct API Implementation Documentation (Docs-Only)

1) Overview

Goal: Route Buyer/Seller agent reasoning through Anthropic Claude models using Anthropic's direct API.
Scope: Documentation only. This guide specifies configuration, interfaces, and testing strategy to implement later.

2) Official Documentation (verify before implementing)

Anthropic API Getting Started:

https://docs.anthropic.com/en/api/getting-started

Anthropic Messages API:

https://docs.anthropic.com/en/api/messages

Anthropic Python SDK:

https://github.com/anthropics/anthropic-sdk-python

Anthropic Console (API Keys):
```
https://console.anthropic.com/
```

Model Information:

https://docs.anthropic.com/en/docs/models-overview

3) Prerequisites

Anthropic account and API key from
```
https://console.anthropic.com/
```

Choose a Claude model (e.g.,

claude-3-5-sonnet-20241022

claude-3-opus-20240229

claude-3-haiku-20240307

)

Confirm current model names and availability in Anthropic's documentation before rollout.

4) Installation

Python SDK:

```
pip install anthropic
```
Use the Anthropic SDK (
```
from anthropic import Anthropic
```
)

5) Configuration (Environment)

Add to backend
```
.env
```
(documented names; adjust if your project uses different keys):
- ```
LLM_PROVIDER=anthropic
```
- ```
ANTHROPIC_API_KEY=sk-ant-...
```
  (obtain from https://console.anthropic.com/)
- ```
ANTHROPIC_DEFAULT_MODEL=claude-3-5-sonnet-20241022
```
  (example; confirm latest model name in Anthropic docs)
- Optional:
```
ANTHROPIC_API_VERSION=2023-06-01
```
  (default is usually latest)
- Optional:
```
ANTHROPIC_MAX_RETRIES=3
```
  (default retry behavior)
- Optional:
```
ANTHROPIC_TIMEOUT=60
```
  (seconds, default varies by SDK)

Document the mapping in your config file (no code yet). For per-session provider selection, store the chosen provider/model with the Session record.

6) Implementation Details (to be implemented later)

Provider Factory:

Instantiate the Anthropic client with:

```
api_key=os.environ["ANTHROPIC_API_KEY"]
```
Optional:
```
max_retries
```
,
```
timeout
```
from env

Expose

generate(messages, temperature, max_tokens, stop, model)

and

stream(...)

Model Naming:
- Use Anthropic model names exactly as documented, e.g.,
```
claude-3-5-sonnet-20241022
```
  ,
```
claude-3-opus-20240229
```
  ,
```
claude-3-haiku-20240307
```
  (verify latest names in Anthropic docs).
Request Shape (Messages API):
- Messages array of
```
{ "role": "user"|"assistant", "content": "..." }
```
  .
- System prompt passed separately via
```
system
```
  parameter (not in messages array).
- Parameters:
```
temperature
```
  ,
```
max_tokens
```
  , optional
```
stop_sequences
```
  .
Streaming:
- Use
```
stream=True
```
  . Parse Server-Sent Events (SSE) format with
```
text_delta
```
  events from the stream.
Error Handling:
- 401 → invalid API key; check key format and permissions.
- 403 → insufficient permissions or account limits.
- 429 → rate limit; SDK handles retries with exponential backoff by default.
- 5xx → transient provider error; SDK retries automatically, cap attempts if needed.

7) Usage Examples (reference only; not implemented yet)

Non-streaming (Python):

import os
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ["ANTHROPIC_API_KEY"],
)

message = client.messages.create(
    model=os.environ.get("ANTHROPIC_DEFAULT_MODEL", "claude-3-5-sonnet-20241022"),
    max_tokens=500,
    temperature=0.7,
    system="You are a strategic buyer negotiating within constraints.",
    messages=[
        {"role": "user", "content": "I need 3 USB-C cables under $9 each. What can you offer?"}
    ],
)

text = message.content[0].text
print(text)

Streaming (Python):

import os
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ["ANTHROPIC_API_KEY"],
)

with client.messages.stream(
    model="claude-3-5-sonnet-20241022",
    max_tokens=200,
    temperature=0.7,
    messages=[{"role": "user", "content": "Stream a short reply."}],
) as stream:
    for text_block in stream.text_stream:
        # text_block is a string chunk
        print(text_block, end="", flush=True)
print()

8) Prompting Notes (Buyer/Seller)

Buyer:
- System prompt includes: item, quantity, min/max price; objective to pick best offer based on conversation evidence only (no scoring formulas).
Seller:
- System prompt includes: cost (never reveal), selling price, least price, style, and priorities. Enforce never going below least price.
Prompt Templates:
- Keep role separation clear; avoid leaking hidden seller data to buyer prompts.
- Keep messages concise to conserve tokens (document your token budgeting policy).

9) Testing Strategy (to execute after implementation)

Unit Tests:
- Factory returns Anthropic provider when configured.
- Non-stream and stream result parsing with mocked responses.
- Error mapping for 401/403/429/5xx.
Integration Tests:
- Health/status endpoint includes current provider and model.
- Simple round-trip request to Anthropic API with a Claude model in a dev environment (guarded by env flag).
Performance:
- Verify reasonable latency per call (document baseline).
- SDK handles retries automatically; verify backoff behavior.

10) Troubleshooting

401 Unauthorized:
- Check
```
ANTHROPIC_API_KEY
```
  . Ensure it starts with
```
sk-ant-
```
  and has no extra whitespace/newlines.
- Verify key is active in Anthropic Console.
403 Forbidden:
- Check account permissions and usage limits in Anthropic Console.
- Verify billing/credits are available.
429 Rate Limit:
- SDK retries automatically with exponential backoff.
- Reduce concurrency or token usage if limits persist.
- Consider using a smaller/faster model (e.g., claude-3-haiku) for development.
TLS/Network Issues:
- Confirm outbound HTTPS to
```
api.anthropic.com
```
  .
- Check proxies/enterprise firewalls.

11) Cost & Usage Considerations

Pricing is model-specific; confirm on Anthropic's pricing page:
```
https://www.anthropic.com/pricing
```
Use smaller/faster models (claude-3-haiku) in development; switch to higher-quality models (claude-3-5-sonnet, claude-3-opus) for evaluation runs.
Log prompt/response token counts to estimate costs (once implemented).
Monitor usage in Anthropic Console.

12) Security Best Practices

Never commit API keys. Load from environment or secure vault.
Limit logs to non-sensitive metadata; avoid logging full prompts/responses in production.
Use environment variables or secret management systems for API keys.
Rotate API keys periodically and monitor usage in Anthropic Console.

13) Rollout Checklist (Docs-Only)

Verify chosen model name in Anthropic docs and note it in
```
.env
```
templates.
Document environment variables and default values.
Document provider selection rules (global vs per-session).
Document retry/backoff policy (SDK handles automatically).
Add links to this doc from the main README and integration index.

Anthropic Claude — Direct API Implementation Documentation (Docs-Only)

1) Overview

Goal: Route Buyer/Seller agent reasoning through Anthropic Claude models using Anthropic's direct API.
Scope: Documentation only. This guide specifies configuration, interfaces, and testing strategy to implement later.

2) Official Documentation (verify before implementing)

Anthropic API Getting Started:

https://docs.anthropic.com/en/api/getting-started

Anthropic Messages API:

https://docs.anthropic.com/en/api/messages

Anthropic Python SDK:

https://github.com/anthropics/anthropic-sdk-python

Anthropic Console (API Keys):
```
https://console.anthropic.com/
```

Model Information:

https://docs.anthropic.com/en/docs/models-overview

3) Prerequisites

Anthropic account and API key from
```
https://console.anthropic.com/
```

Choose a Claude model (e.g.,

claude-3-5-sonnet-20241022

claude-3-opus-20240229

claude-3-haiku-20240307

)

Confirm current model names and availability in Anthropic's documentation before rollout.

4) Installation

Python SDK:

```
pip install anthropic
```
Use the Anthropic SDK (
```
from anthropic import Anthropic
```
)

5) Configuration (Environment)

Add to backend
```
.env
```
(documented names; adjust if your project uses different keys):
- ```
LLM_PROVIDER=anthropic
```
- ```
ANTHROPIC_API_KEY=sk-ant-...
```
  (obtain from https://console.anthropic.com/)
- ```
ANTHROPIC_DEFAULT_MODEL=claude-3-5-sonnet-20241022
```
  (example; confirm latest model name in Anthropic docs)
- Optional:
```
ANTHROPIC_API_VERSION=2023-06-01
```
  (default is usually latest)
- Optional:
```
ANTHROPIC_MAX_RETRIES=3
```
  (default retry behavior)
- Optional:
```
ANTHROPIC_TIMEOUT=60
```
  (seconds, default varies by SDK)

Document the mapping in your config file (no code yet). For per-session provider selection, store the chosen provider/model with the Session record.

6) Implementation Details (to be implemented later)

Provider Factory:

Instantiate the Anthropic client with:

```
api_key=os.environ["ANTHROPIC_API_KEY"]
```
Optional:
```
max_retries
```
,
```
timeout
```
from env

Expose

generate(messages, temperature, max_tokens, stop, model)

and

stream(...)

Model Naming:
- Use Anthropic model names exactly as documented, e.g.,
```
claude-3-5-sonnet-20241022
```
  ,
```
claude-3-opus-20240229
```
  ,
```
claude-3-haiku-20240307
```
  (verify latest names in Anthropic docs).
Request Shape (Messages API):
- Messages array of
```
{ "role": "user"|"assistant", "content": "..." }
```
  .
- System prompt passed separately via
```
system
```
  parameter (not in messages array).
- Parameters:
```
temperature
```
  ,
```
max_tokens
```
  , optional
```
stop_sequences
```
  .
Streaming:
- Use
```
stream=True
```
  . Parse Server-Sent Events (SSE) format with
```
text_delta
```
  events from the stream.
Error Handling:
- 401 → invalid API key; check key format and permissions.
- 403 → insufficient permissions or account limits.
- 429 → rate limit; SDK handles retries with exponential backoff by default.
- 5xx → transient provider error; SDK retries automatically, cap attempts if needed.

7) Usage Examples (reference only; not implemented yet)

Non-streaming (Python):

import os
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ["ANTHROPIC_API_KEY"],
)

message = client.messages.create(
    model=os.environ.get("ANTHROPIC_DEFAULT_MODEL", "claude-3-5-sonnet-20241022"),
    max_tokens=500,
    temperature=0.7,
    system="You are a strategic buyer negotiating within constraints.",
    messages=[
        {"role": "user", "content": "I need 3 USB-C cables under $9 each. What can you offer?"}
    ],
)

text = message.content[0].text
print(text)

Streaming (Python):

import os
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ["ANTHROPIC_API_KEY"],
)

with client.messages.stream(
    model="claude-3-5-sonnet-20241022",
    max_tokens=200,
    temperature=0.7,
    messages=[{"role": "user", "content": "Stream a short reply."}],
) as stream:
    for text_block in stream.text_stream:
        # text_block is a string chunk
        print(text_block, end="", flush=True)
print()

8) Prompting Notes (Buyer/Seller)

Buyer:
- System prompt includes: item, quantity, min/max price; objective to pick best offer based on conversation evidence only (no scoring formulas).
Seller:
- System prompt includes: cost (never reveal), selling price, least price, style, and priorities. Enforce never going below least price.
Prompt Templates:
- Keep role separation clear; avoid leaking hidden seller data to buyer prompts.
- Keep messages concise to conserve tokens (document your token budgeting policy).

9) Testing Strategy (to execute after implementation)

Unit Tests:
- Factory returns Anthropic provider when configured.
- Non-stream and stream result parsing with mocked responses.
- Error mapping for 401/403/429/5xx.
Integration Tests:
- Health/status endpoint includes current provider and model.
- Simple round-trip request to Anthropic API with a Claude model in a dev environment (guarded by env flag).
Performance:
- Verify reasonable latency per call (document baseline).
- SDK handles retries automatically; verify backoff behavior.

10) Troubleshooting

401 Unauthorized:
- Check
```
ANTHROPIC_API_KEY
```
  . Ensure it starts with
```
sk-ant-
```
  and has no extra whitespace/newlines.
- Verify key is active in Anthropic Console.
403 Forbidden:
- Check account permissions and usage limits in Anthropic Console.
- Verify billing/credits are available.
429 Rate Limit:
- SDK retries automatically with exponential backoff.
- Reduce concurrency or token usage if limits persist.
- Consider using a smaller/faster model (e.g., claude-3-haiku) for development.
TLS/Network Issues:
- Confirm outbound HTTPS to
```
api.anthropic.com
```
  .
- Check proxies/enterprise firewalls.

11) Cost & Usage Considerations

Pricing is model-specific; confirm on Anthropic's pricing page:
```
https://www.anthropic.com/pricing
```
Use smaller/faster models (claude-3-haiku) in development; switch to higher-quality models (claude-3-5-sonnet, claude-3-opus) for evaluation runs.
Log prompt/response token counts to estimate costs (once implemented).
Monitor usage in Anthropic Console.

12) Security Best Practices

Never commit API keys. Load from environment or secure vault.
Limit logs to non-sensitive metadata; avoid logging full prompts/responses in production.
Use environment variables or secret management systems for API keys.
Rotate API keys periodically and monitor usage in Anthropic Console.

13) Rollout Checklist (Docs-Only)

Verify chosen model name in Anthropic docs and note it in
```
.env
```
templates.
Document environment variables and default values.
Document provider selection rules (global vs per-session).
Document retry/backoff policy (SDK handles automatically).
Add links to this doc from the main README and integration index.

Anthropic Claude — Direct API Implementation Documentation (Docs-Only)

Anthropic Claude — Direct API Implementation Documentation (Docs-Only)

1) Overview

2) Official Documentation (verify before implementing)

3) Prerequisites

4) Installation

5) Configuration (Environment)

6) Implementation Details (to be implemented later)

7) Usage Examples (reference only; not implemented yet)

8) Prompting Notes (Buyer/Seller)

9) Testing Strategy (to execute after implementation)

10) Troubleshooting

11) Cost & Usage Considerations

12) Security Best Practices

13) Rollout Checklist (Docs-Only)

Related Skills

Nano Banana Pro

Markdown Converter

1password

Anthropic Claude — Direct API Implementation Documentation (Docs-Only)

1) Overview

2) Official Documentation (verify before implementing)

3) Prerequisites

4) Installation

5) Configuration (Environment)

6) Implementation Details (to be implemented later)

7) Usage Examples (reference only; not implemented yet)

8) Prompting Notes (Buyer/Seller)

9) Testing Strategy (to execute after implementation)

10) Troubleshooting

11) Cost & Usage Considerations

12) Security Best Practices

13) Rollout Checklist (Docs-Only)