Welt

A Slack frontend for AI agents on Amazon Bedrock AgentCore.

Welt forwards conversations to your agent on AgentCore and streams the reply back into the Slack thread.

You focus on the agent — model, tools, MCP, memory. Welt handles the Slack side — tokens, event intake, history fetch, streaming rendering, and uploading the files your agent generates.

The pieces line up like this:

Slack ⇄ Welt ⇄ AgentCore Runtime
└── your agent, using an adapter for Welt's JSON wire

Adapters exist for several agent frameworks, in Python and TypeScript — see Agent-Side Adapters. The Quick Start below runs welt-io-strands's example agent.

Quick Start

The Quick Start runs everything on your machine — Welt in one terminal, the example agent in another. Nothing is deployed; the only AWS dependency is the Bedrock model the agent calls. Deployment comes after, once the conversation works — see Deployment.

1. Create a Slack App

• Go to https://api.slack.com/apps and create a new Slack app from manifest.yml — or open the pre-filled creation screen to skip the copy and paste.
• In Basic Information > App-Level Tokens, generate a token with the connections:write scope and copy it (xapp-1-...).
• In Install App, install the app to your workspace and copy the Bot User OAuth Token (xoxb-...).

2. Get the Code and Create a .env File

Clone this repository:

git clone https://github.com/iwamot/welt.git
cd welt

Then save your Slack tokens in a .env file at the repository root (.env.sample lists all supported variables):

SLACK_APP_TOKEN=xapp-1-...
SLACK_BOT_TOKEN=xoxb-...

With no AGENT_ARN set, Welt runs in local mode: it forwards conversations to the agent at http://localhost:8080.

3. Run Welt

Run Welt with uv:

uv run --env-file .env main.py

It connects to Slack and waits. In local mode Welt itself needs no AWS credentials — the agent process is the one calling AWS.

4. Run the Example Agent

In another terminal, run welt-io-strands's example agent by following its README's Run Locally section; it serves on http://localhost:8080, where Welt is pointing. (The other adapters' example agents work just as well here.)

5. Say Hello!

Invite the bot to a channel (/invite @Welt) and mention it, or send it a DM. Welt streams the agent's reply into the thread; the example agent's README suggests things to try.

Deployment

The Quick Start keeps everything on your machine. For real use, the agent goes to AgentCore and Welt goes somewhere it keeps running.

The agent is one of two things:

• Your own, on AgentCore Runtime. Build it on one of the adapters, with its example agent as the reference — deploying that example as it is makes a fine start — and deploy it; each example's README has a Deploy section. AGENT_ARN is the agent runtime ARN.
• A managed harness, with no agent code at all. Create one in the AgentCore console; AGENT_ARN is its ARN.

Either way, restart Welt with AGENT_ARN set:

AGENT_ARN=arn:aws:bedrock-agentcore:...

Welt now picks up your AWS credentials the standard SDK way — environment variables, AWS_PROFILE, an SSO session — and that identity needs permission to invoke the target: bedrock-agentcore:InvokeAgentRuntime and bedrock-agentcore:InvokeAgentRuntimeForUser on a runtime agent (Welt sends the verified Slack user as the runtimeUserId), or bedrock-agentcore:InvokeHarness on a harness.

Welt then goes to one of two places, whichever the agent is:

• Running Welt as a Resident Process — Socket Mode, so no public URL is involved. Runs as a container on ECS or any host you already have.
• Running Welt on AWS Lambda — no always-on process, no cost while idle. Slack reaches it at a Function URL.

Features

• Files — file input from Slack uploads, and uploading the files your agent generates back into the thread.
• Interrupts — human-in-the-loop: a tool (or hook) that interrupts pauses the run and becomes buttons or a text field in the thread; the answer resumes it.

Agent-Side Adapters

The wire between Welt and the agent is plain JSON, and the Wire Contract is its full specification. Each adapter maps the wire to one framework's types and carries its own example agent:

Repository	Language	Framework	Package
welt-io-strands	Python	Strands Agents	welt-io-strands
welt-io-langgraph	Python	LangGraph	welt-io-langgraph
welt-io-openai-agents	Python	OpenAI Agents SDK	welt-io-openai-agents
welt-io-strands-ts	TypeScript	Strands Agents	@welt-io/strands
welt-io-mastra	TypeScript	Mastra	@welt-io/mastra
welt-io-openai-agents-ts	TypeScript	OpenAI Agents SDK	@welt-io/openai-agents

Other stacks can implement the contract directly.

Configuration

Optional environment variables, all with working defaults:

Variable	Default	Description
AGENT_ARN	(unset)	The AgentCore Runtime agent — or managed harness — to invoke, as its own ARN or as one of its endpoints' (.../runtime-endpoint/<name>, .../harness-endpoint/<name>); an endpoint ARN selects that endpoint, and an ARN naming none invokes the DEFAULT endpoint. Unset is local mode, for development: Welt invokes the agent at http://localhost:8080 instead.
AGENT_MANAGES_HISTORY	false	What Welt sends per turn: the full thread history (false), or only the new messages (true).
FILE_INPUT_MODALITIES	(unset)	Comma-separated modalities to accept from Slack uploads; unset disables file input. See Files.
LOG_LEVEL	INFO	Logging level for Welt's own loggers.
DEPS_LOG_LEVEL	INFO	Logging level for dependency libraries (botocore, slack_bolt, ...). Separate from LOG_LEVEL because botocore logs credential material at DEBUG.
SLACK_STREAM_BUFFER_SIZE	256	Markdown characters buffered before each streaming update; larger values mean fewer Slack API calls.

Contributing

Contributions are welcome! Please see our Contributing Guide for details.

Related Projects

• iwamot/collmbo — A Slack bot for chatting with 100+ LLMs directly, no AI agent to implement or deploy. Pick Collmbo for plain LLM chat, Welt for your own agent.

License

MIT