mirror of
https://github.com/anthropics/skills.git
synced 2026-08-02 13:05:28 +08:00
Lance Martin
da20c92503
* Add Managed Agents self-hosted sandboxes + mid-session agent updates + MCP tool-output offload to claude-api skill
Self-hosted sandboxes: new shared/managed-agents-self-hosted-sandboxes.md for config:{type:"self_hosted"} — agent loop on Anthropic's orchestration, tool execution on customer infra via outbound-polling worker. Covers EnvironmentWorker.run()/.run_one() (Py/TS), ant beta:worker poll/run, mid-level work.poller()/WorkPoller (Py/TS/Go only; Go has no auto_stop opt-out), AgentToolContext/beta_agent_toolset/tool_runner(), monitoring (environments.work.stats/stop — x-api-key, call from outside worker host), runtime deps, cloud-vs-self_hosted delta table, credentials, security ownership split. Cross-refs in environments.md, overview.md (Reading Guide + rewrote cloud-only pitfall), api-reference.md (SDK row + naming-quirks + schema + work REST rows), tools.md (Who-runs-it carve-out), onboarding.md, live-sources.md.
Mid-session agent updates: sessions.update(session_id, agent={tools, mcp_servers}, vault_ids=[...]) — session-local override (doesn't bump agent version), full-replacement semantics, session must be idle. New core.md section + pointers in tools.md, api-reference.md (UpdateSession row), overview.md.
Large MCP tool outputs → files: >100K tokens → automatic offload to sandbox file; agent gets truncated preview + path. Plus: invalid vault credentials don't block sessions.create() — session.error event fires, auth retries on next idle→running. Both in tools.md.
* Point ant CLI install ref to live-sources.md (OSS has no anthropic-cli.md)
* Add Opus 4.8 model migration guide to claude-api skill
* Add prescriptive tool-description guidance for Opus 4.8 to claude-api skill
114 lines
2.9 KiB
Markdown
114 lines
2.9 KiB
Markdown
# Claude API — Ruby
|
|
|
|
> **Note:** The Ruby SDK supports the Claude API. A tool runner is available in beta via `client.beta.messages.tool_runner()`. Agent SDK is not yet available for Ruby.
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
gem install anthropic
|
|
```
|
|
|
|
## Client Initialization
|
|
|
|
```ruby
|
|
require "anthropic"
|
|
|
|
# Default (uses ANTHROPIC_API_KEY env var)
|
|
client = Anthropic::Client.new
|
|
|
|
# Explicit API key
|
|
client = Anthropic::Client.new(api_key: "your-api-key")
|
|
```
|
|
|
|
---
|
|
|
|
## Basic Message Request
|
|
|
|
```ruby
|
|
message = client.messages.create(
|
|
model: :"claude-opus-4-8",
|
|
max_tokens: 16000,
|
|
messages: [
|
|
{ role: "user", content: "What is the capital of France?" }
|
|
]
|
|
)
|
|
# content is an array of polymorphic block objects (TextBlock, ThinkingBlock,
|
|
# ToolUseBlock, ...). .type is a Symbol — compare with :text, not "text".
|
|
# .text raises NoMethodError on non-TextBlock entries.
|
|
message.content.each do |block|
|
|
puts block.text if block.type == :text
|
|
end
|
|
```
|
|
|
|
---
|
|
|
|
## Streaming
|
|
|
|
```ruby
|
|
stream = client.messages.stream(
|
|
model: :"claude-opus-4-8",
|
|
max_tokens: 64000,
|
|
messages: [{ role: "user", content: "Write a haiku" }]
|
|
)
|
|
|
|
stream.text.each { |text| print(text) }
|
|
```
|
|
|
|
---
|
|
|
|
## Tool Use
|
|
|
|
The Ruby SDK supports tool use via raw JSON schema definitions and also provides a beta tool runner for automatic tool execution.
|
|
|
|
### Tool Runner (Beta)
|
|
|
|
```ruby
|
|
class GetWeatherInput < Anthropic::BaseModel
|
|
required :location, String, doc: "City and state, e.g. San Francisco, CA"
|
|
end
|
|
|
|
class GetWeather < Anthropic::BaseTool
|
|
doc "Get the current weather for a location"
|
|
|
|
input_schema GetWeatherInput
|
|
|
|
def call(input)
|
|
"The weather in #{input.location} is sunny and 72°F."
|
|
end
|
|
end
|
|
|
|
client.beta.messages.tool_runner(
|
|
model: :"claude-opus-4-8",
|
|
max_tokens: 16000,
|
|
tools: [GetWeather.new],
|
|
messages: [{ role: "user", content: "What's the weather in San Francisco?" }]
|
|
).each_message do |message|
|
|
puts message.content
|
|
end
|
|
```
|
|
|
|
### Manual Loop
|
|
|
|
See the [shared tool use concepts](../shared/tool-use-concepts.md) for the tool definition format and agentic loop pattern.
|
|
|
|
---
|
|
|
|
## Prompt Caching
|
|
|
|
`system_:` (trailing underscore — avoids shadowing `Kernel#system`) takes an array of text blocks; set `cache_control` on the last block. Plain hashes work via the `OrHash` type alias. For placement patterns and the silent-invalidator audit checklist, see `shared/prompt-caching.md`.
|
|
|
|
```ruby
|
|
message = client.messages.create(
|
|
model: :"claude-opus-4-8",
|
|
max_tokens: 16000,
|
|
system_: [
|
|
{ type: "text", text: long_system_prompt, cache_control: { type: "ephemeral" } }
|
|
],
|
|
messages: [{ role: "user", content: "Summarize the key points" }]
|
|
)
|
|
```
|
|
|
|
For 1-hour TTL: `cache_control: { type: "ephemeral", ttl: "1h" }`. There's also a top-level `cache_control:` on `messages.create` that auto-places on the last cacheable block.
|
|
|
|
Verify hits via `message.usage.cache_creation_input_tokens` / `message.usage.cache_read_input_tokens`.
|