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 inspectreturns 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:
| Field | Purpose |
|---|---|
Name | Unique within your tenant. Mission nodes refer to your agent by name. |
Version | Semantic version. Useful for canarying upgrades. |
Description | Human-readable purpose. Shown in the dashboard. |
TargetTypes | The shape of system this agent works against ("web_app", "k8s_cluster", "llm_chat"). |
SetExecuteFunc | The 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 LLM | h.Complete, h.CompleteWithTools, h.Stream, h.CompleteStructured |
| Call a tool | h.CallToolProto, h.CallToolProtoStream, h.QueueToolWork, h.ToolResults |
| Query a plugin | h.QueryPlugin, h.ListPlugins |
| Hand a subtask to another agent | h.DelegateToAgent, h.ListAgents |
| Persist a security finding | h.SubmitFinding, h.GetFindings |
| Read the knowledge graph | h.QueryNodes, h.FindSimilarAttacks, h.FindSimilarFindings, h.GetAttackChains |
| Report what the agent saw into the World | h.Observe |
| Keep a fact across runs | h.Observe with an agent.MemoryObservation |
| See the mission's target and metadata | h.Mission(), h.Target() |
| Spawn a sub-mission | h.CreateMission, h.RunMission |
| Read or write a workspace file | h.Workspace(), h.Workspaces() |
| Extra authz check before a sensitive op | h.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
SubmitFindingdoes 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.
Getting Started
Start your first Gibson agent in under an hour. Sign up, install the gibson CLI, sign in with the device flow, enroll, build, and run a mission.
Component bootstrap & auth
How agents, tools, and plugins authenticate against Gibson, the one enrollment path, the per-call protocol, and where to look when a 401 lands.