ZeroRoot Docs

Your First Agent

Build a Gibson agent with the SDK, the Agent contract, the Harness, and a working hello-world example.

An agent is the autonomous reasoning layer of a Gibson mission. It decides what to do next, calls tools, queries the knowledge graph, and submits findings. Gibson runs your agent inside a mission alongside any other agents, tools, and plugins the mission references.

This page shows how to write an agent from scratch with the Gibson SDK.

Prerequisites

  • You completed Install, and gibson inspect returns successfully for a registered agent identity.
  • Go 1.26+ (the ADK pins the exact version in its gibson/go.mod).

If you have not enrolled an agent yet, do that first. gibson agent enroll --name <name> --kind agent mints a bootstrap token. Set GIBSON_URL and GIBSON_BOOTSTRAP_TOKEN, then start the agent. The first start exchanges the token for the runtime credential the SDK needs.

What an agent looks like

In the SDK, an agent is anything that satisfies the agent.Agent contract from github.com/zeroroot-ai/sdk/agent. Do not write the struct by hand. Use the builder:

cfg := agent.NewConfig().
    SetName("my-agent").
    SetVersion("0.1.0").
    SetDescription("…").
    SetTargetTypes([]string{"web_app"}).
    SetExecuteFunc(execute)

a, err := agent.New(cfg)

What the fields mean:

FieldPurpose
NameUnique within your tenant. Mission nodes refer to your agent by name.
VersionSemantic version. Useful for canarying upgrades.
DescriptionHuman-readable purpose. Shown in the dashboard.
TargetTypesThe shape of system this agent works against ("web_app", "k8s_cluster", "llm_chat").
SetExecuteFuncThe actual work. See below.

The Harness

Your agent never talks to Gibson directly. It calls agent.Harness, which is the view of the platform for the agent. Gibson passes the harness into Execute. The harness exposes everything an agent might need:

You want to…Use
Call an LLMh.Complete, h.CompleteWithTools, h.Stream, h.CompleteStructured
Call a toolh.CallToolProto, h.CallToolProtoStream, h.QueueToolWork, h.ToolResults
Query a pluginh.QueryPlugin, h.ListPlugins
Hand a subtask to another agenth.DelegateToAgent, h.ListAgents
Persist a security findingh.SubmitFinding, h.GetFindings
Read the knowledge graphh.QueryNodes, h.FindSimilarAttacks, h.FindSimilarFindings, h.GetAttackChains
Report what the agent saw into the Worldh.Observe
Keep a fact across runsh.Observe with an agent.MemoryObservation
See the mission's target and metadatah.Mission(), h.Target()
Spawn a sub-missionh.CreateMission, h.RunMission
Read or write a workspace fileh.Workspace(), h.Workspaces()
Extra authz check before a sensitive oph.Authorize(ctx, action, resource)

An LLM slot is a name. The agent names it in the call, for example h.Complete(ctx, "primary", messages). The platform maps each slot name to a provider and a model of your tenant at dispatch time. See Observability for cost and latency metrics.

A complete hello-world

package main

import (
    "context"
    "log"

    sdk "github.com/zeroroot-ai/sdk"
    "github.com/zeroroot-ai/sdk/agent"
    "github.com/zeroroot-ai/sdk/llm"
)

func execute(ctx context.Context, h agent.Harness, t agent.Task) (agent.Result, error) {
    resp, err := h.Complete(ctx, "primary", []llm.Message{
        {Role: llm.RoleSystem, Content: "You greet people warmly in one sentence."},
        {Role: llm.RoleUser, Content: t.Goal},
    })
    if err != nil {
        return agent.Result{Status: agent.StatusFailed, Output: err.Error()}, nil
    }
    return agent.Result{Status: agent.StatusSuccess, Output: resp.Content}, nil
}

func main() {
    cfg := agent.NewConfig().
        SetName("hello-agent").
        SetVersion("0.1.0").
        SetDescription("Says hi via the primary LLM slot.").
        SetTargetTypes([]string{"none"}).
        SetExecuteFunc(execute)

    a, err := agent.New(cfg)
    if err != nil {
        log.Fatal(err)
    }

    if err := sdk.ServeAgent(a); err != nil {
        log.Fatal(err)
    }
}

sdk.ServeAgent reads GIBSON_URL and GIBSON_BOOTSTRAP_TOKEN, connects to your tenant, registers the agent, and waits for missions to dispatch work.

Run the agent

go run .

Leave the process running. In the Missions section of the dashboard, add a node that points at the name of your agent. Click Run. The mission detail page streams events as your agent works. See Missions for the full event taxonomy.

A more realistic example

This bug-bounty triage agent calls a tool, asks the LLM for a structured plan, and submits a finding for each item that the plan flags:

// triagePlan is the structured output that the LLM fills in.
type triagePlan struct {
    Flag []struct {
        Title       string `json:"title"`
        Severity    string `json:"severity"`
        Description string `json:"description"`
        Evidence    string `json:"evidence"`
    } `json:"flag"`
}

func execute(ctx context.Context, h agent.Harness, t agent.Task) (agent.Result, error) {
    target := h.Target()

    // 1. Run a port scan tool that you enrolled before. In this example
    //    the target name is the host name.
    scan := &portscanv1.Response{}
    if err := h.CallToolProto(ctx, "port-scan", &portscanv1.Request{Host: target.Name}, scan); err != nil {
        return failed(err), nil
    }

    // 2. Ask the LLM what to flag. The reply is JSON data, so decode it
    //    into the plan struct.
    out, err := h.CompleteStructured(ctx, "primary", []llm.Message{
        {Role: llm.RoleSystem, Content: "Triage the scan output. Decide what to flag."},
        {Role: llm.RoleUser, Content: prototext.Format(scan)},
    }, triagePlan{})
    if err != nil {
        return failed(err), nil
    }
    raw, err := json.Marshal(out)
    if err != nil {
        return failed(err), nil
    }
    var plan triagePlan
    if err := json.Unmarshal(raw, &plan); err != nil {
        return failed(err), nil
    }

    // 3. Submit a finding for each flagged item.
    for _, item := range plan.Flag {
        if err := h.SubmitFinding(ctx, &finding.Finding{
            Title:       item.Title,
            Severity:    finding.Severity(item.Severity),
            Description: item.Description,
            TargetID:    target.ID,
            Evidence: []finding.Evidence{
                {Type: finding.EvidenceLog, Title: "port scan", Content: item.Evidence},
            },
        }); err != nil {
            return failed(err), nil
        }
    }
    return agent.Result{Status: agent.StatusSuccess, Output: "triage complete"}, nil
}

func failed(err error) agent.Result {
    return agent.Result{Status: agent.StatusFailed, Output: err.Error()}
}

Their own pages explain tools, plugins, and the graph: Tools, Plugins, Knowledge graph.

Next steps

  • Tools: define and call a tool from your agent.
  • Findings: what SubmitFinding does and how findings appear in the dashboard.
  • Knowledge graph: query and write the graph from inside an agent.
  • Missions: chain your agent with other components in a DAG.
  • Taxonomy and Ontology: extend the type system with custom node types or industry-vocab mappings for your component.

On this page