أداة Claude Advisor: قم بإقران منفذ سريع مع مخطط أكثر ذكاءً

لديك وكيل ترميز يقوم بتشغيل Sonnet. يتعامل مع 90% من المنعطفات دون بذل أي جهد: قراءة الملفات، إجراء الاختبارات، وكتابة النموذج المعياري. ولكن عندما يتعلق الأمر بقرار معماري غريب أو تزامن دقيق خطأ، كنت ترغب في أن تتمكن من الاتصال بصديق.

هذه هي أداة المستشار. تتيح ميزة واجهة برمجة التطبيقات التجريبية الجديدة من Anthropic نموذج منفذ أسرع (Sonnet أو Haiku) استدعاء نموذج مستشار الذكاء العالي (Opus) للجيل المتوسط. المستشار يقرأ النص كاملا ينتج خطة قصيرة أو تصحيح المسار، ويستمر المنفذ في المهمة. طلب API واحد، نموذجين بجودة قريبة من Opus بسعر Sonnet.

كيف تعمل أداة المستشار

عند إضافة أداة المستشار إلى ملفك tools المصفوفة، يقرر المنفذ متى يتم استدعاؤها، مثل أي أداة أخرى. التدفق:

1. يصدر المنفذ أ server_tool_use كتلة مع name: "advisor" وفارغة input.
2. يقوم Anthropic بتشغيل ممر استدلالي منفصل من جانب الخادم لنموذج المستشار، ويمرر النص الكامل للمنفذ (موجه النظام، وتعريفات الأداة، وجميع المنعطفات والنتائج السابقة).
3. يعود رد المستشار ك advisor_tool_result الكتلة (عادة من 400 إلى 700 رمز نصي).
4. ويواصل المنفذ التوليد، مستنيرًا بالنصيحة.

كل هذا يحدث داخل واحد /v1/messages طلب. لا توجد رحلات ذهابًا وإيابًا إضافية من جانبك. يعمل المستشار بدون أدوات وبدون إدارة السياق؛ يتم إسقاط كتل تفكيرها وفقط يصل نص النصيحة إلى منفذ التنفيذ.

أول اتصال للمستشار الخاص بك هو: curly وPython وTypeScript

أداة المستشار في مرحلة تجريبية. تشمل advisor-tool-2026-03-01 رأس بيتا في طلباتك. إليك أبسط مكالمة ممكنة:

حليقة

curl https://api.anthropic.com/v1/messages \\
  --header "x-api-key: \$ANTHROPIC_API_KEY" \\
  --header "anthropic-version: 2023-06-01" \\
  --header "anthropic-beta: advisor-tool-2026-03-01" \\
  --header "content-type: application/json" \\
  --data '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 4096,
    "tools": [
      {
        "type": "advisor_20260301",
        "name": "advisor",
        "model": "claude-opus-4-6"
      }
    ],
    "messages": [{
      "role": "user",
      "content": "Build a concurrent worker pool in Go with graceful shutdown."
    }]
  }'

بايثون

import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=4096,
    betas=["advisor-tool-2026-03-01"],
    tools=[
        {
            "type": "advisor_20260301",
            "name": "advisor",
            "model": "claude-opus-4-6",
        }
    ],
    messages=[
        {
            "role": "user",
            "content": "Build a concurrent worker pool in Go with graceful shutdown.",
        }
    ],
)

print(response)

تايب سكريبت

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const response = await client.beta.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 4096,
  betas: ["advisor-tool-2026-03-01"],
  tools: [
    {
      type: "advisor_20260301",
      name: "advisor",
      model: "claude-opus-4-6",
    },
  ],
  messages: [
    {
      role: "user",
      content: "Build a concurrent worker pool in Go with graceful shutdown.",
    },
  ],
});

console.log(response);

كيف يبدو الرد

ينتج عن استدعاء المستشار الناجح أربع كتل محتوى: النص الأولي للمنفذ، و server_tool_use كتلة، advisor_tool_result كتلة، والمنفذ الناتج النهائي على علم بالمشورة.

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Let me consult the advisor on this."
    },
    {
      "type": "server_tool_use",
      "id": "srvtoolu_abc123",
      "name": "advisor",
      "input": {}
    },
    {
      "type": "advisor_tool_result",
      "tool_use_id": "srvtoolu_abc123",
      "content": {
        "type": "advisor_result",
        "text": "Use a channel-based coordination pattern. Close the input channel first, then wait on a WaitGroup..."
      }
    },
    {
      "type": "text",
      "text": "Here's the implementation using a channel-based coordination pattern..."
    }
  ]
}

ال advisor_tool_result المحتوى له نوعان: advisor_result مع نص عادي نصيحة، و advisor_redacted_result مع المحتوى المشفر. في كلتا الحالتين، ذهابًا وإيابًا المحتوى حرفيًا في المنعطفات اللاحقة.

أزواج نماذج صالحة

يجب أن يكون المستشار على الأقل بنفس كفاءة المنفذ. أزواج غير صالحة ترجع أ 400 خطأ.

المكان المثالي لمعظم أعباء العمل: Sonnet كمنفذ، وOpus كمستشار. يمكنك الحصول على رفع الجودة في تكلفة إجمالية مماثلة أو أقل مقارنة بتشغيل Opus لكل رمز مميز.

محادثات متعددة المنعطفات

تمرير محتوى المساعد الكامل، بما في ذلك advisor_tool_result كتل، والعودة إلى API على المنعطفات اللاحقة. إذا قمت بحذف أداة المستشار من tools في منعطف للمتابعة بينما لا يزال سجل الرسائل يحتوي على advisor_tool_result الكتل، تقوم واجهة برمجة التطبيقات (API) بإرجاع أ 400.

import anthropic

client = anthropic.Anthropic()

tools = [
    {
        "type": "advisor_20260301",
        "name": "advisor",
        "model": "claude-opus-4-6",
    }
]

messages = [
    {
        "role": "user",
        "content": "Build a concurrent worker pool in Go with graceful shutdown.",
    }
]

# First turn: executor calls advisor, builds the worker pool
response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=4096,
    betas=["advisor-tool-2026-03-01"],
    tools=tools,
    messages=messages,
)

# Pass back the full response content (including advisor_tool_result blocks)
messages.append({"role": "assistant", "content": response.content})
messages.append({"role": "user", "content": "Now add a max-in-flight limit of 10."})

# Second turn: executor has context from first advisor call
response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=4096,
    betas=["advisor-tool-2026-03-01"],
    tools=tools,
    messages=messages,
)

الهندسة السريعة لوكلاء الترميز

تأتي أداة المستشار مع وصف مدمج يدفع المنفذ إلى الاتصال بها بالقرب من البداية من المهام المعقدة. بالنسبة لأحمال عمل الترميز والوكيل، يمكنك تحسين النتائج من خلال مطالبة النظام بذلك يعزز توقيتين:

• اتصال مبكر للمستشار الأول، بعد وجود بضع قراءات استكشافية في النص
• توجد مكالمة مستشار نهائية بعد كتابة الملف ومخرجات الاختبار في النص

إليك نمط موجه النظام الذي توصي به Anthropic لمهام البرمجة. أنتجت أعلى الذكاء بتكلفة قريبة من السوناتة في التقييمات الداخلية:

You have access to an \`advisor\` tool backed by a stronger reviewer model.
It takes NO parameters. When you call advisor(), your entire conversation
history is automatically forwarded.

Call advisor BEFORE substantive work: before writing, before committing
to an interpretation, before building on an assumption.

Also call advisor:
- When you believe the task is complete (save your deliverable first)
- When stuck: errors recurring, approach not converging
- When considering a change of approach

The advisor should respond in under 100 words and use enumerated steps,
not explanations.

الجمع مع الأدوات الأخرى

تتكون أداة المستشار من بحث الويب وتنفيذ التعليمات البرمجية وأدواتك المخصصة في نفس الوقت tools صفيف. يمكن للمنفذ البحث في الويب والاتصال بالمستشار واستخدام أدواتك فيه نفس المنعطف. يمكن لخطة المستشار أن تحدد الأدوات التي يصل إليها المنفذ بعد ذلك.

tools = [
    {
        "type": "web_search_20250305",
        "name": "web_search",
        "max_uses": 5,
    },
    {
        "type": "advisor_20260301",
        "name": "advisor",
        "model": "claude-opus-4-6",
    },
    {
        "name": "run_bash",
        "description": "Run a bash command",
        "input_schema": {
            "type": "object",
            "properties": {"command": {"type": "string"}},
        },
    },
]

مستشار التخزين المؤقت الفوري

تتوفر طبقتان مستقلتان للتخزين المؤقت. يعمل التخزين المؤقت من جانب المنفذ بنفس طريقة عمل أي كتلة محتوى: مكان أ cache_control نقطة توقف بعد advisor_tool_result ويضرب.

يحتفظ التخزين المؤقت من جانب المستشار بنسخة المستشار مخزنة مؤقتًا عبر المكالمات داخل نفس المحادثة. تمكينه مع أ caching الحقل الخاص بتعريف الأداة:

tools = [
    {
        "type": "advisor_20260301",
        "name": "advisor",
        "model": "claude-opus-4-6",
        "caching": {"type": "ephemeral", "ttl": "5m"},
    }
]

تكاليف الكتابة في ذاكرة التخزين المؤقت أكثر من عمليات القراءة التي يتم حفظها عند استدعاء المستشار مرتين أو أقل. ينقطع التخزين المؤقت حتى عند ثلاث مكالمات للمستشار تقريبًا ويتحسن من هناك. تمكينه لفترة طويلة حلقات الوكيل؛ يبقيه قبالة للمهام القصيرة.

تفاصيل الاستخدام والفواتير

يتم تشغيل مكالمات المستشار كاستدل فرعي منفصل تتم محاسبته بأسعار نموذج المستشار. ال usage.iterations تمنحك المصفوفة تفصيلاً لكل تكرار:

{
  "usage": {
    "input_tokens": 412,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 0,
    "output_tokens": 531,
    "iterations": [
      {
        "type": "message",
        "input_tokens": 412,
        "output_tokens": 89
      },
      {
        "type": "advisor_message",
        "model": "claude-opus-4-6",
        "input_tokens": 823,
        "output_tokens": 1612
      },
      {
        "type": "message",
        "input_tokens": 1348,
        "cache_read_input_tokens": 412,
        "output_tokens": 442
      }
    ]
  }
}

المستوى الأعلى usage تعكس الحقول الرموز المميزة للمنفذ فقط. التكرارات مع type: "advisor_message" تتم محاسبتها بأسعار نموذج المستشار. استخدم iterations المصفوفة عند بناء منطق تتبع التكلفة.

التحكم في التكاليف: وضع حد أقصى لمكالمات المستشار

لا تحتوي أداة المستشار على حد أقصى لمستوى المحادثة. يستخدم max_uses على الأداة تعريف حدود لكل طلب. بالنسبة لحدود مستوى المحادثة، قم بحساب المكالمات من جانب العميل و تجريد المستشار عندما تصل إلى السقف الخاص بك:

# Track advisor calls client-side
advisor_count = 0
MAX_ADVISOR_CALLS = 5

for turn in conversation:
    response = client.beta.messages.create(...)

    # Count advisor calls in response
    for block in response.content:
        if block.type == "server_tool_use" and block.name == "advisor":
            advisor_count += 1

    if advisor_count >= MAX_ADVISOR_CALLS:
        # Remove advisor tool and strip advisor_tool_result blocks
        tools = [t for t in tools if t.get("name") != "advisor"]
        for msg in messages:
            if msg["role"] == "assistant":
                msg["content"] = [
                    b for b in msg["content"]
                    if b.get("type") not in ("server_tool_use", "advisor_tool_result")
                    or b.get("name") != "advisor"
                ]

معالجة الأخطاء

إذا فشل استدعاء المستشار، فإن النتيجة تحمل رسالة advisor_tool_result_error مع error_code. يرى المنفذ الخطأ ويستمر دون نصيحة؛ الطلب في حد ذاته لا يفشل.

سلوك التدفق

لا يتم بث الاستدلال الفرعي للمستشار. يتوقف تدفق المنفذ مؤقتًا أثناء تشغيل المستشار، ثم الكامل advisor_tool_result يصل في واحدة content_block_start حدث. يتم تنشيط SSE ping كل 30 ثانية أثناء الإيقاف المؤقت. خطط لمدة 2 إلى 5 ثواني الصمت لكل مكالمة مستشار، اعتمادا على طول النص.

عندما يساعد المستشار (وعندما لا يساعد)

القيود التي يجب معرفتها

• لا يتم بث إخراج المستشار. توقع توقفًا مؤقتًا أثناء الاستدلال الفرعي.
• لا يوجد حد أقصى لمستوى المحادثة على مكالمات المستشار. تتبعهم وحدد لهم سقفًا من جانب العميل.
• max_tokens ينطبق على إخراج المنفذ فقط. لا يربط رموز المستشار.
• لا تمتد طبقة الأولوية على المنفذ إلى المستشار؛ كنت في حاجة إليها على كلا النموذجين.
• الميزة في مرحلة تجريبية. يشمل anthropic-beta: advisor-tool-2026-03-01 في كل طلب.