Core Concepts

Tools

Tools are Python functions decorated with @tool that give agents the ability to take actions - querying APIs, running commands, fetching data, or interacting with external systems.

Basic tool:

from ncp import tool

@tool
def ping_device(ip_address: str, timeout: int = 5) -> dict:
    """Ping a network device and return the result."""
    ...

Async tool:

@tool
async def backup_device_config(device_ip: str, backup_type: str = "running") -> dict:
    """Asynchronously back up a device configuration."""
    ...

Best practices:

• Always provide a clear docstring - the LLM uses it to decide when to call the tool

• Use type hints for all parameters

• Return structured data (dict or list) where possible

• Handle errors gracefully within the tool

Agents

Agents combine an LLM with a set of tools to handle tasks autonomously. They are configured with a name, description, instructions, and a list of tools.

from ncp import Agent

agent = Agent(
    name="NetworkMonitorBot",
    description="AI assistant for network monitoring and diagnostics",
    instructions="You are a network operations assistant. Use available tools to diagnose and report on network health.",
    tools=[ping_device, get_interface_status, backup_device_config]
)

LLM configuration:

from ncp import LLMConfig

config = LLMConfig(
    model="gpt-oss-120b",
)

Project Structure

Every NCP SDK agent follows a standard project layout:

my-agent-project/
├── ncp.toml                  # Agent metadata and configuration
├── requirements.txt          # Python dependencies
├── apt-requirements.txt      # System-level dependencies
├── agents/
│   └── main_agent.py         # Agent definition
├── tools/
└── __init__.py