Skip to content

Commit fcd490e

Browse files
zimegClaude
andcommitted
docs: describe where the framework lives and what turns.py relies on
Co-Authored-By: Claude <svc-devxp-claude@slack-corp.com>
1 parent 21a03ed commit fcd490e

2 files changed

Lines changed: 7 additions & 6 deletions

File tree

‎AGENTS.md‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -40,9 +40,9 @@ CI runs ruff and pytest against each directory with a matrix in `.github/workflo
4040

4141
Three layers: **app.py** -> **listeners/** -> **agent/**.
4242

43-
- **`app.py`** starts Bolt's `AsyncApp` in Socket Mode and calls `register_listeners(app)`. **`app_oauth.py`** is the alternative entry point for OAuth over HTTP. Everything is async, so a long turn never holds up the stop button, an approval click, or another channel.
43+
- **`app.py`** starts Bolt's `AsyncApp` in Socket Mode and calls `register_listeners(app)`. **`app_oauth.py`** is the alternative entry point for OAuth over HTTP, where agent slash commands arrive at the manifest's `code_channels.slash_command_url`. Everything is async, so a long turn never holds up the stop button, an approval click, or another channel.
4444
- **`listeners/`** holds Bolt handlers only, grouped by Slack feature (`actions/`, `commands/`, `events/`). Each sub-package has a `register(app)` function.
45-
- **`agent/`** holds everything else: the agents and their prompts, one file per tool under `agent/tools/`, the turn handling, the session store, and command approvals.
45+
- **`agent/`** holds everything else: the agents and their prompts, one file per tool under `agent/tools/`, the turn handling, the sessions and the deps each run gets, and command approvals.
4646

4747
The flow: a mention or direct message outside a code channel runs a small routing agent that either replies in place or calls `create_code_channel`. Slack seeds the new channel with the request, and that mention starts the coding agent's first turn there, along with the conversation the request came from. Every later message, slash command, and approval in the channel runs a turn of the same session. Messages sent while a turn runs wait and go into the next turn together.
4848

@@ -51,10 +51,11 @@ The flow: a mention or direct message outside a code channel runs a small routin
5151
Implementations share structure, not code, so these parts are kept the same by copying them and changing them everywhere at once:
5252

5353
- **The seam between `listeners/` and `agent/`.** Listeners import only from the `agent` package, never from the agent framework, so `listeners/` is the same in every implementation. `agent/__init__.py` provides `answer_request`, `find_session`, `run_turn`, `resume_turn`, `stop_turn`, and `end_session`.
54-
- **Framework-free files.** `agent/turns.py`, `agent/context.py`, `agent/approvals.py`, `agent/sessions.py`, `agent/workspace.py`, and `agent/outcome.py` don't import the agent framework. The framework lives in `agent/agent.py` and `agent/tools/`. `turns.py` calls only `run_request(prompt, deps)`, `start_run(history, text, deps)`, and `resume_run(paused, approved, deps)`, which return the `RunOutcome` in `agent/outcome.py`. The paused run is a handle `turns.py` passes back without looking inside, so each framework's way of pausing fits behind it.
54+
- **Framework-free files.** `agent/turns.py`, `agent/context.py`, `agent/approvals.py`, `agent/sessions.py`, `agent/workspace.py`, `agent/outcome.py`, and `agent/prompts.py` don't import the agent framework. The framework lives in `agent/agent.py`, `agent/guardrails.py`, and `agent/tools/`. `turns.py` calls only `run_request(prompt, deps)`, which returns the reply text, and `start_run(history, text, deps)` and `resume_run(paused, approved, deps)`, which return the `RunOutcome` in `agent/outcome.py`. The paused run is a handle `turns.py` passes back without looking inside, so each framework's way of pausing fits behind it.
55+
- **What the framework side keeps true.** `turns.py` relies on these, so every implementation keeps them: `create_code_channel` sets `deps.code_channel_id`, and `archive_channel` sets `session.archived`. Every code channel tool skips its call once `session.stopped` is set. A paused run's history already records the pending command as not run, so `turns.py` can drop a paused run without resuming it. Beyond that, `turns.py` only checks whether `history` is empty, to know a turn is the first.
5556
- **Prompts.** `agent/prompts.py` is the same word for word in every implementation.
5657
- **Tools.** Every implementation offers the same tools with the same names, arguments, and descriptions, written with its framework's tool decorator. File tools stay inside the clone and can't write into `.git`.
57-
- **Command approvals.** `command_needs_approval(command)` is plain Python and the same in every implementation, wrapped in the framework's own approval hook. Read-only commands and local git changes run without asking. Anything that runs the repository's code or reaches outside the clone asks first. Commands run without a shell, so the check and the run split a command the same way.
58+
- **Command approvals.** `command_needs_approval(command)` is plain Python and the same in every implementation, wrapped in the framework's own approval hook. Read-only commands and local git changes run without asking. Anything that runs the repository's code or reaches outside the clone asks first. Commands run without a shell, so the check and the run split a command the same way. On Windows, `.cmd` and `.bat` programs like `npm` are the exception, since Windows runs them through `cmd.exe`.
5859
- **Tests.** Test files and names mirror each other, and `tests/test_runs.py` drives real agent runs with a scripted model to cover pausing, resuming, stopping, and running out of turns.
5960

6061
Refer to each implementation's README for its specifics.

‎openai-agents-sdk/AGENTS.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,13 +4,13 @@ Guidance for coding agents working in this directory. Refer to the root `../AGEN
44

55
## OpenAI Agents SDK specifics
66

7-
**Agents (`agent/agent.py`)** are two `Agent`s with pinned models: a routing `request_agent` (`gpt-6-luna`) whose only tool is `create_code_channel`, and the coding `agent` (`gpt-6.1-sol`) with every other tool. Tools are async `@function_tool` functions, one per file under `agent/tools/`, that read `RunContextWrapper[AgentDeps]` (or `RequestDeps`) for the Slack client and session. Both agents set `ModelSettings(truncation="auto")`, so a long session drops its oldest conversation instead of outgrowing the context window.
7+
**Agents (`agent/agent.py`)** are two `Agent`s with pinned models: a routing `request_agent` (`gpt-6-luna`) whose only tool is `create_code_channel`, and the coding `agent` (`gpt-6.1-sol`) with every other tool. Tools are async `@function_tool` functions, one per file under `agent/tools/`, that read `RunContextWrapper[AgentDeps]` (or `RequestDeps`, both in `agent/sessions.py`) for the Slack client and session. Both agents set `ModelSettings(truncation="auto")`, so a long session drops its oldest conversation instead of outgrowing the context window.
88

99
**Runs** use `await Runner.run()` from async Bolt listeners. Coding turns allow `MAX_TURNS` model calls, and a turn that uses them all ends with a message through the SDK's `max_turns` error handler, so its history is kept. Each agent's `tool_use_behavior` ends the run early once there's nothing left to do: after `create_code_channel` succeeds for the routing agent, and after `archive_channel` for the coding agent.
1010

1111
**Turns** go through `agent/turns.py`, which doesn't import the SDK. A turn that raises posts a warning and moves the session back to `active`, keeping the history from the last finished turn. Model-written replies use `markdown_text`, since the model writes standard markdown.
1212

13-
**Stopping** sets `session.stopped`. Every code channel tool lists the `session_stopped` tool input guardrail (`agent/guardrails.py`), which skips the call and tells the model to wrap up, and the turn posts nothing when it finishes.
13+
**Stopping** sets `session.stopped`, and so does archiving the channel from Slack. Every code channel tool lists the `session_stopped` tool input guardrail (`agent/guardrails.py`), which skips the call and tells the model to wrap up, and the turn posts nothing when it finishes.
1414

1515
**Conversation history** comes from `result.to_input_list()` and is stored on the `CodeChannelSession` (`agent/sessions.py`), keyed by code channel. Follow-up turns pass `session.history + [{"role": "user", "content": text}]`.
1616

0 commit comments

Comments
 (0)