Skip to main content

The Agentic Layer

Tool Integrations

Tools are capabilities you give to agents. File reading, code execution, API access, context gathering. Not IDEs. Not products. Capabilities.

What are tools in this context

In this framework, a "tool" is a capability boundary. It defines what an agent can do in the environment. Reading a file is a tool. Running a shell command is a tool. The framework organizes these into 4 categories and controls which phases get access to which.

Tools are not products. "File system access" is a tool category. A specific editor, IDE, or CLI is a product that provides that tool category. The framework defines the categories. Your tooling stack provides the implementations.

The four tool categories

Read

read file contents, list directories, check existence

Write

create new files, edit existing files, delete files

Search

pattern matching (grep/glob), find files, AST search

# tools/file-system.yaml
file_system:
  read:
    enabled: true
    allowed_paths:
      - "src/**"
      - "tests/**"
      - "docs/**"
    denied_paths:
      - ".env"
      - "**/*.secret"
      - "node_modules/**"
  write:
    enabled: true
    allowed_paths:
      - "src/**"
      - "tests/**"
    denied_paths:
      - "src/config/production.ts"
      - "**/*.lock"
  search:
    enabled: true
    max_results: 100
    timeout_ms: 5000

Shell

run arbitrary commands (with sandboxing)

Test Runners

jest, pytest, go test, cargo test

Linters/Formatters

eslint, prettier, ruff, gofmt, rustfmt

Build Tools

tsc, webpack, cargo build, go build

Security Warning

code execution is the most powerful and most dangerous tool category. Always sandbox agent execution environments. Agents should never run commands that modify system-level configuration, access network resources not explicitly allowed, delete files outside the project, or install global packages.

# tools/code-execution.yaml
code_execution:
  shell:
    enabled: true
    sandbox: true
    timeout_ms: 120000
    allowed_commands:
      - "npm *"
      - "npx *"
      - "node *"
      - "git *"
      - "tsc *"
    denied_commands:
      - "rm -rf /*"
      - "sudo *"
      - "curl * | bash"
      - "npm publish"
  test_runners:
    enabled: true
    commands:
      unit: "npm test"
      integration: "npm run test:integration"
      e2e: "npm run test:e2e"
    timeout_ms: 300000
  linters:
    enabled: true
    commands:
      lint: "npm run lint"
      format_check: "npm run format:check"
  build:
    enabled: true
    commands:
      typecheck: "npx tsc --noEmit"
      build: "npm run build"

Version Control

Git operations, branch management, PR creation

CI/CD

trigger workflows, check build status, read logs

Issue Trackers

read issues, update status, create sub-tasks

Browser Automation

E2E testing, visual review, screenshot comparison

# tools/external-apis.yaml
external_apis:
  version_control:
    enabled: true
    provider: git               # tool-agnostic: just git
    operations:
      - branch_create
      - branch_switch
      - commit
      - push
      - pull_request_create
      - pull_request_update
    protected_branches:
      - main
      - production
  ci_cd:
    enabled: true
    operations: [trigger_pipeline, check_status, read_logs]
    auto_trigger: false
  issue_tracker:
    enabled: true
    operations: [read_issue, update_status, add_comment, create_subtask]
  browser:
    enabled: false               # enable for visual review

Codebase Indexing

AST parsing, dependency graphs, symbol tables

Documentation

relevant docs on demand, API references, READMEs

Dependencies

package relationships, version compatibility

Agents with too much context perform worse. Context providers are not "dump everything." They retrieve and surface only what is relevant. A Plan agent analyzing a bug in the auth module does not need the entire codebase.

# tools/context-providers.yaml
context_providers:
  codebase_index:
    enabled: true
    index_type: ast              # ast | text | hybrid
    languages: [typescript, python]
    max_context_tokens: 8000
    relevance_threshold: 0.7
  documentation:
    enabled: true
    sources:
      - path: "docs/**/*.md"
      - path: "README.md"
      - path: "ARCHITECTURE.md"
    max_docs_per_request: 5
  dependency_analyzer:
    enabled: true
    manifest_files: ["package.json", "tsconfig.json"]

Permission matrix: tools by phase

Tool Plan Build Test Review Doc Deploy Monitor
file.readYYYYYYY
file.writeNYYNYNN
file.searchYYYYYYY
exec.shellNYYNNYY
exec.testNYYNNNN
exec.lintNYNNNNN
api.gitNNNNNYN
api.issuesYNNNNNY
ctx.indexYYYYNNN
ctx.docsYYNYYNN

This is the default matrix. Override per-project in your workflow.yaml. The principle is least privilege: each phase gets only what it needs. Planners cannot execute code. Reviewers cannot write files. This is not a limitation; it is a safety pattern.

Adding a new tool integration

1

Define the config file

Create a YAML file in agentic-layer/tools/ describing capabilities, allowed operations, and security boundaries.

2

Declare permissions per phase

In workflow.yaml, specify which phases can access the new tool. Default to denied; explicitly grant.

3

Reference in templates

Update the relevant prompt templates to inform the agent about the new capability. An agent cannot use a tool it does not know exists.

# workflow.yaml -- adding a custom tool
tools:
  file_system: tools/file-system.yaml
  code_execution: tools/code-execution.yaml
  external_apis: tools/external-apis.yaml
  context_providers: tools/context-providers.yaml
  custom_analytics: tools/analytics.yaml    # your new tool

phase_tools:
  plan: [file_system.read, file_system.search, context_providers, custom_analytics.read]
  build: [file_system, code_execution, context_providers]
  # ... etc