Beginner Cog Walkthrough

June 8, 2026 ยท View on GitHub

This guide continues after the direct Agent path works.

It runs a tiny no-memory Cog that does two things: summarize -> respond.

The example uses debug mode so you can prove the Cog wiring without provider credentials.

Start From A Scaffolded Project

Use a project that already has .agentforge/ from the Quickstart.

If you followed First Real Model Run, turn debug mode back on for deterministic output. Open .agentforge/settings/system.yaml and set:

debug:
  mode: true

The Cog File

The scaffold includes .agentforge/cogs/beginner_summary_cog.yaml:

cog:
  name: "BeginnerSummaryCog"
  description: "A tiny no-memory workflow that summarizes a user message and drafts a reply."
  chat_memory_enabled: false

  agents:
    - id: summarize
      description: "Summarizes the user message for the response node."
      template_file: beginner_summary_agent

    - id: respond
      description: "Writes the final beginner-friendly reply."
      template_file: beginner_response_agent

  flow:
    start: summarize
    transitions:
      summarize: respond
      respond:
        end: true

The agents list gives each node an ID, optional description metadata, and a prompt file under .agentforge/prompts/.

The flow starts with summarize, then moves directly to respond.

The respond transition uses end: true, so Cog.run(...) returns the response agent's output.

chat_memory_enabled: false keeps this first Cog independent from automatic chat history memory.

The Prompt Files

The summary agent reads the runtime input from _ctx.user_input:

prompts:
  system: |
    You summarize user messages for a response agent.

  user: |
    Summarize this user message in one sentence:
    {_ctx.user_input}

The response agent reads the original input and the first agent's output from _state.summarize:

prompts:
  system: |
    You write concise replies using a summary from another agent.

  user: |
    Original user message:
    {_ctx.user_input}

    Summary from the first agent:
    {_state.summarize}

    Write a friendly two-sentence answer.

In a Cog prompt, _ctx is the context passed to Cog.run(...), and _state stores earlier agent outputs by node ID. Structured agent outputs are available through _state when the prompt YAML uses parse_response_as; _ctx values are used as passed by the caller.

Run The Cog

Create run_beginner_cog.py in your project root:

from agentforge.cog import Cog

result = Cog("beginner_summary_cog").run(user_input="What can AgentForge help me build?")
print(result)

Run it:

python run_beginner_cog.py

With debug mode on, the final output should be:

AgentForge helps you compose agents into small workflows. This beginner Cog ran summarize -> respond and returned this final reply.

What To Notice

  • Cogs live under .agentforge/cogs/.
  • Cog agent nodes point at prompt YAML files under .agentforge/prompts/.
  • The first prompt uses _ctx.user_input from the Python call.
  • The second prompt uses _state.summarize from the first node.
  • This Cog has no branching, loops, memory nodes, personas, storage setup, custom Agent subclasses, or custom APIs.