10xscale-agentflow-cli 0.3.0__tar.gz → 0.3.1__tar.gz

{10xscale_agentflow_cli-0.3.0 → 10xscale_agentflow_cli-0.3.1}/10xscale_agentflow_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: 10xscale-agentflow-cli
-Version: 0.3.0
+Version: 0.3.1
 Summary: CLI and API for 10xscale AgentFlow
 Author-email: 10xscale <contact@10xscale.ai>
 Maintainer-email: Shudipto Trafder <shudiptotrafder@gmail.com>

{10xscale_agentflow_cli-0.3.0 → 10xscale_agentflow_cli-0.3.1}/10xscale_agentflow_cli.egg-info/SOURCES.txt

@@ -22,6 +22,7 @@ agentflow_cli/cli/commands/__init__.py
 agentflow_cli/cli/commands/api.py
 agentflow_cli/cli/commands/build.py
 agentflow_cli/cli/commands/init.py
+agentflow_cli/cli/commands/skills.py
 agentflow_cli/cli/commands/version.py
 agentflow_cli/cli/core/__init__.py
 agentflow_cli/cli/core/config.py
@@ -29,6 +30,36 @@ agentflow_cli/cli/core/output.py
 agentflow_cli/cli/core/validation.py
 agentflow_cli/cli/templates/__init__.py
 agentflow_cli/cli/templates/defaults.py
+agentflow_cli/cli/templates/skills/agent-skills/SKILL.md
+agentflow_cli/cli/templates/skills/agent-skills/references/agents-and-tools.md
+agentflow_cli/cli/templates/skills/agent-skills/references/api-client.md
+agentflow_cli/cli/templates/skills/agent-skills/references/api-configuration.md
+agentflow_cli/cli/templates/skills/agent-skills/references/api-settings-and-middleware.md
+agentflow_cli/cli/templates/skills/agent-skills/references/architecture.md
+agentflow_cli/cli/templates/skills/agent-skills/references/auth-and-authorization.md
+agentflow_cli/cli/templates/skills/agent-skills/references/callbacks-and-command.md
+agentflow_cli/cli/templates/skills/agent-skills/references/checkpointing-and-threads.md
+agentflow_cli/cli/templates/skills/agent-skills/references/cli-commands.md
+agentflow_cli/cli/templates/skills/agent-skills/references/client-auth-and-errors.md
+agentflow_cli/cli/templates/skills/agent-skills/references/client-messages-invoke-stream.md
+agentflow_cli/cli/templates/skills/agent-skills/references/client-threads-memory-files.md
+agentflow_cli/cli/templates/skills/agent-skills/references/context-id-background.md
+agentflow_cli/cli/templates/skills/agent-skills/references/dependency-injection.md
+agentflow_cli/cli/templates/skills/agent-skills/references/id-and-thread-name-generators.md
+agentflow_cli/cli/templates/skills/agent-skills/references/media-and-files.md
+agentflow_cli/cli/templates/skills/agent-skills/references/memory-and-store.md
+agentflow_cli/cli/templates/skills/agent-skills/references/prebuilt-agents-and-tools.md
+agentflow_cli/cli/templates/skills/agent-skills/references/production-runtime.md
+agentflow_cli/cli/templates/skills/agent-skills/references/providers-and-adapters.md
+agentflow_cli/cli/templates/skills/agent-skills/references/publishers-and-runtime-protocols.md
+agentflow_cli/cli/templates/skills/agent-skills/references/remote-tools.md
+agentflow_cli/cli/templates/skills/agent-skills/references/rest-api-and-errors.md
+agentflow_cli/cli/templates/skills/agent-skills/references/security-and-validators.md
+agentflow_cli/cli/templates/skills/agent-skills/references/state-and-messages.md
+agentflow_cli/cli/templates/skills/agent-skills/references/state-graph.md
+agentflow_cli/cli/templates/skills/agent-skills/references/streaming.md
+agentflow_cli/cli/templates/skills/agent-skills/references/testing-and-evaluation.md
+agentflow_cli/cli/templates/skills/copilot/agentflow.instructions.md
 agentflow_cli/src/__init__.py
 agentflow_cli/src/app/__init__.py
 agentflow_cli/src/app/loader.py

{10xscale_agentflow_cli-0.3.0 → 10xscale_agentflow_cli-0.3.1}/MANIFEST.in

@@ -6,6 +6,7 @@ include example_weather_agent.py
 recursive-include agentflow_cli *.json
 recursive-include agentflow_cli *.yaml
 recursive-include agentflow_cli *.yml
+recursive-include agentflow_cli *.md
 recursive-include agentflow_cli *.py
 recursive-include src *.json
 recursive-include src *.yaml

{10xscale_agentflow_cli-0.3.0 → 10xscale_agentflow_cli-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: 10xscale-agentflow-cli
-Version: 0.3.0
+Version: 0.3.1
 Summary: CLI and API for 10xscale AgentFlow
 Author-email: 10xscale <contact@10xscale.ai>
 Maintainer-email: Shudipto Trafder <shudiptotrafder@gmail.com>

10xscale_agentflow_cli-0.3.1/agentflow_cli/cli/commands/skills.py

@@ -0,0 +1,306 @@
+"""Skills command implementation."""
+
+from __future__ import annotations
+
+import json
+import shutil
+import sys
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any, Literal
+
+import typer
+
+from agentflow_cli.cli.commands import BaseCommand
+from agentflow_cli.cli.constants import CLI_VERSION
+from agentflow_cli.cli.exceptions import FileOperationError, ValidationError
+
+
+_MANIFEST_FILENAME = ".agentflow-skill.json"
+
+
+@dataclass(frozen=True)
+class _InstallArtifact:
+    """Describes one file or folder installed for an agent."""
+
+    kind: Literal["folder", "file"]
+    install_relpath: str
+    source_relpath: str
+    manifest: bool = False
+
+
+@dataclass(frozen=True)
+class _AgentTarget:
+    """Describes how the bundled skill is materialised for one agent."""
+
+    name: str
+    artifacts: tuple[_InstallArtifact, ...]
+
+    @property
+    def kind(self) -> str:
+        kinds = {artifact.kind for artifact in self.artifacts}
+        if len(kinds) == 1:
+            return next(iter(kinds))
+        return "file+folder"
+
+
+_TARGETS: tuple[_AgentTarget, ...] = (
+    _AgentTarget(
+        name="Codex",
+        artifacts=(
+            _InstallArtifact(
+                kind="folder",
+                install_relpath=".agents/skills/agentflow",
+                source_relpath="agent-skills",
+                manifest=True,
+            ),
+        ),
+    ),
+    _AgentTarget(
+        name="Claude",
+        artifacts=(
+            _InstallArtifact(
+                kind="folder",
+                install_relpath=".claude/skills/agentflow",
+                source_relpath="agent-skills",
+                manifest=True,
+            ),
+        ),
+    ),
+    _AgentTarget(
+        name="GitHub",
+        artifacts=(
+            _InstallArtifact(
+                kind="file",
+                install_relpath=".github/instructions/agentflow.instructions.md",
+                source_relpath="copilot/agentflow.instructions.md",
+            ),
+            _InstallArtifact(
+                kind="folder",
+                install_relpath=".github/skills/agentflow",
+                source_relpath="agent-skills",
+                manifest=True,
+            ),
+        ),
+    ),
+)
+
+_AGENT_LOOKUP: dict[str, _AgentTarget] = {
+    **{t.name.lower(): t for t in _TARGETS},
+    "1": _TARGETS[0],
+    "2": _TARGETS[1],
+    "3": _TARGETS[2],
+}
+
+
+class SkillsCommand(BaseCommand):
+    """Command to install bundled Agentflow skills for supported agents."""
+
+    def execute(
+        self,
+        agent: str | None = None,
+        path: str = ".",
+        force: bool = False,
+        all_agents: bool = False,
+        list_agents: bool = False,
+        **kwargs: Any,
+    ) -> int:
+        """Execute the skills command.
+
+        Args:
+            agent: Target agent name or menu number.
+            path: Project directory where the agent skill should be installed.
+            force: Overwrite an existing installation.
+            all_agents: Install for every supported agent.
+            list_agents: Print supported agents and exit.
+            **kwargs: Additional arguments.
+
+        Returns:
+            Exit code.
+        """
+        try:
+            self.output.print_banner(
+                "Skills",
+                "Install bundled Agentflow skills for Codex, Claude, or GitHub Copilot.",
+                color="magenta",
+            )
+
+            if list_agents:
+                self._print_agents()
+                return 0
+
+            if all_agents and agent:
+                raise ValidationError("--all cannot be combined with --agent.", field="agent")
+
+            templates_root = self._templates_root()
+            project_root = self._safe_project_root(path)
+
+            if all_agents:
+                return self._install_all(templates_root, project_root, force=force)
+
+            target = self._select_agent(agent)
+            self._install_one(templates_root, project_root, target, force=force)
+            return 0
+
+        except (FileOperationError, ValidationError) as e:
+            return self.handle_error(e)
+        except OSError as e:
+            file_error = FileOperationError(f"Failed to install Agentflow skills: {e}")
+            file_error.__cause__ = e
+            return self.handle_error(file_error)
+
+    def _install_one(
+        self,
+        templates_root: Path,
+        project_root: Path,
+        target: _AgentTarget,
+        *,
+        force: bool,
+    ) -> None:
+        installs = [
+            (
+                artifact,
+                templates_root / artifact.source_relpath,
+                project_root / artifact.install_relpath,
+            )
+            for artifact in target.artifacts
+        ]
+        for _artifact, source, _dest in installs:
+            if not source.exists():
+                raise FileOperationError(
+                    f"Bundled skills template not found: {source}", file_path=str(source)
+                )
+
+        existing = [dest for _artifact, _source, dest in installs if dest.exists()]
+        if existing and not force:
+            paths = ", ".join(str(dest) for dest in existing)
+            raise FileOperationError(
+                f"Skill already installed at {paths}. Use --force to overwrite.",
+                file_path=str(existing[0]),
+            )
+
+        for _artifact, _source, dest in installs:
+            if dest.exists():
+                if dest.is_dir():
+                    shutil.rmtree(dest)
+                else:
+                    dest.unlink()
+
+        installed_paths: list[str] = []
+        for artifact, source, dest in installs:
+            dest.parent.mkdir(parents=True, exist_ok=True)
+
+            if artifact.kind == "folder":
+                shutil.copytree(
+                    source,
+                    dest,
+                    ignore=shutil.ignore_patterns("__pycache__", "*.pyc", ".DS_Store"),
+                )
+                if artifact.manifest:
+                    self._write_manifest(dest, target.name)
+            else:
+                shutil.copyfile(source, dest)
+            installed_paths.append(str(dest))
+
+        self.output.success(
+            f"Installed Agentflow skills for {target.name} at {', '.join(installed_paths)}"
+        )
+
+    def _install_all(self, templates_root: Path, project_root: Path, *, force: bool) -> int:
+        installed = 0
+        skipped: list[str] = []
+        failed: list[str] = []
+        for target in _TARGETS:
+            existing = [
+                project_root / artifact.install_relpath
+                for artifact in target.artifacts
+                if (project_root / artifact.install_relpath).exists()
+            ]
+            if existing and not force:
+                paths = ", ".join(str(dest) for dest in existing)
+                skipped.append(f"{target.name} ({paths})")
+                continue
+            try:
+                self._install_one(templates_root, project_root, target, force=force)
+                installed += 1
+            except (FileOperationError, OSError, UnicodeError) as e:
+                self.logger.error("Install failed for %s: %s", target.name, e)
+                failed.append(f"{target.name}: {e}")
+
+        if skipped:
+            self.output.warning(
+                "Skipped existing installs (use --force to overwrite): " + ", ".join(skipped)
+            )
+        if failed:
+            self.output.error("Failed installs: " + "; ".join(failed))
+
+        if failed and installed == 0:
+            return 1
+        return 0
+
+    def _write_manifest(self, target_dir: Path, agent_name: str) -> None:
+        manifest = {
+            "agent": agent_name,
+            "cli_version": CLI_VERSION,
+            "installed_at": datetime.now(UTC).isoformat(timespec="seconds"),
+        }
+        (target_dir / _MANIFEST_FILENAME).write_text(
+            json.dumps(manifest, indent=2) + "\n", encoding="utf-8"
+        )
+
+    def _print_agents(self) -> None:
+        rows = [
+            [t.name, t.kind, ", ".join(a.install_relpath for a in t.artifacts)] for t in _TARGETS
+        ]
+        self.output.print_table(
+            ["Agent", "Kind", "Install path (relative to --path)"],
+            rows,
+            title="Supported agents",
+        )
+
+    def _safe_project_root(self, path: str) -> Path:
+        project_root = Path(path).resolve()
+        if project_root.parent == project_root:
+            raise ValidationError(
+                f"Refusing to install skills at filesystem root: {project_root}",
+                field="path",
+            )
+        if project_root == Path.home().resolve():
+            raise ValidationError(
+                f"Refusing to install skills directly into the home directory: {project_root}. "
+                "Pass --path pointing at a project directory.",
+                field="path",
+            )
+        return project_root
+
+    def _select_agent(self, agent: str | None) -> _AgentTarget:
+        if agent:
+            return self._normalize_agent(agent)
+
+        if not sys.stdin.isatty():
+            raise ValidationError(
+                "No --agent provided and stdin is not interactive. "
+                "Pass --agent codex|claude|github or --all.",
+                field="agent",
+            )
+
+        self.output.print_list(
+            [f"{i}. {t.name}" for i, t in enumerate(_TARGETS, 1)],
+            title="Which agent?",
+            bullet="-",
+        )
+        selected = typer.prompt("Select an agent", default="1")
+        return self._normalize_agent(selected)
+
+    def _normalize_agent(self, value: str) -> _AgentTarget:
+        key = value.strip().lower()
+        if key in _AGENT_LOOKUP:
+            return _AGENT_LOOKUP[key]
+
+        valid = "Codex, Claude, GitHub, or 1, 2, 3"
+        raise ValidationError(f"Invalid agent '{value}'. Choose {valid}.", field="agent")
+
+    def _templates_root(self) -> Path:
+        cli_dir = Path(__file__).resolve().parents[1]
+        return cli_dir / "templates" / "skills"

{10xscale_agentflow_cli-0.3.0 → 10xscale_agentflow_cli-0.3.1}/agentflow_cli/cli/main.py

@@ -8,6 +8,7 @@ from dotenv import load_dotenv
 from agentflow_cli.cli.commands.api import APICommand
 from agentflow_cli.cli.commands.build import BuildCommand
 from agentflow_cli.cli.commands.init import InitCommand
+from agentflow_cli.cli.commands.skills import SkillsCommand
 from agentflow_cli.cli.commands.version import VersionCommand
 from agentflow_cli.cli.constants import (
     DEFAULT_CONFIG_FILE,
@@ -308,6 +309,67 @@ def build(
         sys.exit(handle_exception(e))
 
 
+@app.command()
+def skills(
+    agent: str | None = typer.Option(
+        None,
+        "--agent",
+        "-a",
+        help="Target agent: codex, claude, github, or menu number 1, 2, 3",
+    ),
+    path: str = typer.Option(
+        ".",
+        "--path",
+        "-p",
+        help="Project directory where the skills should be installed",
+    ),
+    force: bool = typer.Option(
+        False,
+        "--force",
+        "-f",
+        help="Overwrite the existing installed Agentflow skill directory",
+    ),
+    all_agents: bool = typer.Option(
+        False,
+        "--all",
+        help="Install skills for every supported agent",
+    ),
+    list_agents: bool = typer.Option(
+        False,
+        "--list",
+        "-l",
+        help="List supported agents and exit",
+    ),
+    verbose: bool = typer.Option(
+        False,
+        "--verbose",
+        "-v",
+        help="Enable verbose logging",
+    ),
+    quiet: bool = typer.Option(
+        False,
+        "--quiet",
+        "-q",
+        help="Suppress all output except errors",
+    ),
+) -> None:
+    """Install bundled Agentflow skills for Codex, Claude, or GitHub."""
+    setup_cli_logging(verbose=verbose, quiet=quiet)
+
+    try:
+        command = SkillsCommand(output)
+        exit_code = command.execute(
+            agent=agent,
+            path=path,
+            force=force,
+            all_agents=all_agents,
+            list_agents=list_agents,
+        )
+        sys.exit(exit_code)
+    except Exception as e:
+        sys.exit(handle_exception(e))
+
+
 def main() -> None:
     """Main CLI entry point."""
     try:

10xscale_agentflow_cli-0.3.1/agentflow_cli/cli/templates/skills/agent-skills/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: agentflow
+description: Use for building, debugging, documenting, or extending Agentflow agents, tools, graphs, API/CLI services, TypeScript clients, memory, checkpointing, streaming, media, dependency injection, production runtime, and multi-agent workflows in this repository.
+metadata:
+  resources:
+    - references/architecture.md
+    - references/agents-and-tools.md
+    - references/state-graph.md
+    - references/state-and-messages.md
+    - references/checkpointing-and-threads.md
+    - references/dependency-injection.md
+    - references/media-and-files.md
+    - references/memory-and-store.md
+    - references/streaming.md
+    - references/production-runtime.md
+    - references/api-client.md
+    - references/remote-tools.md
+    - references/callbacks-and-command.md
+    - references/prebuilt-agents-and-tools.md
+    - references/testing-and-evaluation.md
+    - references/publishers-and-runtime-protocols.md
+    - references/context-id-background.md
+    - references/providers-and-adapters.md
+    - references/security-and-validators.md
+    - references/cli-commands.md
+    - references/api-configuration.md
+    - references/auth-and-authorization.md
+    - references/api-settings-and-middleware.md
+    - references/rest-api-and-errors.md
+    - references/id-and-thread-name-generators.md
+    - references/client-auth-and-errors.md
+    - references/client-messages-invoke-stream.md
+    - references/client-threads-memory-files.md
+  tags:
+    - agentflow
+    - agents
+    - multi-agent
+    - framework
+  priority: 10
+---
+
+# Agentflow Project Skill
+
+Use this skill when working in this Agentflow monorepo. Agentflow is a multi-agent framework that wraps official OpenAI and Google SDK capabilities behind a unified graph, agent, tool, state, storage, API, CLI, and TypeScript client interface.
+
+Treat `agentflow-docs/docs` as the first source of truth for public package names, install commands, and user-facing behavior. Use implementation source after the docs establish the intended API.
+
+## Workflow
+
+1. Identify the published package or docs surface involved:
+   - PyPI core Python SDK: `10xscale-agentflow` (`pip install 10xscale-agentflow`), source in `agentflow/agentflow`
+   - PyPI API/CLI SDK: `10xscale-agentflow-cli` (`pip install 10xscale-agentflow-cli`), source in `agentflow-api/agentflow_cli`
+   - npm TypeScript SDK: `@10xscale/agentflow-client` (`npm install @10xscale/agentflow-client`), source in `agentflow-client/src`
+   - Main docs: `agentflow-docs/docs`
+   - Playground/UI: `agentflow play` command after installed cli
+
+2. Read the matching reference file before changing behavior:
+   - Architecture and package flow: `references/architecture.md`
+   - Agent and tool behavior: `references/agents-and-tools.md`
+   - Graph construction and execution: `references/state-graph.md`
+   - State, messages, and content blocks: `references/state-and-messages.md`
+   - Threads and persistence: `references/checkpointing-and-threads.md`
+   - Dependency injection: `references/dependency-injection.md`
+   - Multimodal files and media stores: `references/media-and-files.md`
+   - Long-term memory stores: `references/memory-and-store.md`
+   - Streaming, chunks, and SSE: `references/streaming.md`
+   - API server and deployment runtime: `references/production-runtime.md`
+   - REST and TypeScript client surface: `references/api-client.md`
+   - Browser/client-side tool execution: `references/remote-tools.md`
+   - Observability hooks, validators, and runtime jumps: `references/callbacks-and-command.md`
+   - Prebuilt agents/tools and handoff helpers: `references/prebuilt-agents-and-tools.md`
+   - Testing helpers and evaluation framework: `references/testing-and-evaluation.md`
+   - Event publishers and A2A/ACP runtime protocols: `references/publishers-and-runtime-protocols.md`
+   - Context management, ID generation, and background tasks: `references/context-id-background.md`
+   - Provider internals and adapters: `references/providers-and-adapters.md`
+   - Prompt-injection and validation safety: `references/security-and-validators.md`
+   - CLI commands and generated project files: `references/cli-commands.md`
+   - `agentflow.json` and dependency loading: `references/api-configuration.md`
+   - API auth and authorization: `references/auth-and-authorization.md`
+   - API environment, settings, and middleware: `references/api-settings-and-middleware.md`
+   - REST routes and error behavior: `references/rest-api-and-errors.md`
+   - API Snowflake IDs and thread naming: `references/id-and-thread-name-generators.md`
+   - TypeScript auth helpers and structured errors: `references/client-auth-and-errors.md`
+   - TypeScript messages, invoke, and stream details: `references/client-messages-invoke-stream.md`
+   - TypeScript thread, memory, and file APIs: `references/client-threads-memory-files.md`
+3. Prefer existing Agentflow abstractions over new custom wiring:
+   - Build workflows with `StateGraph`, `Agent`, `ToolNode`, `AgentState`, and `Message`.
+   - Persist conversation state with checkpointers; use stores only for cross-thread memory.
+   - Put business services in `InjectQ` instead of global variables.
+   - Keep API/CLI graph modules storage-agnostic and wire dependencies through `agentflow.json`.
+4. Verify against source when implementation details matter. Public names and expected behavior should match `agentflow-docs/docs`; source under `agentflow/`, `agentflow-api/`, and `agentflow-client/src/` explains how that behavior is implemented.
+
+## Local Conventions
+
+- A compiled graph is normally loaded once by the API server and reused per request.
+- Public package naming matters: use `10xscale-agentflow`, `10xscale-agentflow-cli`, and `@10xscale/agentflow-client` in user-facing docs and examples, not repository folder names.
+- Every persisted interaction should include `config.thread_id`.
+- Tools need docstrings and type annotations so model-facing schemas are useful.
+- Injectable tool and node parameters such as `state`, `config`, and `tool_call_id` are hidden from the model schema.
+- For production, avoid process-local storage for shared state; use durable checkpointer/store backends.

10xscale_agentflow_cli-0.3.1/agentflow_cli/cli/templates/skills/agent-skills/references/agents-and-tools.md

@@ -0,0 +1,65 @@
+# Agents and Tools
+
+Use this when adding model behavior, tools, tool routing, provider options, retries, fallbacks, memory tools, or skills to an agent.
+
+## Agent
+
+`Agent` is a graph node that calls an LLM provider and appends the response to state. It supports OpenAI and Google provider flows behind a unified interface. Provider can be explicit (`"openai"` or `"google"`) or inferred from the model/config in existing code paths.
+
+Common constructor concerns:
+
+- `model`: model name.
+- `provider`: provider name when auto-detection is not enough.
+- `output_type`: `"text"`, `"image"`, `"video"`, or `"audio"`.
+- `system_prompt`: string/list message instructions; supports `{state_field}` interpolation.
+- `tool_node`: `ToolNode` instance or a graph node name string.
+- `trim_context`: trims messages before model calls and writes summaries to `context_summary`.
+- `reasoning_config`: effort/budget/provider reasoning options.
+- `retry_config` and `fallback_models`: retry and cross-provider fallback behavior.
+- `multimodal_config`: image/document/audio/video handling.
+- `memory`: `MemoryConfig` that wires memory tools onto the tool node.
+- `skills`: `SkillConfig` that discovers and exposes skills through the tool node.
+- Extra kwargs such as `temperature`, `max_tokens`, and `base_url`.
+
+## ToolNode
+
+`ToolNode` registers and executes callable tools requested by the model. It supports local Python callables, MCP clients, Composio/LangChain style tools where supported by the implementation, and dynamically added tools.
+
+For client-executed tools registered through `@10xscale/agentflow-client`, read `remote-tools.md`.
+
+Tool authoring rules:
+
+- Provide useful docstrings; they become model-facing descriptions.
+- Provide type annotations; they become the parameter schema.
+- Return plain values for normal tool results.
+- Return `ToolResult` when a tool also needs to update state fields.
+- Keep model-visible parameters separate from injected parameters.
+
+Injected parameters are hidden from the model schema:
+
+- `state`: current `AgentState` or subclass.
+- `config`: execution config including `thread_id`, `user_id`, and `run_id`.
+- `tool_call_id`: current model tool call ID.
+
+## ReAct Loop
+
+The standard tool-using graph loops from agent to tools and back:
+
+1. `Agent` returns an assistant message.
+2. Route to `ToolNode` when the last assistant message has `tools_calls`.
+3. `ToolNode` appends a tool result message.
+4. Route back to `Agent` so the model can produce a final answer.
+5. End when there are no more tool calls.
+
+## `@tool`
+
+Use `agentflow.utils.tool` to add metadata such as name, description, tags, provider, capabilities, and arbitrary metadata. The decorator enriches the schema; it does not change injected parameter behavior.
+
+## Source Map
+
+- Agent implementation: `agentflow/agentflow/core/graph/agent.py`
+- Tool node and graph exports: `agentflow/agentflow/core/graph`
+- Tool result: `agentflow/agentflow/core/state/tool_result.py`
+- Tool decorator: `agentflow/agentflow/utils/decorators.py`
+- Skill integration: `agentflow/agentflow/core/skills`
+- Prebuilt tools: `agentflow/agentflow/prebuilt/tools`