Agentic Workers

An agentic worker is an LLM-driven Plan → Act → Observe loop with tools, exposed to a flow as a single node. Instead of hand-wiring every step, you give the worker a goal (system prompt) and a set of tools; the model decides which tools to call, observes the results, and keeps going until it can answer.

This guide shows how to build one by hand and run it end to end. (Code identifiers use dw_* / dw.agent — the runtime name for what the product calls an “Agentic Worker”.)

A worker comes in one of three shapes — see Agent Types for single_turn (this guide), agent_graph, and deep_worker. Workers can also carry memory and a knowledge corpus.

The pipeline

 Designer / by hand        Packaging            Runtime (gtc start)
┌──────────────────┐   ┌───────────────┐   ┌──────────────────────────┐
│ AgentConfig       │   │ worker → pack │   │ flow .ygtc                │
│  + tool extension │ → │ tools → .gtxpack │ → │  └ dw.agent node          │
│  + a flow         │   │               │   │     └ AgentRuntime loop    │
└──────────────────┘   └───────────────┘   │        LLM ⇄ tools         │
                                            └──────────────────────────┘

A worker has three pieces:

1. An AgentConfig — the system prompt, the allowed tools, the LLM provider/model, limits, and optional guardrails, memory, and knowledge blocks.
2. Its tools — either a .gtxpack design-extension (the same format as component-tavily-ext), discovered at runtime, or an MCP server registered for the tenant.
3. A flow with a single dw.agent node that hands user messages to the worker.

Tools are extensions or MCP servers, not flow-node components

A worker’s tools come from .gtxpack design-extensions (from GREENTIC_EXTENSIONS_DIR/design/) or from MCP servers registered for the tenant — not from the greentic:component/component@0.6.0 flow-node components run by component.exec. Adding a capability to a flow-node component’s describe() does not make it an agent tool.

1. The agent config

The worker’s behaviour is one JSON document (schema: greentic-aw-runtime’s AgentConfig). Save it as <agent_id>.json in GREENTIC_AGENT_MANIFESTS_DIR (default ~/.greentic/agents):

tx-network-assistant.json

{
  "agent_id": "tx-network-assistant",
  "system_prompt": "You are a read-only network operations assistant. Resolve an entity (prefix, device) before analysing it, then call the matching analysis tool. Never invent data; if a tool returns found=false, ask the user to clarify.",
  "tools": [
    { "extension_id": "greentic.telco-x-tools", "tool_name": "tx_resolve_prefix" },
    { "extension_id": "greentic.telco-x-tools", "tool_name": "tx_analyse_top_source_asns" }
  ],
  "llm": { "provider": "openai", "model": "gpt-4o-mini" },
  "limits": { "max_iter": 8 }
}

• tools[] is the allow-list: extension_id is a loaded extension’s id, tool_name is one of its tools. Only listed tools are exposed to the model.
• limits.max_iter bounds the loop (default 8) — enough for multi-step resolve-then-analyse investigations.
• llm accepts any greentic-llm provider — openai, anthropic, deepseek, gemini, and the others — as { "provider": "...", "model": "...", "credential_ref": "..." }. Use credential_ref to name a stored credential instead of relying on an environment variable.
• The config also supports optional guardrails (see below), memory, and knowledge blocks. Omit them to start simple.

Spell out tool arguments in the prompt

At the current runtime, extension tools reach the model by name with an empty argument schema, so the model learns each tool’s arguments from your system prompt. List each tool’s exact JSON arguments there (e.g. tx_resolve_prefix: {"query": "<prefix>"}).

2. The tool extension

Package your tools as a design-extension .gtxpack. The quickest start is to copy component-tavily-ext and replace the tool logic. Each tool must declare the agentic_worker capability in its tool_meta:

ToolMeta {
    name: "tx_resolve_prefix",
    description: "Resolve a network prefix to its canonical id.",
    input_schema_json: RESOLVE_PREFIX_INPUT,
    output_schema_json: RESOLVE_PREFIX_OUTPUT,
    capabilities: vec!["agentic_worker".into()],   // ← required to be an agent tool
    agentic_worker_metadata: RESOLVE_PREFIX_AW_META,
}

Build and stage it where the runtime discovers extensions:

bash build.sh    # → greentic.telco-x-tools-1.0.0.gtxpack
# Stage into the design kind-dir the runtime scans at boot:
unzip -o greentic.telco-x-tools-1.0.0.gtxpack \
  -d "$GREENTIC_EXTENSIONS_DIR/design/greentic.telco-x-tools"

Signing

A default runner loads only signed extensions. For local development with an unsigned extension, set GREENTIC_EXT_ALLOW_UNSIGNED=1 and use a runner built with the dev-allow-unsigned feature.

3. The flow

A dw.agent node maps the inbound message to user_text and routes the reply back. The node key is dw.agent.<agent_id>:

flows/network_assistant_flow.ygtc

id: network_assistant_flow
title: Network Assistant
type: messaging
schema_version: 2
start: ask_agent

nodes:
  ask_agent:
    dw.agent.tx-network-assistant:        # component=dw.agent, operation=agent_id
      input:
        mapping: '{"user_text": "{{in.text}}"}'
    routing: reply

• Input contract: the node payload must contain user_text.
• Output contract: the worker returns { reply, trail, terminated_by }; routing: reply sends reply back over the inbound channel.

4. Run it

The runtime needs a state backend (in-memory by default — no Redis required), an LLM key, and the extension + manifest staged:

# State backend is optional: unset → in-memory (ephemeral). For durability use
# `export GREENTIC_AW_STATE_BACKEND=disk` (on-disk redb) or point at Redis for
# multi-instance state: `export GREENTIC_AW_REDIS_URL=redis://127.0.0.1:6379`
export OPENAI_API_KEY=sk-...                 # or GREENTIC_LLM_API_KEY
export GREENTIC_EXTENSIONS_DIR=~/.greentic/extensions
export GREENTIC_AGENT_MANIFESTS_DIR=~/.greentic/agents

gtc start ./my-bundle --cloudflared off --nats on

A message arrives → the flow routes it to the dw.agent node → AgentRuntime::step(tenant, session, agent_id, text) runs the loop → the reply goes back to the user. A typical two-step investigation:

USER:  What are the top source ASNs for prefix 10.0.0.0/8?
 turn 1: model calls tx_resolve_prefix{"query":"10.0.0.0/8"}  → {prefix_id: "px-core-10-8"}
 turn 2: model calls tx_analyse_top_source_asns{"prefix_id":"px-core-10-8"} → ranked ASNs
 turn 3: model writes the final answer
WORKER: The top source ASNs for 10.0.0.0/8 are: AS15169 (Google) 4.2 Gbps (38.1%), …

Guardrails

A worker can run guardrails — content-safety hooks that fire on every step at two points: inbound (the user prompt, before the LLM sees it) and outbound (the LLM reply, before it reaches the caller). Each guardrail returns one of three verdicts — accept (pass through), update (replace with masked/rewritten content), or deny (block with a structured payload). Guardrails are chained in order; an update feeds the modified content to the next guardrail.

Declare agent-level guardrails in AgentConfig.guardrails by capability id, e.g.:

"guardrails": ["greentic:guardrail/pii"]

Agent-level guardrails fail open (skipped if unresolvable); platform/tenant mandatory guardrails injected by policy fail closed (block if unresolvable). Each guardrail is a design extension implementing greentic:extension-design/guardrail@0.3.0. See Guardrail Extensions for authoring and the reference component-guardrail-pii implementation.

Worked example

A complete, runnable agentic worker lives in the Telco-X solution repo under bundles/agentic-network-assistant/ (worker config, a four-tool extension in extensions/network-tools-ext/, the flow, and a run.sh that stages everything). Its docs/agentic-workers-integration.md walks through the same pieces with file references.

Reference

Variable	Purpose
GREENTIC_AW_STATE_BACKEND	State backend: redis | memory | disk. Unset → redis if GREENTIC_AW_REDIS_URL is set, else memory (ephemeral). memory/disk = single-process locking only.
GREENTIC_AW_STATE_PATH	On-disk (redb) path when GREENTIC_AW_STATE_BACKEND=disk (default ~/.greentic/aw-state.redb).
GREENTIC_AW_REDIS_URL	Optional. Redis worker conversation state + idempotency for durable / multi-instance state. Unset → in-memory backend (worker still runs).
GREENTIC_LLM_API_KEY / OPENAI_API_KEY	LLM credential.
GREENTIC_LLM_PROVIDER / GREENTIC_LLM_MODEL	Override provider/model.
GREENTIC_EXTENSIONS_DIR	Tool-extension discovery root (scans <root>/design/).
GREENTIC_AGENT_MANIFESTS_DIR	<agent_id>.json config dir.
GREENTIC_EXT_ALLOW_UNSIGNED	Allow unsigned extensions (dev only; needs the dev feature).

Note

The runner must be built with the agentic-worker feature (on by default). Without it, dw.agent nodes fail with a clear “compiled without the agentic-worker feature” error.