agentbyte 0.3.0__tar.gz → 0.3.2__tar.gz

agentbyte-0.3.2/.github/skills/agentbyte-agent-as-tool/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: agentbyte-agent-as-tool
+description: Guide for the Orchestrator-Specialist pattern. Use this to wrap an Agentbyte agent as a tool that can be executed by another coordinator agent.
+---
+
+Use this skill when building complex agentic teams or delegated workflows.
+
+## Pattern: AgentAsTool
+```python
+from agentbyte.agents import Agent
+from agentbyte.agents.agent_as_tool import AgentAsTool
+
+# 1. Define specialist agent
+research_agent = Agent(
+    name="researcher",
+    description="Research-focused specialist that queries for data.",
+    instructions="Research the topic provided and return a summary.",
+    model_client=client
+)
+
+# 2. Wrap as a tool
+research_tool = AgentAsTool(research_agent)
+
+# 3. Add to coordinator agent
+coordinator = Agent(
+    name="manager",
+    description="Orchestrates task execution by delegating to researcher.",
+    model_client=client,
+    tools=[research_tool] # Coordinator sees researcher as a tool
+)
+
+response = await coordinator.run("Tell me about the history of solar panels.")
+```
+
+## Key Benefits
+- **Specialization:** Specialists have their own instructions, tools, and model client settings.
+- **Isolation:** Coordinator only sees the task input/output, keeping context windows cleaner.
+
+## Guardrails
+- **Naming:** The name of the `AgentAsTool` must be unique in the coordinator's tool list.
+- **Description:** Provide a very clear `description` for the specialist agent; that description is what the coordinator sees to decide when to invoke it.

agentbyte-0.3.2/.github/skills/agentbyte-dataset/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: agentbyte-dataset
+description: Guide for creating and using Agentbyte datasets with SQLite or JSON backends. Use this when asked to load datasets, create dataset structures, or work with schema-driven data loading.
+---
+
+Use this skill when you need to:
+- **Load** an existing dataset using `load_dataset()`
+- **Create** a new dataset with config.json, schema.json, and data.json
+- **Query** SQLite datasets with SQL or iterate JSON datasets
+- **Display** dataset schemas in pretty or raw format
+- **Work with** multiple data engines (SQLite for structured, JSON for semi-structured)
+
+## Dataset Architecture
+
+Agentbyte datasets are file-based and engine-agnostic. Each dataset lives in `data/samples/{category}/{name}/` with three files:
+
+### File Structure
+```
+data/samples/{category}/{name}/
+├── config.json      # Engine, table name, in-memory flag, description
+├── schema.json      # Column definitions (name, type, SQL constraints)
+└── data.json        # Records only ({"records": [...]})
+```
+
+### Supported Engines
+- **sqlite** (default): Structured data with SQL queries, strict schema, constraints
+- **json**: Semi-structured data, flexible JSON format, inferred schema
+- **Future**: duckdb, lance, qdrant
+
+## Creating a Dataset
+
+### 1. Create Directory
+```python
+from pathlib import Path
+
+dataset_dir = Path("data/samples/mydata/mydataset")
+dataset_dir.mkdir(parents=True, exist_ok=True)
+```
+
+### 2. Write config.json
+Define engine, table name, and metadata:
+```python
+import json
+
+config = {
+    "engine": "sqlite",           # "sqlite" or "json"
+    "table_name": "my_table",     # SQL table name (SQLite only)
+    "in_memory": True,            # Use in-memory storage
+    "description": "My dataset"   # Optional description
+}
+
+with open(dataset_dir / "config.json", "w") as f:
+    json.dump(config, f, indent=2)
+```
+
+### 3. Write schema.json (SQLite Only)
+List of column definitions with types and constraints:
+```python
+schema = [
+    {"name": "id", "type": "TEXT", "primary_key": True, "not_null": True},
+    {"name": "name", "type": "TEXT", "not_null": True},
+    {"name": "value", "type": "REAL"},
+    {"name": "status", "type": "TEXT"}
+]
+
+with open(dataset_dir / "schema.json", "w") as f:
+    json.dump(schema, f, indent=2)
+```
+
+**SQLite Column Constraints (all optional):**
+- `primary_key` (bool): Is PRIMARY KEY
+- `not_null` (bool): Is NOT NULL
+- `unique` (bool): Is UNIQUE
+- All other fields ignored for JSON datasets (schema is inferred from data)
+
+### 4. Write data.json
+Records only; schema is separate:
+```python
+data = {
+    "records": [
+        {"id": "001", "name": "Item 1", "value": 100.0, "status": "active"},
+        {"id": "002", "name": "Item 2", "value": 200.0, "status": "inactive"},
+        {"id": "003", "name": "Item 3", "value": 150.0, "status": "active"}
+    ]
+}
+
+with open(dataset_dir / "data.json", "w") as f:
+    json.dump(data, f, indent=2)
+```
+
+## Using Datasets
+
+### Load a Dataset
+```python
+from agentbyte.dataset import load_dataset
+
+ds = load_dataset("category/name")  # Returns SQLiteDataset or JSONDataset
+print(ds.engine)        # "sqlite" or "json"
+print(ds.table_name)    # Table/collection name
+```
+
+### Connect & Get Data
+
+**SQLite Dataset:**
+```python
+conn = ds.connect()  # Returns sqlite3.Connection
+rows = conn.execute("SELECT * FROM my_table").fetchall()
+for row in rows:
+    print(dict(row))  # Convert sqlite3.Row to dict
+```
+
+**JSON Dataset:**
+```python
+data = ds.connect()  # Returns dict with {"records": [...]}
+for record in data.get("records", []):
+    print(record)
+```
+
+### Display Schema
+
+Both datasets support schema inspection:
+```python
+# Pretty format (default) - shows column names, types, constraints
+ds.schema.show()
+
+# Raw format - list of column dicts
+from agentbyte.dataset import SchemaFormat
+ds.schema.show(format=SchemaFormat.RAW)
+```
+
+**SQLite Only:** SqliteSchema has `.to_create_table_sql()` and `.get_column_names()` methods.
+
+## Examples
+
+### Example 1: Load & Query Existing SQLite Dataset
+```python
+from agentbyte.dataset import load_dataset
+
+ds = load_dataset("contracts/asmd")
+conn = ds.connect()
+
+# Display schema
+ds.schema.show()
+
+# Query
+active = conn.execute(
+    "SELECT id, name FROM contracts_asmd WHERE status='active'"
+).fetchall()
+
+for row in active:
+    print(dict(row))
+```
+
+### Example 2: Load & Iterate JSON Dataset
+```python
+ds = load_dataset("documents/wiki")  # engine="json" in config
+data = ds.connect()  # dict with {"records": [...]}
+
+for i, record in enumerate(data["records"], 1):
+    print(f"{i}. {record['title']}: {record['url']}")
+```
+
+### Example 3: Create Dataset Programmatically
+See "Creating a Dataset" section above for step-by-step code.
+
+## Guardrails
+
+- **Do** use relative paths from project root in `load_dataset()` (e.g., `"contracts/asmd"`, not full file paths).
+- **Do** keep schema.json separate from data.json for clarity and reusability.
+- **Do** use `dict(row)` to convert sqlite3.Row objects to dicts for JSON serialization.
+- **Do** call `ds.connect()` only once; it caches the connection and schema on first call.
+- **Don't** hard-code values in datasets (use config.json for metadata).
+- **Don't** forget `.json` extensions for all three files.
+- **Don't** put schema definitions inside data.json (separate files for clarity).
+- **Don't** assume JSON datasets support SQL—use dict iteration instead.
+
+## API Reference
+
+### Factory Function
+```python
+load_dataset(dataset_id: str) -> BaseDataset
+```
+Loads dataset from `data/samples/{category}/{name}/`. Returns `SQLiteDataset` or `JSONDataset` based on config.engine.
+
+### Classes (Generic)
+- **Column**: name (str), type (str)
+- **Schema**: columns (list[Column])
+- **DataRecord**: id (str), data (Any), metadata (dict)
+- **DatasetConfig**: engine (str), table_name (str), in_memory (bool), description (str)
+- **SchemaFormat**: RAW or PRETTY enum for display formats
+
+### Classes (SQLite-Specific)
+- **SqliteColumn**: Extends Column; adds primary_key, not_null, unique; method `to_sql_def()`
+- **SqliteSchema**: Extends Schema; methods `to_create_table_sql()`, `get_column_names()`, `show(format)`
+- **SQLiteDataset**: Implements BaseDataset; properties: engine, table_name, schema, in_memory
+
+### Classes (JSON-Specific)
+- **JSONDataset**: Implements BaseDataset; properties: engine, table_name, schema (inferred)
+
+## Troubleshooting
+
+| Issue | Fix |
+|-------|-----|
+| `FileNotFoundError: Schema file not found` | Ensure `schema.json` exists in dataset directory |
+| `FileNotFoundError: Data file not found` | Ensure `data.json` exists in dataset directory |
+| `KeyError: 'records'` | data.json must have `{"records": [...]}` structure |
+| `sqlite3.Row has no .dict() method` | Use `dict(row)` instead of `row.dict()` |
+| Notebook paths fail in `load_dataset()` | Use relative paths from project root; notebook working directory is handled by loader |

agentbyte-0.3.2/.github/skills/agentbyte-function-tools/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: agentbyte-function-tools
+description: Guide for creating Agentbyte FunctionTools from Python functions or using the @tool decorator. Use this when defining agent capabilities, configuring ToolResult objects, or setting tool ApprovalMode.
+---
+
+Use this skill when defining tools that an Agentbyte agent can execute.
+
+## Patterns
+
+### 1. Using the `@tool` decorator (Recommended for simple functions)
+```python
+from agentbyte.tools import tool
+
+@tool
+def get_weather(city: str) -> str:
+    """Get the current weather for a city."""
+    return f"Weather in {city}: 25°C, Sunny"
+```
+
+### 2. Manual `FunctionTool` wrapping
+```python
+from agentbyte.tools import FunctionTool, ApprovalMode
+
+def calculate_tax(amount: float) -> float:
+    return amount * 0.15
+
+# Manually wrapping with a description and approval mode
+tax_tool = FunctionTool(
+    calculate_tax,
+    description="Calculate the 15% regional tax for a given amount.",
+    approval_mode=ApprovalMode.ALWAYS  # Triggers explicit human-in-the-loop approval
+)
+```
+
+## ToolResult usage
+Returning structured data from tools:
+```python
+from agentbyte.types import ToolResult
+
+def complex_operation():
+    return ToolResult(content="Operation summary", metadata={"id": 123})
+```
+
+## Guardrails
+- **Docstrings:** Always provide clear docstrings for tool functions; these are sent to the LLM as the tool description.
+- **Imports:** Import from `agentbyte.tools` or `agentbyte.types`.
+- **Statelessness:** Tools should ideally be stateless or operate on resources provided via arguments.

agentbyte-0.3.2/.github/skills/agentbyte-list-memory/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: agentbyte-list-memory
+description: Guide for adding persistent memory to Agentbyte agents using ListMemory. Use this when you want agents to store, retrieve, and learn from cross-interaction knowledge.
+---
+
+Use this skill when implementing local, in-memory knowledge stores for agents.
+
+## Pattern: ListMemory Usage
+```python
+from agentbyte.memory import ListMemory, MemoryContent
+from agentbyte.agents import Agent
+
+# 1. Initialize local memory
+user_memory = ListMemory()
+
+# 2. Pre-load knowledge (if needed)
+user_memory.add(MemoryContent(content="The user likes coffee and uses Python 3.13."))
+
+# 3. Attach to agent
+agent = Agent(
+    name="concierge",
+    memory=user_memory,
+    ...
+)
+
+# 4. First turn: Agent 'learns' from the context
+response = await agent.run("What is my favorite language?")
+print(response.messages[-1].content) # "You use Python 3.13."
+```
+
+## Advanced Memory: OperationRecorder
+To allow agents to **write** to their own memory during a run, add the recorder middleware:
+```python
+from agentbyte.middleware import OperationRecorderMiddleware
+
+agent = Agent(
+    ...,
+    memory=user_memory,
+    middlewares=[OperationRecorderMiddleware()]
+)
+```
+
+## Guardrails
+- **In-Memory:** `ListMemory` is not persisted to disk by default.
+- **System Prompt:** Memory is automatically injected into the agent's system prompt instructions.
+- **Context vs Memory:** `AgentContext` threads messages (short-term); `Memory` stores facts (long-term).

agentbyte-0.3.2/.github/skills/agentbyte-llm-client/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: agentbyte-llm-client
+description: Guide for initializing Agentbyte agents with OpenAI and Azure OpenAI clients. Use this when asked to set up LLM clients, configure authentication (API keys, certificates, Managed Identity), or implement Dependency Injection for model clients.
+---
+
+Use this skill when a user needs to initialize an `OpenAIChatCompletionClient` or `AzureOpenAIChatCompletionClient`, select an authentication path, or configure LLM parameters.
+
+## Core Patterns
+
+### 1. OpenAI Client Initialization
+Canonical source: `notebooks/concepts/agent/02b-openai-wrapper.ipynb`
+
+#### Method A: Env-based factory (Recommended for simple setup)
+```python
+from agentbyte.llm.openai import OpenAIChatCompletionClient
+
+# Automatically reads OPENAI_API_KEY from environment
+model_client = OpenAIChatCompletionClient.from_api_key(
+    model="gpt-4o",
+    config={"max_completion_tokens": 500}
+)
+```
+
+#### Method B: Direct Dependency Injection (For advanced SDK control)
+```python
+import os
+from openai import AsyncOpenAI
+from agentbyte.llm.openai import OpenAIChatCompletionClient
+
+raw_client = AsyncOpenAI(api_key=os.environ["OPENAI_API_KEY"], timeout=30.0)
+model_client = OpenAIChatCompletionClient(model="gpt-4o", client=raw_client)
+```
+
+### 2. Azure OpenAI Client Initialization
+Canonical source: `notebooks/concepts/agent/02a-azure-openai-wrapper.ipynb`
+
+#### Method A: Managed Identity (Recommended for Azure-hosted production)
+```python
+from agentbyte.llm.azure_openai import AzureOpenAIChatCompletionClient
+
+model_client = AzureOpenAIChatCompletionClient.from_default_credential(
+    model="gpt-4o-mini"
+)
+```
+
+#### Method B: Certificate Auth (Service Principal)
+```python
+import os
+from agentbyte.llm.azure_openai import AzureOpenAIChatCompletionClient
+
+model_client = AzureOpenAIChatCompletionClient.from_certificate(
+    model="gpt-4o-mini",
+    tenant_id=os.environ["AZURE_TENANT_ID"],
+    client_id=os.environ["AZURE_CLIENT_ID"],
+    certificate_data=os.environ["AZURE_CERT_DATA"]
+)
+```
+
+## Guardrails
+- **Environment Loading:** Always use `load_dotenv(find_dotenv(), override=True)` before initializing clients in scripts or notebooks.
+- **Client Reuse:** Prefer creating one `model_client` and passing it to multiple agents rather than re-initializing for every agent.
+- **Factory vs. Constructor:** Use factory methods (`from_api_key`, `from_certificate`) for standard auth. Use the constructor only if you need to inject a custom-configured `AsyncOpenAI` or `AsyncAzureOpenAI` instance.
+- **Config Dict:** LLM parameters like `temperature`, `max_completion_tokens`, or `seed` should be passed via the `config` dictionary.

agentbyte-0.3.2/.github/skills/agentbyte-memory-tool/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: agentbyte-memory-tool
+description: Guide for sandboxed file-system operations in Agentbyte memory. Use this when agents need to read, write, and modify files in a safe project environment.
+---
+
+Use this skill when your agent needs to persist structured data or documents in a sandbox.
+
+## Pattern: MemoryTool and Backend
+```python
+from agentbyte.tools.memory_tool import MemoryTool, MemoryBackend
+from agentbyte.agents import Agent
+
+# 1. Initialize backend (sandboxed or direct)
+backend = MemoryBackend(root_dir="agent_knowledge_base", sandbox=True)
+
+# 2. Initialize the tool
+memory_tool = MemoryTool(memory_backend=backend)
+
+# 3. Register as a tool
+agent = Agent(
+    name="knowledge-agent",
+    model_client=client,
+    tools=[memory_tool] # Agent gets 'create', 'view', 'str_replace', 'insert' commands
+)
+
+await agent.run("Create a file called 'notes.txt' with the text 'Hello World'.")
+```
+
+## Available Operations
+- `create`: Create a new file with initial content.
+- `view`: Read part or all of a file.
+- `str_replace`: Change exact strings within a file.
+- `insert`: Add content at a specific line.
+- `delete`: Remove a file or directory.
+
+## Guardrails
+- **Sandbox:** Always use `sandbox=True` for agent-facing file operations to prevent path transversal.
+- **Root Dir:** Ensure the `root_dir` exists or the backend has permissions to create it.
+- **Context:** `MemoryTool` is meant for long-term file storage, separate from conversation history.

agentbyte-0.3.2/.github/skills/agentbyte-middleware/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: agentbyte-middleware
+description: Guide for adding middleware chains to Agentbyte agents. Use this for logging, guardrails, PII redaction, usage tracking, or custom pre/post run logic.
+---
+
+Use this skill when you need to intercept agent execution.
+
+## Pattern: Custom Middleware
+```python
+from agentbyte.middleware import BaseMiddleware, MiddlewareContext
+from agentbyte.messages import Message
+
+class MyLogger(BaseMiddleware):
+    async def before_run(self, context: MiddlewareContext):
+        print(f"Starting agent: {context.agent_name}")
+
+    async def after_run(self, context: MiddlewareContext, response: list[Message]):
+        print(f"Finished agent: {context.agent_name}")
+
+agent = Agent(
+    ...,
+    middlewares=[MyLogger()]
+)
+```
+
+## Built-in Middlewares
+- `LoggingMiddleware`: Outputs detailed step logic.
+- `GuardrailMiddleware`: Enforces constraints on responses.
+- `PIIRedactionMiddleware`: Automatically masks sensitive patterns.
+- `RateLimitMiddleware`: Prevents LLM client flooding.
+
+## Guardrails
+- **Execution Order:** Middlewares execute in the list order.
+- **Error Handling:** Use `on_error` implementation in the middleware to handle exceptions in the pipeline.
+- **Context:** Use `MiddlewareContext` to pass information between `before_run` and `after_run`.

agentbyte-0.3.2/.github/skills/agentbyte-multi-turn-context/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: agentbyte-multi-turn-context
+description: Guide for managing Agentbyte multi-turn conversations using a caller-owned AgentContext. Use this when implementing stateful chats, threading conversation history, or isolating user sessions.
+---
+
+Use this skill when building conversational agents that need to remember previous turns.
+
+## Pattern: Context Threading
+```python
+from agentbyte.context import AgentContext
+from agentbyte.agents import Agent
+
+# 1. Create caller-owned context
+session_context = AgentContext(metadata={"session_id": "user-123"})
+
+agent = Agent(name="chat-bot", ...)
+
+# 2. First Turn
+response1 = await agent.run("Hi, I am Alex", context=session_context)
+
+# 3. Second Turn (Re-pass the context from the response)
+response2 = await agent.run("What is my name?", context=response1.context)
+
+print(response2.messages[-1].content) # "Your name is Alex"
+```
+
+## Key Attributes
+- **`context.messages`**: Access the conversation history.
+- **`context.metadata`**: Dictionary of custom data carried across turns.
+
+## Guardrails
+- **Stateless Agents:** Never store conversation history on the `Agent` object itself.
+- **Context Ownership:** The application caller is responsible for persisting and passing the `AgentContext`.
+- **Model Client vs Context:** `AgentContext` stores messages; `model_client` handles the LLM API calls.

agentbyte-0.3.2/.github/skills/agentbyte-otel-tracing/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: agentbyte-otel-tracing
+description: Guide for enabling OpenTelemetry (OTel) instrumentation in Agentbyte. Use this when connecting agents to Jaeger, tracing LLM calls, or aggregating multi-turn token metrics.
+---
+
+Use this skill to add observability to your agents.
+
+## Pattern 1: Automatic Instrumentation
+```python
+import os
+# MUST occur before any agentbyte imports
+os.environ["AGENTBYTE_ENABLE_OTEL"] = "true"
+os.environ["OTEL_EXPORTER_OTLP_ENDPOINT"] = "http://localhost:4318"
+os.environ["OTEL_SERVICE_NAME"] = "my-agent-service"
+
+from agentbyte.middleware import auto_instrument
+auto_instrument()
+
+# Agents will now automatically create traces in Jaeger
+```
+
+## Pattern 2: Manual Instrumentation
+```python
+from agentbyte.middleware import OTelMiddleware
+
+agent = Agent(
+    name="my-traced-agent",
+    ...,
+    middlewares=[OTelMiddleware()]
+)
+```
+
+## Environment Config
+| Variable | Purpose |
+|---|---|
+| `AGENTBYTE_OTEL_CAPTURE_CONTENT` | Capture full message text in spans |
+| `AGENTBYTE_OTEL_CAPTURE_USAGE` | Aggregate tokens, calls, and cost in root span |
+
+## Guardrails
+- **Import Order:** Ensure OTel environment variables are set before the first `agentbyte` import.
+- **Jaeger:** Ensure your OTLP collector endpoint is active.
+- **PII:** Be careful with `AGENTBYTE_OTEL_CAPTURE_CONTENT` in production environments.

agentbyte-0.3.2/.github/skills/agentbyte-simple-agent/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: agentbyte-simple-agent
+description: Guide for creating basic Agentbyte agents for simple reasoning, tool use, and structured output. Use this when starting an agent project or setting up agents for single reasoning turns without complex state.
+---
+
+Use this skill when initializing the core reasoning agent in Agentbyte.
+
+## Patterns
+
+### 1. Simple Reasoning Agent
+```python
+from agentbyte.agents import Agent
+from agentbyte.llm.openai import OpenAIChatCompletionClient
+
+client = OpenAIChatCompletionClient.from_api_key(model="gpt-4o-mini")
+
+simple_agent = Agent(
+    name="concierge",
+    description="A helpful assistant that answers user questions clearly.",
+    instructions="You are a concierge. Be brief and professional.",
+    model_client=client
+)
+
+result = await simple_agent.run("What is the time in London?")
+print(result.messages[-1].content)
+```
+
+### 2. Structured Output Agent (Pydantic)
+```python
+from pydantic import BaseModel
+from agentbyte.agents import Agent
+
+class ProductReview(BaseModel):
+    score: int
+    summary: str
+
+review_agent = Agent(
+    name="reviewer",
+    description="Extracts structured reviews from customer feedback.",
+    instructions="Analyze the text and provide score (1-5) and summary.",
+    model_client=client,
+    output_format=ProductReview  # Enforces Pydantic model response
+)
+```
+
+## Guardrails
+- **Required Fields:** Always include `name`, `description`, and `instructions` in the `Agent` constructor.
+- **Streaming:** Use `await agent.run_stream(...)` to access incremental message chunks.
+- **Model Client:** Always pass a `model_client` (instantiated from `agentbyte.llm`).

agentbyte-0.3.2/.github/skills/agentbyte-tool-approval/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: agentbyte-tool-approval
+description: Guide for implementing Human-in-the-Loop workflows in Agentbyte. Use this for pausing execution on sensitive tool calls, inspecting pending requests, and resuming after approval.
+---
+
+Use this skill for high-risk operations where you need manual oversight.
+
+## Pattern: Approval Workflow
+
+### 1. Set Approval Mode on the Tool
+```python
+from agentbyte.tools import FunctionTool, ApprovalMode
+
+risky_tool = FunctionTool(
+    process_payment,
+    description="Processes sensitive payments.",
+    approval_mode=ApprovalMode.ALWAYS # Force pause
+)
+```
+
+### 2. Handle the Pause in the Orchestrator
+```python
+response = await agent.run("Charge $50 to my account.", context=context)
+
+if response.status == "approval_needed":
+    # 3. Inspect pending requests in the context
+    pending = context.pending_approval_requests[0]
+    print(f"Approving call to: {pending.tool_name}")
+
+    # 4. Approve and re-run
+    context.approve_tool(pending.call_id)
+    final_response = await agent.run(action=None, context=context)
+```
+
+## Key Statuses
+- **`response.status`**: Check for `"approval_needed"`.
+- **`context.approve_tool(call_id)`**: Marks the tool call for execution.
+
+## Guardrails
+- **Context Threading:** You **must** pass the same `AgentContext` object between the first run and the approved run.
+- **Metadata:** Use `context.pending_approval_requests` to see the actual tool parameters before deciding to approve.