### Quick Start: Install and Run NOT7 (macOS)

Source: https://github.com/avoguru/not7-core/blob/main/README.md

This snippet details the steps to download, make executable, and run the NOT7 binary on macOS (Apple Silicon and Intel) and Linux. It includes setting up configuration and running an example agent.

```bash
curl -L https://github.com/not7/core/raw/main/dist/not7-darwin-arm64 -o not7
chmod +x not7
cp not7.conf.example not7.conf
# Edit not7.conf: Add your OPENAI_API_KEY
./not7 run examples/camera-research.json
```

```bash
# Setup Arcade.dev credentials in not7.conf
# ARCADE_API_KEY=your-key
# ARCADE_USER_ID=your-user-id

# Authorize Google services
./not7 authorize

# Run lunch recommendations demo (update email in JSON first!)
./not7 run examples/arcade-lunch-demo.json
```

--------------------------------

### Execute Multi-Toolkit Agent and Setup

Source: https://context7.com/avoguru/not7-core/llms.txt

This example provides the necessary command-line instructions to execute the multi-toolkit agent and details the setup required for Arcade credentials and Google service authorization. It outlines the steps for running the agent and the expected outcome, highlighting the seamless transition between different toolkits.

```bash
# Setup Arcade credentials in not7.conf
# ARCADE_API_KEY=your-api-key
# ARCADE_USER_ID=your-user-id

# Authorize Google services (one-time OAuth)
./not7 authorize

# Execute the multi-toolkit agent
./not7 run examples/arcade-lunch-demo.json

# Result: Agent searches Google Maps, formats results, and sends email via Gmail
# Each node uses its own toolkit (googlemaps vs gmail) seamlessly
```

--------------------------------

### Test and Run NOT7 Build

Source: https://context7.com/avoguru/not7-core/llms.txt

After building the NOT7 binary, this snippet shows how to test the build by checking the version and running example agents. It includes copying and editing the configuration file, which may be necessary for API key setup.

```bash
# Test the build
./not7 --version

# Run examples
cp not7.conf.example not7.conf
# Edit not7.conf with API key
./not7 run examples/camera-research.json
```

--------------------------------

### Configure and Deploy NOT7 Runtime

Source: https://context7.com/avoguru/not7-core/llms.txt

Provides instructions for setting up the NOT7 runtime for production. It includes steps to copy an example configuration file, edit it with necessary API keys and server settings (e.g., OpenAI, server port, directories, tool provider keys), and then start the NOT7 server using a command-line interface. The output shows the NOT7 banner upon successful startup.

```bash
# Copy example configuration
cp not7.conf.example not7.conf

# Edit not7.conf with your credentials
cat > not7.conf << 'EOF'
# OpenAI Settings
OPENAI_API_KEY=sk-proj-abc123def456...
OPENAI_DEFAULT_MODEL=gpt-4
OPENAI_DEFAULT_TEMPERATURE=0.7
OPENAI_DEFAULT_MAX_TOKENS=2000

# Server Settings
SERVER_PORT=8080
SERVER_EXECUTIONS_DIR=./executions
SERVER_LOG_DIR=./logs

# Arcade Tool Provider (optional)
ARCADE_API_KEY=arcade_sk_abc123...
ARCADE_USER_ID=user_12345

# Built-in Tool Provider (optional)
SERP_API_KEY=your-serpapi-key-here
EOF

# Start server in production
./not7 serve

# Output:
# ╔═════════════════════════════════════════════════════════════╗
# ║            ███╗   ██╗ ██████╗ ████████╗███████╗             ║
# ║            ████╗  ██║██╔═══██╗╚══██╔══╝╚════██║             ║
# ║            ██╔██╗ ██║██║   ██║   ██║       ██╔╝             ║
# ║            ██║╚██╗██║██║   ██║   ██║      ██╔╝              ║
# ║            ██║ ╚████║╚██████╔╝   ██║      ██║               ║
# ║            ╚═╝  ╚═══╝ ╚═════╝    ╚═╝      ╚═╝               ║
# ║                 Declarative Agent Runtime                   ║

```

--------------------------------

### Setup Commands for not7-core

Source: https://github.com/avoguru/not7-core/blob/main/README.md

These bash commands outline the initial setup required for the not7-core project. It involves adding necessary API keys and user IDs to the not7.conf file and then running an authorization command, likely for setting up OAuth credentials for external services.

```bash
# Add to not7.conf
ARCADE_API_KEY=your-api-key
ARCADE_USER_ID=your-user-id

# Authorize (one-time interactive OAuth)
./not7 authorize
```

--------------------------------

### Example Agent Execution Output (Text)

Source: https://github.com/avoguru/not7-core/blob/main/README.md

This is an example of the output generated when running the poem-generator.json agent using the NOT7 CLI. It shows the agent loading, execution details, cost, and the final output.

```text
NOT7 - Agent Runtime
====================

📖 Loading spec: poem-generator.json
✓ Spec loaded successfully

🚀 Starting agent: Generate a poem about AI agents
📋 Version: 1.0.0

⚙️  Executing node: Generate Poem About Agents (llm)
   ✓ Completed in 2850ms (cost: $0.0275)

✅ Execution completed in 2850ms
💰 Total cost: $0.0275

📄 Output:
─────────────────────────────────────
[Your generated poem appears here]
─────────────────────────────────────

💾 Results saved to: poem-generator.json.result.json
```

--------------------------------

### Start Go HTTP Server for Agent Management

Source: https://context7.com/avoguru/not7-core/llms.txt

This Go code initializes and starts the NOT7 HTTP server, which listens for agent execution requests via a REST API. It loads configuration from a 'not7.conf' file and sets up directories for storing executions and logs. The server is configured with a port and these directory paths. Dependencies include the 'github.com/not7/core/config' and 'github.com/not7/core/server' packages.

```go
package main

import (
    "fmt"
    "github.com/not7/core/config"
    "github.com/not7/core/server"
)

func main() {
    // Load configuration from not7.conf
    cfg, err := config.LoadConfig("not7.conf")
    if err != nil {
        panic(fmt.Errorf("failed to load config: %w", err))
    }

    // Create server with configuration
    srv := server.NewServer(
        cfg.Server.Port,           // Port: 8080
        cfg.Server.ExecutionsDir,  // Executions storage: ./executions
        cfg.Server.LogDir,         // Logs directory: ./logs
    )

    // Start server (blocks until error)
    if err := srv.Start(); err != nil {
        panic(fmt.Errorf("server error: %w", err))
    }
}
```

--------------------------------

### Start HTTP Server for Agent Management

Source: https://context7.com/avoguru/not7-core/llms.txt

This Go code illustrates how to launch the NOT7 HTTP server, which listens for agent execution requests. It loads configuration and specifies directories for executions and logs.

```APIDOC
## Start HTTP Server for Agent Management

### Description
This Go code illustrates how to launch the NOT7 HTTP server, which listens for agent execution requests. It loads configuration and specifies directories for executions and logs.

### Method
Programmatic server startup within a Go application.

### Endpoint
N/A (Server runs on a configured port)

### Parameters
N/A

### Request Example
```go
package main

import (
    "fmt"
    "github.com/not7/core/config"
    "github.com/not7/core/server"
)

func main() {
    // Load configuration from not7.conf
    cfg, err := config.LoadConfig("not7.conf")
    if err != nil {
        panic(fmt.Errorf("failed to load config: %w", err))
    }

    // Create server with configuration
    srv := server.NewServer(
        cfg.Server.Port,           // Port: 8080
        cfg.Server.ExecutionsDir,  // Executions storage: ./executions
        cfg.Server.LogDir,         // Logs directory: ./logs
    )

    // Start server (blocks until error)
    if err := srv.Start(); err != nil {
        panic(fmt.Errorf("server error: %w", err))
    }
}
```

### Response
N/A (Server runs and listens for incoming API requests. Errors are handled via panic.)
```

--------------------------------

### Example Workflow: NOT7 Agent Management (Bash)

Source: https://github.com/avoguru/not7-core/blob/main/README.md

A comprehensive bash script demonstrating a typical workflow for managing and interacting with NOT7 agents using curl. It includes deploying, listing, running, updating, and deleting an agent.

```bash
# 1. Deploy an agent
curl -X POST http://localhost:8080/api/v1/agents \
  -H "Content-Type: application/json" \
  -d @examples/poem-generator.json

# 2. List agents
curl http://localhost:8080/api/v1/agents

# 3. Run agent (can trigger multiple times)
curl -X POST http://localhost:8080/api/v1/agents/poem-generator/run

# 4. Update agent
curl -X PUT http://localhost:8080/api/v1/agents/poem-generator \
  -H "Content-Type: application/json" \
  -d @examples/poem-generator-v2.json

# 5. Delete agent
curl -X DELETE http://localhost:8080/api/v1/agents/poem-generator
```

--------------------------------

### Execute Agent via REST API (Bash)

Source: https://context7.com/avoguru/not7-core/llms.txt

This bash script demonstrates how to interact with the NOT7 HTTP API to execute agents. It shows examples for both synchronous execution (waiting for the result) and asynchronous execution (starting in the background). It also includes a command to check the status of an asynchronous execution using its ID. The API accepts agent specifications in JSON format.

```bash
# Synchronous execution - wait for completion
curl -X POST http://localhost:8080/api/v1/run \
  -H "Content-Type: application/json" \
  -d '{
    "version": "1.0.0",
    "goal": "Generate a creative poem about AI agents",
    "config": {
      "llm": {
        "provider": "openai",
        "model": "gpt-4",
        "temperature": 0.9
      }
    },
    "nodes": [
      {
        "id": "generate_poem",
        "name": "Poem Generator",
        "type": "llm",
        "prompt": "Write a creative 4-stanza poem about AI agents and their role in the future of technology."
      }
    ],
    "routes": [
      {"from": "start", "to": "generate_poem"},
      {"from": "generate_poem", "to": "end"}
    ]
  }'

# Response (synchronous):
# {
#   "id": "",
#   "status": "success",
#   "goal": "Generate a creative poem about AI agents",
#   "output": "[Generated poem text...]",
#   "duration_ms": 2850,
#   "total_cost": 0.0275,
#   "created_at": "2025-10-25T10:30:00Z"
# }

# Asynchronous execution - return immediately
curl -X POST http://localhost:8080/api/v1/run?async=true \
  -H "Content-Type: application/json" \
  -d @agent.json

# Response (async):
# {
#   "execution_id": "exec_abc123def456",
#   "status": "running",
#   "message": "Execution started in background"
# }

# Check execution status
curl http://localhost:8080/api/v1/executions/exec_abc123def456

# Response:
# {
#   "id": "exec_abc123def456",
#   "status": "success",
#   "goal": "Generate a creative poem about AI agents",
#   "created_at": "2025-10-25T10:30:00Z",
#   "started_at": "2025-10-25T10:30:01Z",
#   "ended_at": "2025-10-25T10:30:04Z",
# }
```

--------------------------------

### Example Agent: Poem Generator (JSON)

Source: https://github.com/avoguru/not7-core/blob/main/README.md

An example of a declarative agent specification in JSON format for the NOT7 system. This agent is configured to generate a poem about AI agents using the OpenAI GPT-4 model.

```json
{
  "version": "1.0.0",
  "goal": "Generate a poem about AI agents",
  
  "config": {
    "llm": {
      "provider": "openai",
      "model": "gpt-4",
      "temperature": 0.9
    }
  },

  "nodes": [
    {
      "id": "generate_poem",
      "type": "llm",
      "prompt": "Write a creative poem about AI agents...",
      "output_format": "text"
    }
  ],

  "routes": [
    {"from": "start", "to": "generate_poem"},
    {"from": "generate_poem", "to": "end"}
  ]
}
```

--------------------------------

### Multi-Toolkit Configuration with Node-Level Overrides

Source: https://github.com/avoguru/not7-core/blob/main/README.md

This JSON configuration illustrates a multi-toolkit setup where different nodes utilize distinct toolkits. It includes a 'react' node using 'arcade-googlemaps', an 'llm' node with 'openai', and a 'tool' node for sending email via 'arcade-gmail'. This allows for complex workflows by chaining specialized tools and services.

```json
{
  "config": {
    "llm": {
      "provider": "openai",
      "model": "gpt-4o"
    }
  },
  "nodes": [
    {
      "id": "find-restaurants",
      "type": "react",
      "tools_enabled": true,
      "config": {
        "tools": {
          "provider": "arcade-googlemaps"
        }
      },
      "react_goal": "Find 3 lunch restaurants in San Francisco"
    },
    {
      "id": "format-email",
      "type": "llm",
      "prompt": "Format the restaurant list as a clean email"
    },
    {
      "id": "send-email",
      "type": "tool",
      "config": {
        "tools": {
          "provider": "arcade-gmail"
        }
      },
      "tool_name": "SendEmail",
      "tool_arguments": {
        "recipient": "user@example.com",
        "subject": "Lunch Recommendations",
        "body": "{{input}}"
      }
    }
  ],
  "routes": [
    {"from": "start", "to": "find-restaurants"},
    {"from": "find-restaurants", "to": "format-email"},
    {"from": "format-email", "to": "send-email"},
    {"from": "send-email", "to": "end"}
  ]
}
```

--------------------------------

### Execute Multi-Node Agent via CLI

Source: https://context7.com/avoguru/not7-core/llms.txt

This example shows how to execute the previously defined multi-node agent configuration from the command line using the Not7 CLI. It includes the command to run the agent and a sample of the expected output, illustrating the agent's execution process and the final results.

```bash
# Execute from command line
./not7 run examples/camera-research.json

# Output:
# 🚀 Starting agent: Research the best cameras for content creators in 2025
# 📋 Version: 1.0.0
#
# ⚙️  Executing node: Camera Research Agent (react)
#    Iteration 1: Searching for camera reviews...
#    Iteration 2: Analyzing Sony A7 IV specifications...
#    Iteration 3: Comparing with Canon R6 Mark II...
#    ✓ Completed in 12500ms (cost: $0.1250)
#
# ✅ Execution completed in 12500ms
# 💰 Total cost: $0.1250
#
# 📄 Output:
# ─────────────────────────────────────
# Top 5 Cameras for Content Creators in 2025:
#
# 1. Sony A7 IV - $2,498
#    - 33MP full-frame sensor, 4K 60fps video...
# [Full research results...]
# ─────────────────────────────────────
```

--------------------------------

### Create Multi-Node Agent with ReAct Reasoning

Source: https://context7.com/avoguru/not7-core/llms.txt

This example demonstrates how to build a multi-node agent that uses ReAct (Reasoning + Acting) loops. It allows agents to access tools for performing complex tasks. The configuration defines the LLM, tools, and the sequence of nodes for the agent's workflow. Dependencies include the Not7 Core library.

```json
{
  "id": "camera-research",
  "version": "1.0.0",
  "goal": "Research the best cameras for content creators in 2025",
  "config": {
    "llm": {
      "provider": "openai",
      "model": "gpt-4",
      "temperature": 0.7,
      "max_tokens": 4000
    },
    "tools": {
      "provider": "builtin"
    }
  },
  "nodes": [
    {
      "id": "research",
      "name": "Camera Research Agent",
      "type": "react",
      "tools_enabled": true,
      "react_goal": "Research the best cameras for content creators in 2025. Find 3-5 top recommendations with specific model names, key features, and pricing. Use WebSearch to find recent reviews and comparisons.",
      "max_iterations": 15
    }
  ],
  "routes": [
    {"from": "start", "to": "research"},
    {"from": "research", "to": "end"}
  ]
}
```

--------------------------------

### Get Agent

Source: https://github.com/avoguru/not7-core/blob/main/README.md

Retrieves the full specification of a specific deployed agent by its ID.

```APIDOC
## GET /api/v1/agents/{id}

### Description
Retrieves the specification for a specific agent identified by its ID.

### Method
GET

### Endpoint
/api/v1/agents/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the agent to retrieve.

### Response
#### Success Response (200)
- **agent** (object) - The full specification of the requested agent.

#### Response Example
```json
{
  "id": "my-agent",
  "version": "1.0.0",
  "goal": "Do something",
  "nodes": [...],
  "routes": [...] 
}
```
```

--------------------------------

### Multi-Toolkit Orchestration with Per-Node Configuration

Source: https://context7.com/avoguru/not7-core/llms.txt

This example demonstrates creating agents that use different tool providers in different nodes for complex workflows. It configures a multi-node agent where one node uses the 'arcade-googlemaps' tool and another uses the 'arcade-gmail' tool. This showcases seamless integration of different toolkits within a single agent execution.

```json
{
  "id": "arcade-lunch-demo",
  "version": "1.0.0",
  "goal": "Arcade Integration Demo: Lunch Recommendations via Google Maps + Gmail",
  "config": {
    "llm": {
      "provider": "openai",
      "model": "gpt-4o",
      "temperature": 0.7,
      "max_tokens": 2000
    }
  },
  "nodes": [
    {
      "id": "find-restaurants",
      "name": "Find Lunch Recommendations",
      "type": "react",
      "tools_enabled": true,
      "config": {
        "tools": {
          "provider": "arcade-googlemaps"
        }
      },
      "react_goal": "Find 3 highly-rated restaurants in San Francisco for lunch today. For each restaurant, get: name, address, rating, and brief description.",
      "max_iterations": 8
    },
    {
      "id": "format-recommendations",
      "name": "Format Recommendations",
      "type": "llm",
      "prompt": "Format the restaurant recommendations into a simple plain text email. List each of the 3 restaurants with name, address, rating, and description."
    },
    {
      "id": "send-email",
      "name": "Send Recommendations Email",
      "type": "tool",
      "config": {
        "tools": {
          "provider": "arcade-gmail"
        }
      },
      "tool_name": "SendEmail",
      "tool_arguments": {
        "recipient": "user@example.com",
        "subject": "Your Lunch Recommendations for Today",
        "body": "{{input}}"
      }
    }
  ],
  "routes": [
    {"from": "start", "to": "find-restaurants"},
    {"from": "find-restaurants", "to": "format-recommendations"},
    {"from": "format-recommendations", "to": "send-email"},
    {"from": "send-email", "to": "end"}
  ]
}
```

--------------------------------

### Get Execution Status

Source: https://context7.com/avoguru/not7-core/llms.txt

Retrieves the status and details of a specific agent execution by its ID.

```APIDOC
## GET /api/v1/executions/{id}

### Description
Retrieves the status and details of a specific agent execution using its unique identifier.

### Method
GET

### Endpoint
/api/v1/executions/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the execution to retrieve.

### Response
#### Success Response (200)
- **execution** (object) - An object containing details about the specified execution.
  - **id** (string) - The unique identifier for the execution.
  - **status** (string) - The current status of the execution (e.g., 'running', 'completed', 'failed').
  - **start_time** (string) - Timestamp when the execution started.
  - **end_time** (string) - Timestamp when the execution ended (if applicable).
  - **results** (any) - The results of the execution (format depends on the agent's output).

#### Response Example
```json
{
  "execution": {
    "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "status": "completed",
    "start_time": "2023-10-27T10:00:00Z",
    "end_time": "2023-10-27T10:05:00Z",
    "results": {
      "summary": "AI news summary..."
    }
  }
}
```
```

--------------------------------

### GET /api/v1/executions/{execution_id} - Check Execution Status

Source: https://context7.com/avoguru/not7-core/llms.txt

Retrieve the status and details of a previously initiated agent execution using its unique execution ID.

```APIDOC
## GET /api/v1/executions/{execution_id} - Check Execution Status

### Description
Retrieve the status and details of a previously initiated agent execution using its unique execution ID.

### Method
GET

### Endpoint
`/api/v1/executions/{execution_id}`

### Parameters
#### Path Parameters
- **execution_id** (string) - Required - The unique identifier of the execution to check.

### Request Example
```bash
curl http://localhost:8080/api/v1/executions/exec_abc123def456
```

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the execution.
- **status** (string) - The current status of the execution (e.g., "success", "running", "failed").
- **goal** (string) - The goal of the execution.
- **created_at** (string) - Timestamp when the execution was created.
- **started_at** (string) - Timestamp when the execution started.
- **ended_at** (string) - Timestamp when the execution ended (if applicable).

#### Response Example
```json
{
  "id": "exec_abc123def456",
  "status": "success",
  "goal": "Generate a creative poem about AI agents",
  "created_at": "2025-10-25T10:30:00Z",
  "started_at": "2025-10-25T10:30:01Z",
  "ended_at": "2025-10-25T10:30:04Z"
}
```
```

--------------------------------

### Building from Source: NOT7 Core (Bash)

Source: https://github.com/avoguru/not7-core/blob/main/README.md

Instructions for building the NOT7 Core executable from source using Make. It covers cloning the repository, setting up the configuration file, and running the build command. It also includes how to build for all platforms.

```bash
git clone https://github.com/not7/core.git
cd core
cp not7.conf.example not7.conf
# Edit not7.conf with your API key
make build
./not7 run examples/poem-generator.json
```

```bash
make build-all
```

--------------------------------

### Initialize and Execute Tools in Go

Source: https://context7.com/avoguru/not7-core/llms.txt

Demonstrates how to register tool providers and programmatically execute tools within a Go application. It covers loading configuration, creating a tool manager, initializing built-in providers like web search, registering providers, and executing tools with specified arguments. Error handling for initialization and execution is included.

```go
package main

import (
    "context"
    "fmt"
    "time"
    "github.com/not7/core/tools"
    "github.com/not7/core/tools/builtin"
    "github.com/not7/core/config"
)

func main() {
    // Load configuration
    cfg := config.Get()

    // Create tool manager
    toolMgr := tools.NewManager("default-user")

    // Initialize built-in provider (web search)
    builtinProvider := builtin.NewProvider(cfg.Builtin.SerpAPIKey)
    providerConfig := map[string]string{
        "serp_api_key": cfg.Builtin.SerpAPIKey,
    }

    if err := builtinProvider.Initialize(providerConfig); err != nil {
        panic(fmt.Errorf("failed to initialize builtin provider: %w", err))
    }

    // Register provider
    if err := toolMgr.RegisterProvider(builtinProvider); err != nil {
        panic(fmt.Errorf("failed to register provider: %w", err))
    }

    fmt.Printf("Registered %d tools\n", len(toolMgr.ListTools()))

    // Execute a web search tool
    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
    defer cancel()

    arguments := map[string]interface{}{
        "query": "best mirrorless cameras 2025",
        "num_results": 5,
    }

    result, err := toolMgr.ExecuteTool(ctx, "WebSearch", arguments)
    if err != nil {
        panic(fmt.Errorf("tool execution failed: %w", err))
    }

    if result.Success {
        fmt.Printf("Search results: %v\n", result.Output)
    } else {
        fmt.Printf("Tool error: %s\n", result.Error)
    }
}
```

--------------------------------

### Build NOT7 Binary for Multiple Platforms

Source: https://context7.com/avoguru/not7-core/llms.txt

Instructions for compiling the NOT7 binary for different operating systems and architectures (macOS, Linux, Windows). This involves cloning the repository, downloading Go dependencies, and using make targets to build for current or all platforms.

```bash
# Clone repository
git clone https://github.com/not7/core.git
cd core

# Install dependencies
go mod download

# Build for current platform
make build
# Creates: ./not7

# Build for all platforms
make build-all
# Creates:
#   dist/not7-darwin-amd64    (macOS Intel)
#   dist/not7-darwin-arm64    (macOS Apple Silicon)
#   dist/not7-linux-amd64     (Linux x64)
#   dist/not7-linux-arm64     (Linux ARM)
#   dist/not7-windows-amd64.exe (Windows x64)
```

--------------------------------

### Load and Execute Go Agent Specification

Source: https://context7.com/avoguru/not7-core/llms.txt

This Go code snippet demonstrates how to load a JSON agent specification from a file, validate its structure, create an executor, and then run the agent with an initial input. It also shows how to access execution metadata like duration and cost. Dependencies include the 'github.com/not7/core/spec' and 'github.com/not7/core/executor' packages.

```go
package main

import (
    "fmt"
    "github.com/not7/core/spec"
    "github.com/not7/core/executor"
)

func main() {
    // Load agent specification from JSON file
    agentSpec, err := spec.LoadSpec("examples/camera-research.json")
    if err != nil {
        panic(fmt.Errorf("failed to load spec: %w", err))
    }

    // Validate specification structure
    if err := spec.ValidateSpec(agentSpec); err != nil {
        panic(fmt.Errorf("invalid spec: %w", err))
    }

    // Create executor with CLI output
    exec, err := executor.NewExecutor(agentSpec)
    if err != nil {
        panic(fmt.Errorf("failed to create executor: %w", err))
    }

    // Execute agent with input
    output, err := exec.Execute("")
    if err != nil {
        panic(fmt.Errorf("execution failed: %w", err))
    }

    fmt.Printf("Final output: %s\n", output)

    // Access execution metadata
    metadata := exec.GetMetadata()
    fmt.Printf("Execution time: %dms\n", metadata.ExecutionTimeMs)
    fmt.Printf("Total cost: $%.4f\n", metadata.TotalCost)
}
```

--------------------------------

### Single Toolkit Configuration using Arcade Gmail

Source: https://github.com/avoguru/not7-core/blob/main/README.md

This JSON configuration demonstrates how to set up a single toolkit, specifically 'arcade-gmail', for a 'react' node. The node is enabled with tools and has a goal to send an email summarizing an analysis. It requires the 'arcade-gmail' provider to be configured.

```json
{
  "config": {
    "tools": {
      "provider": "arcade-gmail"
    }
  },
  "nodes": [{
    "type": "react",
    "tools_enabled": true,
    "react_goal": "Send an email summarizing the analysis"
  }]
}
```

--------------------------------

### Integrate NOT7 Client Library in Go

Source: https://context7.com/avoguru/not7-core/llms.txt

Shows how to use the NOT7 client library to integrate NOT7 execution into Go applications. This involves creating an API client, checking server health, defining an agent specification (including LLM configuration and agent nodes/routes), submitting the agent for asynchronous execution, and polling for the execution status and results. It also demonstrates handling execution IDs and retrieving output and cost information.

```go
package main

import (
    "encoding/json"
    "fmt"
    "github.com/not7/core/client"
    "time"
)

func main() {
    // Create API client
    c := client.NewClient("http://localhost:8080")

    // Check server health
    if err := c.CheckHealth(); err != nil {
        panic(fmt.Errorf("server not available: %w", err))
    }

    // Define agent specification
    agent := map[string]interface{}{
        "version": "1.0.0",
        "goal": "Analyze sentiment of product reviews",
        "config": map[string]interface{}{
            "llm": map[string]interface{}{
                "provider": "openai",
                "model": "gpt-3.5-turbo",
            },
        },
        "nodes": []map[string]interface{}{
            {
                "id": "analyze",
                "name": "Sentiment Analyzer",
                "type": "llm",
                "prompt": "Analyze the sentiment of these reviews and provide a summary: {{input}}",
            },
        },
        "routes": []map[string]interface{}{
            {"from": "start", "to": "analyze"},
            {"from": "analyze", "to": "end"},
        },
    }

    agentJSON, _ := json.Marshal(agent)

    // Execute agent asynchronously
    result, err := c.RunAgent(agentJSON, true, false)
    if err != nil {
        panic(err)
    }

    execID := result["execution_id"].(string)
    fmt.Printf("Submitted execution: %s\n", execID)

    // Poll for completion
    for {
        time.Sleep(2 * time.Second)

        exec, err := c.GetExecution(execID)
        if err != nil {
            panic(err)
        }

        status := exec["status"].(string)
        fmt.Printf("Status: %s\n", status)

        if status == "success" || status == "failed" {
            if output, ok := exec["output"]; ok {
                fmt.Printf("\nOutput:\n%s\n", output)
            }
            if totalCost, ok := exec["total_cost"]; ok {
                fmt.Printf("Cost: $%.4f\n", totalCost)
            }
            break
        }
    }
}
```

--------------------------------

### Load and Execute Agent Specification (Programmatic)

Source: https://context7.com/avoguru/not7-core/llms.txt

This Go code demonstrates how to load an agent specification from a JSON file, validate it, and then execute it using the NOT7 runtime engine. It also shows how to access execution metadata like time and cost.

```APIDOC
## Load and Execute Agent Specification (Programmatic)

### Description
This Go code demonstrates how to load an agent specification from a JSON file, validate it, and then execute it using the NOT7 runtime engine. It also shows how to access execution metadata like time and cost.

### Method
Programmatic execution within a Go application.

### Endpoint
N/A (In-process execution)

### Parameters
N/A

### Request Example
```go
package main

import (
    "fmt"
    "github.com/not7/core/spec"
    "github.com/not7/core/executor"
)

func main() {
    // Load agent specification from JSON file
    agentSpec, err := spec.LoadSpec("examples/camera-research.json")
    if err != nil {
        panic(fmt.Errorf("failed to load spec: %w", err))
    }

    // Validate specification structure
    if err := spec.ValidateSpec(agentSpec); err != nil {
        panic(fmt.Errorf("invalid spec: %w", err))
    }

    // Create executor with CLI output
    exec, err := executor.NewExecutor(agentSpec)
    if err != nil {
        panic(fmt.Errorf("failed to create executor: %w", err))
    }

    // Execute agent with input
    output, err := exec.Execute("")
    if err != nil {
        panic(fmt.Errorf("execution failed: %w", err))
    }

    fmt.Printf("Final output: %s\n", output)

    // Access execution metadata
    metadata := exec.GetMetadata()
    fmt.Printf("Execution time: %dms\n", metadata.ExecutionTimeMs)
    fmt.Printf("Total cost: $%.4f\n", metadata.TotalCost)
}
```

### Response
N/A (Execution output and metadata are printed to stdout and returned as Go variables.)
```

--------------------------------

### Run Agent via CLI and API

Source: https://context7.com/avoguru/not7-core/llms.txt

Demonstrates how to execute agents using the NOT7 command-line interface and its HTTP API. The CLI is useful for local development and testing, while the API is suited for production deployments. Both methods take agent definitions as JSON input.

```bash
# Execute agent via CLI
./not7 run examples/camera-research.json

# Execute agent via API using curl
curl -X POST http://localhost:8080/api/v1/run -d @examples/poem-generator.json
```

--------------------------------

### Execute Deployed Agent

Source: https://github.com/avoguru/not7-core/blob/main/README.md

Initiates the execution of a previously deployed agent identified by its ID.

```APIDOC
## POST /api/v1/agents/{id}/run

### Description
Executes a deployed agent.

### Method
POST

### Endpoint
/api/v1/agents/{id}/run

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the agent to execute.

### Response
#### Success Response (200)
- **result** (object) - The output and execution details of the agent run.

#### Response Example
```json
{
  "output": "The generated poem...",
  "execution_time_ms": 2850,
  "total_cost_usd": 0.0275
}
```
```

--------------------------------

### API Reference: Deploy and Manage Agents (Bash)

Source: https://github.com/avoguru/not7-core/blob/main/README.md

This section outlines the bash commands using curl to interact with the NOT7 REST API for deploying, listing, retrieving, updating, and deleting agents. It demonstrates how to send JSON payloads for agent specifications.

```bash
POST /api/v1/agents
Content-Type: application/json

{
  "id": "my-agent",
  "version": "1.0.0",
  "goal": "Do something",
  "nodes": [...],
  "routes": [...] 
}
```

```bash
GET /api/v1/agents
```

```bash
GET /api/v1/agents/{id}
```

```bash
PUT /api/v1/agents/{id}
Content-Type: application/json

{ ...updated agent spec... }
```

```bash
DELETE /api/v1/agents/{id}
```

--------------------------------

### Deploy Agent

Source: https://github.com/avoguru/not7-core/blob/main/README.md

Deploys an agent specification to the NOT7 server without executing it. This makes the agent available for later execution.

```APIDOC
## POST /api/v1/agents

### Description
Deploys an agent specification. The agent is stored and can be executed later.

### Method
POST

### Endpoint
/api/v1/agents

### Parameters
#### Request Body
- **id** (string) - Required - A unique identifier for the agent.
- **version** (string) - Required - The version of the agent specification.
- **goal** (string) - Required - The primary objective of the agent.
- **nodes** (array) - Required - An array of node definitions for the agent's workflow.
- **routes** (array) - Required - An array defining the flow between nodes.

### Request Example
```json
{
  "id": "my-agent",
  "version": "1.0.0",
  "goal": "Do something",
  "nodes": [...],
  "routes": [...] 
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating successful deployment.

#### Response Example
```json
{
  "message": "Agent 'my-agent' deployed successfully."
}
```
```

--------------------------------

### Execute Agent

Source: https://context7.com/avoguru/not7-core/llms.txt

Executes an agent based on a provided JSON configuration.

```APIDOC
## POST /api/v1/run

### Description
Executes an agent defined in the request body. The agent's configuration should be provided as JSON.

### Method
POST

### Endpoint
/api/v1/run

### Parameters
#### Request Body
- **agent_config** (object) - Required - The JSON configuration for the agent to execute.

### Request Example
```json
{
  "agent_config": {
    "name": "example-agent",
    "steps": [
      {
        "name": "step1",
        "tool": "web_search",
        "input": "latest news about AI"
      }
    ]
  }
}
```

### Response
#### Success Response (200)
- **execution_id** (string) - The unique identifier for the executed agent run.

#### Response Example
```json
{
  "execution_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
}
```
```

--------------------------------

### API Reference: Execute Agents (Bash)

Source: https://github.com/avoguru/not7-core/blob/main/README.md

Provides bash commands for executing agents via the NOT7 REST API. It covers executing a pre-deployed agent using its ID and executing an anonymous agent by sending its JSON specification directly in the request body.

```bash
POST /api/v1/agents/{id}/run
```

```bash
POST /api/v1/agents/run
Content-Type: application/json

{ ...agent spec... }
```

--------------------------------

### List All Agents

Source: https://github.com/avoguru/not7-core/blob/main/README.md

Retrieves a list of all agents that have been deployed to the NOT7 server.

```APIDOC
## GET /api/v1/agents

### Description
Retrieves a list of all deployed agents.

### Method
GET

### Endpoint
/api/v1/agents

### Response
#### Success Response (200)
- **agents** (array) - An array of agent objects, each containing agent details.

#### Response Example
```json
{
  "agents": [
    {
      "id": "my-agent",
      "version": "1.0.0",
      "goal": "Do something"
    },
    {
      "id": "another-agent",
      "version": "2.1.0",
      "goal": "Perform another task"
    }
  ]
}
```
```

--------------------------------

### POST /api/v1/run - Execute Agent via REST API

Source: https://context7.com/avoguru/not7-core/llms.txt

Submit agent specifications for synchronous or asynchronous execution via HTTP. This endpoint accepts a JSON payload defining the agent's goal, configuration, nodes, and routes.

```APIDOC
## POST /api/v1/run - Execute Agent via REST API

### Description
Submit agent specifications for synchronous or asynchronous execution via HTTP. This endpoint accepts a JSON payload defining the agent's goal, configuration, nodes, and routes.

### Method
POST

### Endpoint
`/api/v1/run`

### Parameters
#### Query Parameters
- **async** (boolean) - Optional - If set to `true`, the execution will run in the background and the response will contain an `execution_id`.

#### Request Body
- **version** (string) - Required - The version of the agent specification.
- **goal** (string) - Required - The objective of the agent execution.
- **config** (object) - Optional - Configuration for the agent, including LLM provider, model, and temperature.
  - **llm** (object) - Optional - Language Model configuration.
    - **provider** (string) - Required - The LLM provider (e.g., "openai").
    - **model** (string) - Required - The LLM model to use (e.g., "gpt-4").
    - **temperature** (number) - Optional - The sampling temperature for the LLM.
- **nodes** (array) - Required - A list of nodes defining the agent's execution units.
  - **id** (string) - Required - Unique identifier for the node.
  - **name** (string) - Required - Human-readable name for the node.
  - **type** (string) - Required - Type of node (e.g., "llm", "tool", "react").
  - **prompt** (string) - Required (for llm nodes) - The prompt to send to the LLM.
- **routes** (array) - Required - Defines the workflow by specifying connections between nodes.
  - **from** (string) - Required - The source node or "start" of the route.
  - **to** (string) - Required - The destination node or "end" of the route.

### Request Example
```bash
# Synchronous execution - wait for completion
curl -X POST http://localhost:8080/api/v1/run \
  -H "Content-Type: application/json" \
  -d '{
    "version": "1.0.0",
    "goal": "Generate a creative poem about AI agents",
    "config": {
      "llm": {
        "provider": "openai",
        "model": "gpt-4",
        "temperature": 0.9
      }
    },
    "nodes": [
      {
        "id": "generate_poem",
        "name": "Poem Generator",
        "type": "llm",
        "prompt": "Write a creative 4-stanza poem about AI agents and their role in the future of technology."
      }
    ],
    "routes": [
      {"from": "start", "to": "generate_poem"},
      {"from": "generate_poem", "to": "end"}
    ]
  }'
```

### Response
#### Success Response (200)
**Synchronous Response:**
- **id** (string) - Unique identifier for the execution.
- **status** (string) - The final status of the execution (e.g., "success", "failed").
- **goal** (string) - The goal of the execution.
- **output** (string) - The final output of the agent.
- **duration_ms** (integer) - The execution duration in milliseconds.
- **total_cost** (number) - The total cost incurred during execution.
- **created_at** (string) - Timestamp when the execution was created.

**Asynchronous Response:**
- **execution_id** (string) - The ID of the background execution.
- **status** (string) - The initial status of the execution (e.g., "running").
- **message** (string) - A message indicating the execution has started.

#### Response Example
**Synchronous:**
```json
{
  "id": "",
  "status": "success",
  "goal": "Generate a creative poem about AI agents",
  "output": "[Generated poem text...]",
  "duration_ms": 2850,
  "total_cost": 0.0275,
  "created_at": "2025-10-25T10:30:00Z"
}
```

**Asynchronous:**
```json
{
  "execution_id": "exec_abc123def456",
  "status": "running",
  "message": "Execution started in background"
}
```
```

--------------------------------

### Execute Anonymous Agent

Source: https://github.com/avoguru/not7-core/blob/main/README.md

Executes an agent directly from its specification without deploying it first. This is useful for testing or one-off runs.

```APIDOC
## POST /api/v1/agents/run

### Description
Executes an agent directly from its specification without prior deployment.

### Method
POST

### Endpoint
/api/v1/agents/run

### Parameters
#### Request Body
- **agent spec** (object) - Required - The full specification of the agent to execute.

### Request Example
```json
{
  "version": "1.0.0",
  "goal": "Generate a poem about AI agents",
  "config": {
    "llm": {
      "provider": "openai",
      "model": "gpt-4",
      "temperature": 0.9
    }
  },
  "nodes": [
    {
      "id": "generate_poem",
      "type": "llm",
      "prompt": "Write a creative poem about AI agents...",
      "output_format": "text"
    }
  ],
  "routes": [
    {"from": "start", "to": "generate_poem"},
    {"from": "generate_poem", "to": "end"}
  ]
}
```

### Response
#### Success Response (200)
- **result** (object) - The output and execution details of the agent run.

#### Response Example
```json
{
  "output": "The generated poem...",
  "execution_time_ms": 2850,
  "total_cost_usd": 0.0275
}
```
```