Mastering Claude Plugins & Skills for Agentic AI

# Python example using the Anthropic SDK (assuming client is initialized)
from anthropic import Anthropic

client = Anthropic(api_key="YOUR_ANTHROPIC_API_KEY")

def chat_with_tools(messages, tools):
    response = client.messages.create(
        model="claude-3-5-sonnet-20240620", # Or your preferred Claude model
        max_tokens=4096,
        messages=messages,
        tools=tools # Pass your tool definitions here
    )
    return response

# Example: Initial user message
user_message = "What's the current stock price of AAPL?"
messages = [{"role": "user", "content": user_message}]

# Define a dummy stock price tool for demonstration
stock_tool_definition = {
    "name": "get_stock_price",
    "description": "Retrieves the current stock price for a given ticker symbol.",
    "input_schema": {
        "type": "object",
        "properties": {
            "ticker_symbol": {
                "type": "string",
                "description": "The stock ticker symbol (e.g., AAPL, GOOGL)."
            }
        },
        "required": ["ticker_symbol"]
    }
}
tools = [stock_tool_definition]

first_response = chat_with_tools(messages, tools)

# Process the first response
if first_response.stop_reason == "tool_use":
    tool_use = first_response.content[0] # Assuming only one tool_use block for simplicity
    print(f"Claude wants to use tool: {tool_use.name} with arguments: {tool_use.input}")
    # In a real application, you would now execute the tool
    # For this example, let's simulate a tool result
    simulated_tool_output = {"price": 175.25, "currency": "USD"}

    # Prepare the tool_results message
    messages.append({"role": "assistant", "content": [tool_use]}) # Add Claude's tool_use to history
    messages.append({
        "role": "user",
        "content": [
            {
                "type": "tool_results",
                "tool_name": tool_use.name,
                "content": str(simulated_tool_output) # Tool results must be strings
            }
        ]
    })

    # Call Claude again with the tool results
    final_response = chat_with_tools(messages, tools)
    print(f"Final response from Claude: {final_response.content[0].text}")
else:
    print(f"Claude's initial response (no tool use): {first_response.content[0].text}")

# Python example for tool_choice
# ... (client and tool_definition from previous example) ...

# Option 1: Force Claude to use a specific tool
forced_tool_response = client.messages.create(
    model="claude-3-5-sonnet-20240620",
    max_tokens=4096,
    messages=[{"role": "user", "content": "Get me the stock price for Apple."}],
    tools=[stock_tool_definition],
    tool_choice={"type": "tool", "name": "get_stock_price"} # Force this tool
)
print(f"Forced tool use response stop reason: {forced_tool_response.stop_reason}")
# Expected: stop_reason should be "tool_use" with get_stock_price

# Option 2: Force Claude NOT to use any tool (respond directly)
no_tool_response = client.messages.create(
    model="claude-3-5-sonnet-20240620",
    max_tokens=4096,
    messages=[{"role": "user", "content": "What is the capital of France? Also, what's Apple's stock?"}],
    tools=[stock_tool_definition],
    tool_choice={"type": "none"} # Force no tool use
)
print(f"No tool use response stop reason: {no_tool_response.stop_reason}")
print(f"No tool use response content: {no_tool_response.content[0].text}")
# Expected: stop_reason should be "end_turn" and content will be a text response, ignoring the stock price query.

# Option 3: Let Claude decide (default behavior if tool_choice is omitted)
auto_tool_response = client.messages.create(
    model="claude-3-5-sonnet-20240620",
    max_tokens=4096,
    messages=[{"role": "user", "content": "What is the stock price of Google?"}],
    tools=[stock_tool_definition] # tool_choice defaults to {"type": "auto"}
)
print(f"Auto tool use response stop reason: {auto_tool_response.stop_reason}")
# Expected: stop_reason should be "tool_use" with get_stock_price

# Python example of a tool definition
custom_tool_schema = {
    "name": "create_calendar_event",
    "description": "Creates a new event in the user's calendar with a specified title, start time, and end time. Requires user confirmation.",
    "input_schema": {
        "type": "object",
        "properties": {
            "title": {
                "type": "string",
                "description": "The title or subject of the calendar event."
            },
            "start_time": {
                "type": "string",
                "format": "date-time",
                "description": "The start time of the event in ISO 8601 format (e.g., '2026-07-20T10:00:00Z')."
            },
            "end_time": {
                "type": "string",
                "format": "date-time",
                "description": "The end time of the event in ISO 8601 format (e.g., '2026-07-20T11:00:00Z')."
            },
            "attendees": {
                "type": "array",
                "items": {"type": "string", "format": "email"},
                "description": "Optional list of email addresses for attendees."
            }
        },
        "required": ["title", "start_time", "end_time"]
    }
}

# Python example of tool execution logic
from datetime import datetime
import json

def execute_create_calendar_event(title: str, start_time: str, end_time: str, attendees: list = None):
    """
    Simulates creating a calendar event.
    In a real application, this would interact with a calendar API (e.g., Google Calendar, Outlook).
    """
    try:
        # Basic validation
        start_dt = datetime.fromisoformat(start_time.replace('Z', '+00:00'))
        end_dt = datetime.fromisoformat(end_time.replace('Z', '+00:00'))
        if start_dt >= end_dt:
            return {"status": "error", "message": "Start time must be before end time."}

        print(f"--- Simulating Calendar Event Creation ---")
        print(f"Title: {title}")
        print(f"Start: {start_time}")
        print(f"End: {end_time}")
        print(f"Attendees: {attendees if attendees else 'None'}")
        print(f"------------------------------------------")

        # In a real scenario, this would be an API call
        # For now, simulate success
        event_id = f"event_{datetime.now().timestamp()}"
        return {"status": "success", "event_id": event_id, "title": title}

    except ValueError as e:
        return {"status": "error", "message": f"Invalid date/time format: {e}"}
    except Exception as e:
        return {"status": "error", "message": f"An unexpected error occurred: {e}"}

# A dispatcher to map tool names to functions
tool_functions = {
    "create_calendar_event": execute_create_calendar_event
}

# Python example of sending tool_results back to Claude
# ... (client, custom_tool_schema, tool_functions from previous examples) ...

# Initial conversation setup
messages = [
    {"role": "user", "content": "Please create a calendar event for a team meeting tomorrow from 10 AM to 11 AM, titled 'Project Alpha Sync'."}
]

# First API call - Claude will request tool use
response_1 = client.messages.create(
    model="claude-3-5-sonnet-20240620",
    max_tokens=4096,
    messages=messages,
    tools=[custom_tool_schema]
)

if response_1.stop_reason == "tool_use":
    tool_use_block = response_1.content[0]
    tool_name = tool_use_block.name
    tool_input = tool_use_block.input

    print(f"Claude requested tool: {tool_name} with input: {json.dumps(tool_input, indent=2)}")

    # Execute the tool
    if tool_name in tool_functions:
        tool_output = tool_functions[tool_name](**tool_input)
        print(f"Tool execution result: {json.dumps(tool_output, indent=2)}")

        # Add Claude's tool_use and our tool_results to the messages history
        messages.append({"role": "assistant", "content": [tool_use_block]})
        messages.append({
            "role": "user",
            "content": [
                {
                    "type": "tool_results",
                    "tool_name": tool_name,
                    "content": json.dumps(tool_output) # Must be a string
                }
            ]
        })

        # Second API call - Claude processes the results
        response_2 = client.messages.create(
            model="claude-3-5-sonnet-20240620",
            max_tokens=4096,
            messages=messages,
            tools=[custom_tool_schema] # Still provide tools, in case Claude needs to chain
        )
        print(f"Final response from Claude after tool execution: {response_2.content[0].text}")
    else:
        print(f"Error: Tool '{tool_name}' not found in dispatcher.")
        messages.append({"role": "assistant", "content": [tool_use_block]})
        messages.append({
            "role": "user",
            "content": [
                {
                    "type": "tool_results",
                    "tool_name": tool_name,
                    "content": json.dumps({"status": "error", "message": f"Tool '{tool_name}' not implemented."})
                }
            ]
        })
        response_2 = client.messages.create(
            model="claude-3-5-sonnet-20240620",
            max_tokens=4096,
            messages=messages,
            tools=[custom_tool_schema]
        )
        print(f"Error response from Claude: {response_2.content[0].text}")

else:
    print(f"Claude responded directly: {response_1.content[0].text}")

# Python example of an advanced system prompt
advanced_system_prompt = """
You are an advanced AI assistant designed to manage complex project workflows.
Your primary goal is to assist users by creating, updating, and retrieving information about projects and tasks using the available tools.
You operate in a multi-turn conversation and must maintain context.

Available Tools:
- `create_project(name: str, description: str, start_date: str, end_date: str)`: Creates a new project.
- `add_task_to_project(project_id: str, task_name: str, due_date: str)`: Adds a task to an existing project.
- `get_project_status(project_id: str)`: Retrieves the current status of a project.

Guidelines for Tool Usage:
1.  **Prioritize User Intent:** Always strive to fulfill the user's explicit request.
2.  **Information Gathering:** If a tool requires missing information, politely ask the user for clarification. Do NOT make assumptions.
3.  **Confirmation:** Before executing a creation or modification tool, always confirm the details with the user unless explicitly told not to.
4.  **Error Handling:** If a tool returns an error, inform the user clearly and suggest next steps. Do not retry automatically unless instructed.
5.  **Multi-step Tasks:** For requests involving multiple steps (e.g., "Create project X and add task Y"), break them down and execute tools sequentially.
6.  **Reporting:** After successful tool execution, provide a concise summary of the action taken and its outcome.
7.  **No Tool Use:** If a request does not require tool interaction, respond directly and informatively.
8.  **Ambiguity:** If a request is ambiguous, ask clarifying questions before attempting tool use.

Example Workflow:
User: "Create a new project called 'Website Redesign' due next month."
Assistant: "Okay, I can create the 'Website Redesign' project. What is the exact start date for this project? (e.g., YYYY-MM-DD)"
User: "Start it on 2026-08-01."
Assistant: "<tool_code>create_project(name='Website Redesign', description='User requested website redesign project.', start_date='2026-08-01', end_date='2026-09-01')</tool_code>"
... (after tool results) ...
Assistant: "The 'Website Redesign' project has been successfully created with ID [project_id]. Is there anything else I can help with?"

Your responses should be helpful, professional, and adhere strictly to these guidelines.
"""

# Python example demonstrating conversation state and tool chaining
# ... (client, advanced_system_prompt, and tool definitions from previous examples) ...

# Define additional tools for chaining
add_task_tool_schema = {
    "name": "add_task_to_project",
    "description": "Adds a task to an existing project.",
    "input_schema": {
        "type": "object",
        "properties": {
            "project_id": {"type": "string", "description": "The ID of the project."},
            "task_name": {"type": "string", "description": "The name of the task."},
            "due_date": {"type": "string", "format": "date", "description": "The due date of the task in YYYY-MM-DD format."}
        },
        "required": ["project_id", "task_name", "due_date"]
    }
}

get_status_tool_schema = {
    "name": "get_project_status",
    "description": "Retrieves the current status of a project.",
    "input_schema": {
        "type": "object",
        "properties": {
            "project_id": {"type": "string", "description": "The ID of the project."}
        },
        "required": ["project_id"]
    }
}

all_tools = [custom_tool_schema, add_task_tool_schema, get_status_tool_schema]

# Dummy implementations for new tools
project_db = {} # Simple in-memory storage for projects

def execute_create_project(name: str, description: str, start_date: str, end_date: str):
    project_id = f"proj_{len(project_db) + 1}"
    project_db[project_id] = {"name": name, "description": description, "start_date": start_date, "end_date": end_date, "tasks": [], "status": "active"}
    return {"status": "success", "project_id": project_id, "name": name}

def execute_add_task_to_project(project_id: str, task_name: str, due_date: str):
    if project_id not in project_db:
        return {"status": "error", "message": f"Project with ID {project_id} not found."}
    task_id = f"task_{len(project_db[project_id]['tasks']) + 1}"
    project_db[project_id]["tasks"].append({"id": task_id, "name": task_name, "due_date": due_date, "status": "pending"})
    return {"status": "success", "task_id": task_id, "task_name": task_name, "project_id": project_id}

def execute_get_project_status(project_id: str):
    if project_id not in project_db:
        return {"status": "error", "message": f"Project with ID {project_id} not found."}
    project = project_db[project_id]
    return {"status": "success", "project_id": project_id, "name": project["name"], "current_status": project["status"], "tasks_count": len(project["tasks"])}

tool_functions_dispatcher = {
    "create_calendar_event": execute_create_calendar_event, # from previous example
    "create_project": execute_create_project,
    "add_task_to_project": execute_add_task_to_project,
    "get_project_status": execute_get_project_status
}

# --- Main interaction loop for chaining ---
conversation_messages = [{"role": "user", "content": "Create a new project called 'Marketing Campaign' for Q4 2026, then add a task 'Launch Adverts' due 2026-10-15 to it. What's the project ID?"}]

current_project_id = None # To store state across turns

while True:
    print("\n--- Sending to Claude ---")
    response = client.messages.create(
        model="claude-3-5-sonnet-20240620",
        max_tokens=4096,
        messages=[{"role": "system", "content": advanced_system_prompt}] + conversation_messages,
        tools=all_tools
    )

    if response.stop_reason == "end_turn":
        print(f"Claude responded: {response.content[0].text}")
        conversation_messages.append({"role": "assistant", "content": response.content})
        break # Conversation ended

    elif response.stop_reason == "tool_use":
        tool_use_blocks = [block for block in response.content if block.type == "tool_use"]
        conversation_messages.append({"role": "assistant", "content": response.content}) # Add Claude's tool_use to history

        for tool_use_block in tool_use_blocks:
            tool_name = tool_use_block.name
            tool_input = tool_use_block.input

            print(f"Claude wants to use tool: {tool_name} with arguments: {json.dumps(tool_input)}")

            if tool_name in tool_functions_dispatcher:
                tool_output = tool_functions_dispatcher[tool_name](**tool_input)
                print(f"Tool '{tool_name}' executed. Output: {json.dumps(tool_output)}")

                # Update state if a project was created
                if tool_name == "create_project" and tool_output.get("status") == "success":
                    current_project_id = tool_output["project_id"]
                    print(f"Stored current_project_id: {current_project_id}")

                # If add_task_to_project was called and project_id was missing,
                # Claude might ask for it, or we might need to inject it if we have it
                if tool_name == "add_task_to_project" and "project_id" not in tool_input and current_project_id:
                     print(f"Injecting current_project_id {current_project_id} into add_task_to_project call.")
                     tool_input["project_id"] = current_project_id
                     tool_output = tool_functions_dispatcher[tool_name](**tool_input)
                     print(f"Tool '{tool_name}' re-executed with injected ID. Output: {json.dumps(tool_output)}")

                conversation_messages.append({
                    "role": "user",
                    "content": [
                        {
                            "type": "tool_results",
                            "tool_name": tool_name,
                            "content": json.dumps(tool_output)
                        }
                    ]
                })
            else:
                print(f"Error: Tool '{tool_name}' not implemented.")
                conversation_messages.append({
                    "role": "user",
                    "content": [
                        {
                            "type": "tool_results",
                            "tool_name": tool_name,
                            "content": json.dumps({"status": "error", "message": f"Tool '{tool_name}' not implemented."})
                        }
                    ]
                })
    else:
        print(f"Unexpected stop_reason: {response.stop_reason}")
        break

# Python example to demonstrate token usage with tools
# ... (client, stock_tool_definition from previous examples) ...

# Short tool definition, short prompt, short output
messages_short = [{"role": "user", "content": "What is AAPL stock?"}]
tools_short = [stock_tool_definition]

response_short = client.messages.create(
    model="claude-3-5-sonnet-20240620",
    max_tokens=4096,
    messages=messages_short,
    tools=tools_short
)

print(f"Short interaction token usage: {response_short.usage}")
# Expected output might be something like: usage=Usage(input_tokens=~100, output_tokens=~20)

# Simulate tool execution and send results back
if response_short.stop_reason == "tool_use":
    tool_use = response_short.content[0]
    simulated_output = {"price": 175.50}
    messages_short.append({"role": "assistant", "content": [tool_use]})
    messages_short.append({
        "role": "user",
        "content": [
            {
                "type": "tool_results",
                "tool_name": tool_use.name,
                "content": json.dumps(simulated_output)
            }
        ]
    })
    response_final_short = client.messages.create(
        model="claude-3-5-sonnet-20240620",
        max_tokens=4096,
        messages=messages_short,
        tools=tools_short
    )
    print(f"Final short interaction token usage (turn 2): {response_final_short.usage}")
    # Note how input_tokens for the second turn include the entire history and tool results.

# Python example for measuring latency
import time
# ... (client, stock_tool_definition, and a dummy execute_stock_price function) ...

def execute_get_stock_price(ticker_symbol: str):
    time.sleep(0.5) # Simulate a 500ms API call to an external stock service
    return {"price": 175.25, "currency": "USD"}

tool_functions_latency_test = {
    "get_stock_price": execute_get_stock_price
}

def run_latency_test():
    start_total = time.time()
    messages_latency = [{"role": "user", "content": "What's the stock price of NVDA?"}]
    tools_latency = [stock_tool_definition]

    start_claude_1 = time.time()
    response_1 = client.messages.create(
        model="claude-3-5-sonnet-20240620",
        max_tokens=4096,
        messages=messages_latency,
        tools=tools_latency
    )
    end_claude_1 = time.time()
    print(f"Claude turn 1 (tool_use) latency: {end_claude_1 - start_claude_1:.2f}s")

    if response_1.stop_reason == "tool_use":
        tool_use = response_1.content[0]
        messages_latency.append({"role": "assistant", "content": [tool_use]})

        start_tool_exec = time.time()
        tool_output = tool_functions_latency_test[tool_use.name](**tool_use.input)
        end_tool_exec = time.time()
        print(f"Tool execution latency: {end_tool_exec - start_tool_exec:.2f}s")

        messages_latency.append({
            "role": "user",
            "content": [
                {
                    "type": "tool_results",
                    "tool_name": tool_use.name,
                    "content": json.dumps(tool_output)
                }
            ]
        })

        start_claude_2 = time.time()
        response_2 = client.messages.create(
            model="claude-3-5-sonnet-20240620",
            max_tokens=4096,
            messages=messages_latency,
            tools=tools_latency
        )
        end_claude_2 = time.time()
        print(f"Claude turn 2 (tool_results) latency: {end_claude_2 - start_claude_2:.2f}s")

    end_total = time.time()
    print(f"Total end-to-end latency: {end_total - start_total:.2f}s")

run_latency_test()