Skip to content
Auwgent

Intents Payloads

This page is the practical payload map.

If you are wiring handlers and you want to know “what exactly will I receive?”, this is that reference.

The key idea: intent names are the same across both SDKs. The payload shape is also the same at runtime. What differs is how each language presents and types that payload.

First, one quick mental model

Section titled “First, one quick mental model”

Think of every callback as:

  • intent name + payload + agent name

In TypeScript, callback style is typically:

agent.onIntent((name, value, agentName) => {
  // name = intent name
  // value = payload
  // agentName = current active agent/helper
})

In Python, class-based handlers receive payload + agent name, and the method name is the intent name:

class MyIntents(AuwgentBaseIntentHandler):
    async def response_text(self, intent, agent_name):
        ...

1) response_text

Section titled “1) response_text”

When the model returns normal text.

// onIntent payload
{
  text: "Hello from Auwgent"
}

2) response_schema

Section titled “2) response_schema”

When the model returns structured output.

// onIntent payload
{
  type: "MainOutput",   // schema/type name
  response: {
    title: "Weekly summary",
    score: 92
  }
}

3) tool_call

Section titled “3) tool_call”

When the model asks the engine to run a declared tool.

// onIntent payload
{
  type: "search_docs",
  args: {
    query: "intent payload shape"
  }
}

4) tool_result, tool_skipped, tool_error

Section titled “4) tool_result, tool_skipped, tool_error”

These are runtime outcomes for tool execution.

// tool_result
{
  name: "search_docs",
  args: { query: "intent payload shape" },
  result: { hits: 7 },
  overridden: false // optional
}


// tool_skipped
{
  type: "search_docs",
  args: { query: "intent payload shape" }
}


// tool_error
{
  tool: "search_docs",
  message: "Tool not found: search_docs"
}

5) workflow_call and workflow_result

Section titled “5) workflow_call and workflow_result”

Same pattern as tools.

// workflow_call
{
  type: "summarize_report",
  args: {
    reportId: "r-123"
  }
}


// workflow_result
{
  name: "summarize_report",
  args: {
    reportId: "r-123"
  },
  result: {
    status: "ok"
  }
}

6) helper_call and helper_result

Section titled “6) helper_call and helper_result”

Helpers follow the same call/result shape family.

// helper_call
{
  type: "ResearchHelper",
  args: {
    topic: "market analysis"
  }
}


// helper_result
{
  name: "ResearchHelper",
  args: {
    topic: "market analysis"
  },
  result: {
    summary: "..."
  }
}

7) error

Section titled “7) error”

Global engine/runtime error intent.

{
  message: "OpenAI API error (401): invalid key"
}

Partial payloads (onIntentPartial / on_intent_partial)

Section titled “Partial payloads (onIntentPartial / on_intent_partial)”

Partials are for streaming updates before final completion.

Shared envelope fields:

  • partial: true
  • complete: false
  • mode: "text" | "structured"
  • segment: number
  • snapshot: ...
  • raw: string

For text partials, a delta field is also available.

// response_text partial
{
  partial: true,
  complete: false,
  mode: "text",
  segment: 0,
  snapshot: { text: "Hello there" },
  raw: "Hello there",
  delta: " there"
}

Final note

Section titled “Final note”

When in doubt, route by intent name first, then validate expected payload fields for that name.

That gives you simple, reliable handler logic across both languages.